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 JSON to paste into Cursor, Claude Desktop, Claude Code, or any MCP client:

orkai mcp-config

Output includes the SSE URL and Authorization: Bearer … token. Requires a running daemon and credentials from first-run setup (orkai serve once, then orkai start thereafter).

See Quick start § Connect your AI for per-client paste instructions.

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