Daemon & MCP

Run the local daemon, inspect health, and connect your AI assistant.

The orkai daemon is a single local process: SQLite storage, vector search, MCP server, and admin UI. Everything runs on your machine under ~/.orkai/.

Daily use: orkai start and orkai stop — the daemon stays running in the background on macOS and Linux while you work. Use orkai serve only for first-run setup or when you want logs streaming in your terminal.

orkai start / orkai stop

Start the daemon in the background. It keeps running after you close the terminal — this is the command to use day to day. 

orkai start    # background daemon (macOS, Linux)
orkai stop     # stop background daemon
orkai status   # confirm it is running

After a reboot or upgrade, run orkai start again. Use orkai logs or orkai logs -f to read output without tying up a terminal the way serve does.

orkai serve

Run the daemon in the foreground — logs print live in your terminal. Use this:

  • First run only — interactive wizard writes ~/.orkai/config.yaml
  • Debugging — when you want to watch startup and requests in real time
orkai serve

Requires a valid license and an interactive terminal on first run. Once setup is done, prefer orkai start for normal use.

orkai logs

orkai logs      # recent output
orkai logs -f   # follow live (like serve, without blocking the daemon)

orkai status

Check whether the daemon is running, which ports it bound, and entity counts.

orkai status

Ports come from ~/.orkai/runtime.json when the daemon is alive — important when auto-fallback picks a non-default port.

orkai top

Live metrics from the admin endpoint: throughput, latency, errors, ingest queue, backend health.

orkai top       # snapshot
orkai top -f    # refresh every 2s (Ctrl-C to quit)

orkai open

Open the local web UI in your default browser. Requires a running daemon (orkai start or orkai serve).

orkai open

On first open in embedded mode, the UI asks for a 4-digit PIN instead of the auto-generated credentials in ~/.orkai/credentials (those stay on disk; the server validates your PIN and creates the session). Forgot the PIN? Delete ~/.orkai/pin and reopen the app to set a new one.

orkai mcp-config

Print ready-to-paste MCP configuration for your AI client. Requires a running daemon and credentials from first-run setup. 

orkai mcp-config    # all clients (default)
orkai mcp-config --client cursor

Full per-client walkthrough — Cursor, Claude Desktop, Claude Code, Codex, OpenCode, ChatGPT, remote mode, and troubleshooting — is on MCP — connect your AI.

orkai config

View or set daemon configuration (embedding provider, annotations, and other keys in ~/.orkai/config.yaml). See Configuration for the full file reference. 

orkai config get embedding.provider
orkai config set annotations.enabled true