Desktop App

The Octipus desktop app is a thin client built with Tauri v2 (Rust) and a Next.js static export. It connects to any running Octipus backend — it does not embed or start a backend of its own.

Property	Value
Framework	Tauri v2 + Next.js (static export)
Source	`web/src-tauri/`
Launch command	`octi desktop`
Rebuild command	`octi desktop --build`
Authentication	Bearer token (same `octi_…` api tokens)
Platforms	Linux, macOS, Windows
Default window	1400 × 900, resizable

Prerequisites

The desktop app requires a Rust toolchain and Tauri v2 system libraries (e.g. webkit2gtk-4.1 on Linux) that are not installed by the core bun install. Install them with the provided script:

scripts/install-desktop-deps.sh

Or fold desktop deps into the one-shot installer by adding --desktop:

curl -fsSL https://raw.githubusercontent.com/PatriceA/octipus/main/scripts/install.sh | bash -s -- --desktop

The script is idempotent — re-running it after the deps are already present is a no-op.

Platform library reference

Platform	Package(s) needed
Arch Linux	`webkit2gtk-4.1`, `libayatana-appindicator`, `gtk3`
Debian / Ubuntu	`libwebkit2gtk-4.1-dev`, `libgtk-3-dev`, `libayatana-appindicator3-dev`
Fedora	`webkit2gtk4.1-devel`, `gtk3-devel`
openSUSE	`libwebkit2gtk-4_1-0`, `gtk3-devel`
macOS	Xcode Command Line Tools (`xcode-select --install`)
Windows	WebView2 (ships with Windows 11 / Edge; Visual Studio Build Tools for Rust)

Launching the desktop app

octi desktop

This opens the native window. The app will prompt you for a backend URL and a bearer token on first launch.

To rebuild the app after code changes:

octi desktop --build

Connecting to a backend

The desktop app is a client — it needs a running Octipus backend to connect to. This can be:

Local — your own octi start on the same machine (backend on port 3005, web on port 3007)
Remote / team — any accessible Octipus instance (e.g. a Docker deployment)

Enter the backend URL (e.g. http://localhost:3005) and a personal octi_… api token in the login screen. Generate api tokens in Settings → API Tokens from the web UI.

Authentication

The desktop app authenticates via bearer token rather than cookies. All other authentication mechanisms (TOTP, passkeys) flow through the web UI; the desktop client uses the resulting octi_… token.

The MCP bootstrap token at ~/.octipus/mcp-token is not used by the desktop client — use a personal api token so audit attribution stays correct.

What you get

Because the desktop app wraps the same Next.js web UI as a static export, it has access to all the same pages as the Web UI, including:

Full chat with the orchestrator
Agent monitoring and event timelines
Knowledge base, documents, and research
Models, topics, hooks, and settings configuration
Admin and multi-user management

The one difference from the hosted web UI is routing: the static export uses query-parameter routing for dynamic routes (e.g. /agents?id=… instead of /agents/…).

Development

The Tauri app lives at web/src-tauri/. The Tauri config is at web/src-tauri/tauri.conf.json. The Next.js dev server for the desktop runs on port 3008 (separate from the standard web UI on 3007):

cd web
bun run tauri:dev       # dev mode with hot reload
bun run tauri:build     # production build

Or use octi desktop --build from the repo root.

Troubleshooting

“webkit2gtk not found” on Linux: run scripts/install-desktop-deps.sh (or the equivalent package manager command for your distro from the table above).

Blank window on first launch: the static export needs to be built first. Run octi desktop --build once, then octi desktop for subsequent launches.

“Cannot connect to backend”: confirm octi start is running and the backend URL you entered matches (http://localhost:3005 by default). The desktop app does not start a backend — it must already be running.

Login fails / 401 errors: ensure you are using a personal octi_… api token (from Settings → API Tokens), not your password or the MCP bootstrap token.