Set Up the ORQO Desktop App
The ORQO Desktop App is a lightweight menu-bar app that connects directories on your local machine to ORQO. Once connected, those directories appear as Desktop App runtimes in your ORQO dashboard -- agents can read files, write files, and execute commands directly on your machine.
The app connects outward from your computer to ORQO through a WebSocket. No inbound ports, no NAT configuration, no firewall changes needed. It works through any network that allows HTTPS traffic.
Prerequisites
- An ORQO account with access to Settings > API Tokens
- The ORQO Desktop App installed on your machine (macOS, Windows, or Linux)
- Python 3 installed on your machine (required for full tool compatibility)
Steps
1. Create an API token
Navigate to Settings > API Tokens in ORQO. Click Create Token, give it a name (e.g., "Desktop App"), and click Generate.
The token is shown once -- copy it immediately. It looks like orqo_<48 characters>. You cannot retrieve this token later; if you lose it, revoke it and create a new one.
2. Install and launch the desktop app
Download the ORQO Desktop App from the downloads page for your platform:
| Platform | Format |
|---|---|
| macOS | DMG |
| Windows | MSI installer |
| Linux | AppImage |
On first launch, a setup window appears asking for two things:
- ORQO URL -- Your ORQO instance URL (e.g.,
https://orqo.ooopps.com) - API Token -- The token you created in step 1
Enter both and click Connect. The app authenticates with ORQO and moves to the system tray (macOS menu bar / Windows system tray / Linux tray).
3. Add workspace directories
Click the tray icon to open the popover, then click Settings. In the Workspaces section, click Add Workspace and select a directory from your file system.
Each workspace you add becomes a separate runtime in ORQO. Choose directories based on what you want agents to access:
| Use case | Directory to add |
|---|---|
| Obsidian vault | ~/ObsidianVault |
| Local codebase | ~/Projects/my-app |
| Research files | ~/Research/papers |
| Notes and docs | ~/Documents/notes |
Give each workspace a clear name -- this name appears as the runtime name in ORQO.
Only add directories you want agents to access. The app restricts all operations to declared workspaces. Files and directories outside the workspace boundaries are never accessible.
4. Verify in ORQO
Go to Settings > Runtimes in ORQO. Your workspaces should appear as runtimes with the Desktop App provider and a green Running status.
Each runtime shows the workspace name, local path, and connection status. These runtimes are read-only in the ORQO UI -- they're managed entirely by the desktop app.
5. Assign runtimes to skills or stages
Desktop App runtimes are used the same way as any other runtime:
- Via Skills -- Open a skill in Settings > Skills, and select your Desktop App runtime in the Runtime dropdown. Any agent with that skill can access the workspace.
- Via Stages -- In the Workflow Builder, select the runtime on a stage node. All agents in that stage can access the workspace during execution.
Connection Status
The tray icon reflects the current connection state:
| Icon | State |
|---|---|
| Green dot | Connected -- workspaces active and available to agents |
| Yellow dot | Connecting or reconnecting |
| Red dot | Disconnected or error -- check Settings for details |
| Grey dot | Paused by user |
If the connection drops (network change, laptop sleep, ORQO maintenance), the app reconnects automatically with exponential backoff. Runtimes in ORQO temporarily show as stopped and return to running when the app reconnects.
Activity Monitoring
The tray popover shows recent activity -- file reads, directory listings, and command executions performed by agents through the app. The Settings window has a full activity log with timestamps.
This gives you visibility into exactly what agents are doing with your local files.
Security Settings
The app offers three security levels, configured in Settings:
| Setting | Default | Effect |
|---|---|---|
| Require confirmation for write operations | On | The app prompts before any file write |
| Require confirmation for shell commands | On | The app prompts before executing commands |
| Allow unrestricted access | Off | Skip all confirmation prompts (for power users) |
For development workflows where agents frequently write files or run commands, you may want to disable prompts. For sensitive directories, keep them enabled.
The API token is stored in your operating system's secure keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) -- never in plain text on disk.
Use Cases
Obsidian Knowledge Base
Add your Obsidian vault as a workspace. Create a workflow with a research agent that has web search tools and a runtime pointing to the vault. The agent can search the web, read existing vault notes, and write new Markdown files with proper [[backlinks]]. Obsidian picks up the changes instantly.
Local Code Review
Add your project directory as a workspace. Ask Doorkeeper to review today's changes -- it triggers a workflow where an agent runs git diff, reads modified files, and returns a structured code review. The code never leaves your machine except for the LLM analysis.
Document Sync
Add a workspace as a document source to automatically sync files from the local directory into your ORQO knowledge graph. Markdown files, text documents, and other classifiable content are periodically imported and classified.
Troubleshooting
| Issue | Solution |
|---|---|
| Runtime shows "stopped" in ORQO | Check the tray icon. If red, open Settings and verify the connection. If the app is running, try clicking Pause then resuming. |
| "Disconnected" error | The app lost its WebSocket connection. It will reconnect automatically. If persistent, check your network and ORQO URL in Settings. |
| Tools fail with "Python not found" | Install Python 3 on your machine. Tools execute as Python scripts. |
| "Path outside workspace" error | An agent tried to access a file outside the workspace root. This is blocked by design. |
| Token rejected | The API token may have been revoked. Create a new one in Settings > API Tokens. |
What's Next
- Runtimes reference for the full runtime model
- Create a Skill to bundle the runtime with tools
- Connect Document Sources to auto-sync workspace files into the knowledge graph