Desktop App¶
The Cortex desktop app is a native window (built with Tauri v2) that
wraps the Cortex web workbench. It connects directly to any running Cortex server using the
HTTP tRPC transport with a clientToken — no local proxy or sidecar required.
Installation¶
Download the latest release for your platform from the GitHub Releases page.
Linux¶
AppImage (any distribution):
Debian / Ubuntu (.deb):
System prerequisites (Ubuntu 22.04 +):
Most Ubuntu/Debian desktops already have these. If the app fails to start with a missing-library error, install them with the command above.
macOS¶
Download Cortex_*_x64.dmg (Intel) or Cortex_*_aarch64.dmg (Apple Silicon).
- Open the
.dmgfile. - Drag Cortex to your Applications folder.
- Open Cortex from Applications or Spotlight.
On first launch macOS may warn "Apple cannot verify this developer." Click Open Anyway in System Settings → Privacy & Security.
Windows¶
Download Cortex_*_x64-setup.exe. Run the installer and follow the prompts.
Cortex appears in the Start menu after installation.
WebView2 requirement: Windows 10 / 11 normally includes the WebView2 runtime. If the app fails to launch with a WebView2 error, download the Evergreen bootstrapper from Microsoft.
Prerequisites on the server side¶
The desktop app talks to the Cortex server's Web UI HTTP endpoint over HTTP or HTTPS. This endpoint is opt-in — you must enable it before the desktop can connect.
The endpoint is served by the server's in-core Web UI transport, which it loads on demand only
when CORTEX_UI_HTTP is set (it carries @trpc/server + jose and the SPA host — runtime-lazy, so
they never load for a Slack/TUI-only server). Enabling it is the same one-line flag as before —
nothing changes for the desktop app, which still authenticates with a bearer clientToken. The
same endpoint also powers the browser workbench; see Browser Access & Deployment.
Add the following to ~/.cortex/config/.env on the machine running the Cortex server:
CORTEX_UI_HTTP=1 # enables the tRPC HTTP + SSE endpoint
CORTEX_UI_PORT=3004 # optional; defaults to 3004
Then restart the Cortex daemon:
If you expose the endpoint through a tunnel (recommended for remote access), point the tunnel at the port above and use the resulting HTTPS URL when connecting from the desktop app.
First-run: connecting to your server¶
The first time you launch Cortex desktop, the connection screen appears:
┌─────────────────────────────────────────────────────────┐
│ cortex-desktop │
│ │
│ server url │
│ ┌──────────────────────────────────────────────────┐ │
│ │ https://cortex.example.com │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ client token │
│ ┌──────────────────────────────────────────────────┐ │
│ │ •••••••••••••••••• │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ [test connection] [connect →] │
└─────────────────────────────────────────────────────────┘
Step 1 — Enter the Server URL¶
Enter the HTTP/HTTPS URL where your Cortex Web UI endpoint is reachable, for example:
- Same machine, no tunnel:
http://localhost:3004 - Remote server via Cloudflare tunnel:
https://cortex-ui.your-domain.com
Step 2 — Enter the Client Token¶
The client token is the shared secret your server uses to authenticate Cortex clients
(the same token in ~/.cortex/config/.env as CORTEX_TOKEN). You can retrieve it with:
Step 3 — Test the connection¶
Click test connection. The app sends a lightweight probe to <serverUrl>/trpc with the
token header.
- Connected (green) — server is reachable and the token is valid.
- Unauthorized (amber) — server is reachable but the token is wrong.
- Network error (red) — the URL is unreachable (server down, tunnel not running, wrong URL).
Step 4 — Connect¶
Click connect →. The app:
- Saves the credentials to your OS keychain (macOS Keychain, Windows Credential Manager, or Linux SecretService / GNOME Keyring).
- Opens the workbench.
On all subsequent launches, Cortex reads the stored credentials and goes directly to the workbench — the connection screen is skipped.
Usage¶
Once connected, you have access to the full Cortex workbench:
Main workbench¶
The workbench is a three-panel layout:
| Panel | Contents |
|---|---|
| Left rail | Project/session navigator. Switch projects and session archives. |
| Center | Conversation: thread steps, tool calls, assistant output, approval prompts. |
| Right panel | Active threads/tasks/machines; cost bar; step-detail tree. |
Thread detail¶
Click any thread card in the right panel to open the thread detail view — a full step-by-step trace of the agent's plan, execution, and sub-dispatches, with per-step timing and cost.
⌘K / Ctrl+K — Command palette¶
Press ⌘K (macOS) or Ctrl+K (Windows/Linux) to open the command palette. Type to filter
across sessions, threads, and tasks. Press Enter to navigate; Escape to close.
Execution log drawer¶
Click a running execution pill in the right panel or thread detail to open the execution log drawer — a live-streaming view of the execution's stdout/stderr. Logs stream in real time via SSE. A Kill button cancels the execution.
Project and archive switcher¶
The left rail shows the current project. Click the project name to open the project switcher and pick a different project. Click the session archive icon to switch to historical archive view.
Task popup¶
Click any task row in the right panel or command palette to open the task popup, showing the
task's full description, done-when criteria, status, and dependency chain.
Overview¶
The Overview tab in the right panel shows system-wide cost, scheduled tasks, recent executions, and throughput charts.
Switching to a different server¶
A Switch button appears in the bottom-right corner of the workbench window when you move the mouse. Clicking it:
- Clears the stored credentials from the OS keychain.
- Returns to the connection screen.
You can then enter a different server URL and token.
How the connection works¶
The desktop app bypasses the browser's same-origin restriction by using:
- tRPC HTTP batch over
POST <serverUrl>/trpcfor all queries and mutations. Every request carries thex-cortex-tokenheader. - SSE subscriptions via an EventSource ponyfill (fetch-based) that can set custom request headers. Real-time thread and execution updates arrive without polling.
This architecture means the desktop app can connect to any Cortex server on any machine — local or remote — as long as the Web UI endpoint is reachable.
Troubleshooting¶
"Unauthorized" on test connection
The client token is wrong. Check CORTEX_TOKEN in ~/.cortex/config/.env on the server.
"Network error" on test connection
- Confirm the server is running:
cortex daemon(or checksystemctl --user status cortex). - Confirm
CORTEX_UI_HTTP=1is set in the server's.envand the server was restarted after adding it. - Check that the URL is reachable:
curl <serverUrl>/trpcshould return a tRPC error (not a connection-refused error). - If using a tunnel, confirm the tunnel is up and the route points to the correct port.
Credentials lost on restart (Linux headless servers)
On headless Linux servers without a SecretService daemon (e.g., servers without GNOME Keyring running), the OS keychain is unavailable. Credentials survive for the current session only (stored in process memory) and are lost when the app exits.
To work around this, set environment variables before launching the app:
These env vars seed the AppState at startup and bypass the keychain check.
App window does not open (Wayland)
Tauri v2 supports Wayland. If the window does not appear, try forcing X11 compatibility: