Skip to main content

Desktop app

The Ethos desktop app is an Electron shell that provides a native Mac, Windows, and Linux interface with the same agent capabilities as the CLI and web dashboard. It runs in local mode (embedded server) or remote mode (connected to an external Ethos instance).

Source​

  • apps/desktop/src/main/index.ts — Electron main process: window lifecycle and startup mode
  • apps/desktop/src/main/serve.ts — embedded web-api process for local mode
  • apps/desktop/src/main/keychain.ts — auth token storage via Electron safeStorage
  • apps/desktop/src/renderer/ — the web UI rendered inside the native window

Synopsis​

The desktop app wraps the Ethos web UI in a native window. It provides:

  • Full agent chat with streaming responses and tool events
  • Settings panel for personality, MCP server, and connection management
  • Local mode with an embedded web-api process (no separate server required)
  • Remote mode connecting to any running Ethos server instance
  • Status bar indicator showing connection state

All sessions and memory use the same ~/.ethos/ directory as the CLI.

Installation​

Download the installer for your platform from the releases page.

PlatformFormatNotes
macOS.dmgUniversal binary (Intel + Apple Silicon). Drag to /Applications.
Windows.exe installerStandard Windows installer. Adds a Start Menu entry.
Linux.AppImage, .debAppImage is portable; .deb integrates with apt.

Local mode​

Local mode is the default. The app starts an embedded web-api process, equivalent to running ethos serve --web from the CLI. No separate server installation is required.

Sessions are stored in ~/.ethos/ — the same directory the CLI uses. Switching between the desktop app and ethos chat from the same working directory shares conversation history through the standard session keying model.

Remote mode​

Connect to a remote Ethos server instead of running locally. The connection target is any running ethos serve --web or ethos run-all instance — a VPS, home server, or team deployment.

Configure the connection:

  1. Open Settings → Connection.
  2. Select Remote.
  3. Enter the server URL and auth token.
  4. Select Test Connection to verify.
  5. Select Save.
┌─────────────────────────────────────┐
│  Connection Settings                │
├─────────────────────────────────────┤
│                                     │
│  Mode:  ○ Local   ● Remote          │
│                                     │
│  Server URL                         │
│  ┌─────────────────────────────────┐│
│  │ https://ethos.example.com       ││
│  └─────────────────────────────────┘│
│                                     │
│  Auth Token                         │
│  ┌─────────────────────────────────┐│
│  │ ••••••••••••••••••••            ││
│  └─────────────────────────────────┘│
│  Stored in OS keychain              │
│                                     │
│  [ Test Connection ]  [ Save ]      │
│                                     │
│  Status: ● Connected (142ms)        │
│                                     │
└─────────────────────────────────────┘

Security​

The auth token is stored in the OS keychain via Electron safeStorage. It is never written to config files or stored on disk in plaintext.

ConcernHandling
Token storageOS keychain (safeStorage) — encrypted at rest by the OS
TransportHTTPS recommended for all remote connections
Token transmissionSent only over the configured connection — not logged, not included in crash reports

Status bar indicator​

The status bar shows the current connection state.

IndicatorMeaning
Green dot — "Local"Running the embedded web-api process
Blue dot — "Remote: hostname"Connected to a remote server
Red dot — "Disconnected"Connection lost; the app is attempting to reconnect

Switching between local and remote​

Open Settings → Connection and toggle between Local and Remote. Switching modes restarts the agent session.

graph LR
    A[Desktop App] --> B{Mode}
    B -->|Local| C[Embedded web-api]
    B -->|Remote| D[HTTPS] --> E[Remote Ethos Server]

See also​