🚀 Getting Started

Overview

Oryn is a local-first desktop AI coding agent built on Electron and React, backed by a .NET 8 service layer. It pairs a full-featured code editor with a conversational AI agent that can read files, write patches, run terminal commands, and call external tools — all from a single window on your machine. Your source code stays on your machine; the AI model can run locally via Ollama or through a cloud API key you supply. You interact with the agent through a chat panel while the rest of the IDE (file explorer, editor, terminal, git, and more) stays live around it.

How it works

The desktop app is an Electron shell that hosts a React/TypeScript renderer. On launch it connects via SignalR (WebSocket) to the Gateway service running on localhost:7000, which forwards prompts to the Agent API on localhost:7001. The Agent API resolves the active LLM provider at startup — in priority order: Azure AI Foundry, then a direct cloud API key, then a local Ollama instance, then a stub — and streams responses back through the SignalR hub as structured events (text_delta, tool_use, awaiting_approval, session_complete, etc.). Each time the agent wants to mutate a file it fires an awaiting_approval event; you see a diff modal and approve or reject before the write is committed. Your workspace folder path, open tabs, chat history, and model preference are all persisted in the renderer's localStorage so the session survives restarts.

What you can do

How to use it

1. Install prerequisites
   You need .NET 8 SDK, Node.js 20 LTS, and optionally Docker Desktop. Docker is used for Postgres, Redis, and other infrastructure services; if Docker is absent the launcher skips that step and the app runs in a reduced mode. Download .NET 8 from microsoft.com/dotnet and Node.js 20 LTS from nodejs.org.
2. Clone the repository and run the launcher
   Open a terminal in the repository root and run RUN-EVERYTHING.bat (Windows). The script checks that dotnet and node are on PATH, kills any stale instances, builds the three .NET services (Gateway on port 7000, Agent API on 7001, Workspace API on 7002), starts them hidden, waits 25 seconds for them to warm up, installs npm packages for the dashboard and desktop if node_modules is absent, then launches both. The desktop Electron window appears automatically.
3. Complete the onboarding tour
   If this is your first launch the onboarding tour opens automatically. Step through it to learn the keyboard shortcuts: Ctrl+O to open a folder, @ to mention files in chat, and / to trigger slash commands. You can dismiss it at any time and reopen it later via Command Palette (Ctrl+Shift+P) > Show Welcome Tour.
4. Open a folder
   Click Open Folder in the title bar or press Ctrl+O. A native OS dialog appears. Select any project directory. Oryn indexes the folder locally for fuzzy file search and @-mention completion — no files are uploaded. The folder name appears in the title bar and the file explorer populates on the left.
5. Configure your AI model
   Open Settings with Ctrl+, and navigate to AI Provider. Choose your provider: paste an API key for a cloud provider (Anthropic, OpenAI-compatible, Gemini, Groq, xAI, or GLM) or enter your Azure AI Foundry endpoint and key, or enter the Ollama base URL (default http://localhost:11434) for fully local inference. Click Save; the backend picks up the new credentials immediately. The status bar shows the active model label.
6. Type your first prompt
   The chat panel is on the right. Type a message and press Enter (or Shift+Enter for a newline). The agent streams its response token-by-token. If it needs to read or write a file you see a tool-call card; file writes pause for your approval in a diff modal unless you have auto-approve enabled.
7. Review and approve file changes
   When the agent proposes a file edit, an approval modal shows a side-by-side diff of the original and proposed content. Click Approve to write the file, or Reject to skip. Approved writes are snapshotted as checkpoints you can undo later from the chat overflow menu.

Example

Admin notes

Related