Configuration

The daemon config file at ~/.orkai/config.yaml — embedded mode, embeddings, MCP, and review providers.

The orkai daemon reads ~/.orkai/config.yaml. On first run, orkai serve walks you through embedding setup and writes this file for you. After that, prefer orkai start for daily use and edit the file only when you need to change providers, ports, or review settings.

Three different config files

This page covers daemon config only. For project indexing and review rules, see Projects & indexing and Review.

View and change settings

Use the CLI for common keys instead of opening the YAML file. Restart the daemon after changes (orkai stop then orkai start, or restart orkai serve if you run in the foreground).

orkai config                              # path + current embedding/annotation summary
orkai config get embedding.provider
orkai config set annotations.enabled true
orkai config help                         # list supported keys

Example (embedded mode)

After first-run setup with a local Ollama embedding model, your file looks roughly like this. Paths and passwords differ on your machine; the structure is what matters.

storage:
  mode: embedded
  dataDir: ~/.orkai/data

service:
  listen:
    tcp:
      enabled: true
      host: 127.0.0.1
      port: 7779
    unix:
      enabled: true
      path: ~/.orkai/orkai.sock
  auth:
    passwords:
      - "<auto-generated>"

embedding:
  provider: ollama          # ollama | openai | none | mock
  model: mxbai-embed-large
  dimensions: 1024
  apiBase: http://127.0.0.1:11434
  cache:
    enabled: true
    path: ~/.orkai/cache/embeddings
    maxEntries: 10000

ingest:
  queueSize: 1000
  workers: 2
  batchSize: 64
  flushIntervalMs: 500
  overflowPolicy: reject

gc:
  enabled: true
  intervalSecs: 10
  batchSize: 100
  gracePeriodSecs: 30

mcp:
  enabled: true
  host: 127.0.0.1
  port: 8787
  v2:
    enabled: true

admin:
  enabled: true
  host: 127.0.0.1
  port: 9090

Everything runs locally: SQLite and files under storage.dataDir. You do not need separate database or search services for the desktop product.

storage

service

How the CLI and SDKs connect to the daemon binary protocol.

If the default port is busy, the daemon may pick another and record it in ~/.orkai/runtime.json. Use orkai status to see active ports.

embedding

Powers semantic search and indexing. Without a working embedding provider, search quality is limited and indexing may skip vector steps.

The first-run wizard sets Ollama or OpenAI based on your choice. Switch later with orkai config set embedding.provider … or by editing the YAML.

ingest

Tuning for background indexing throughput. Defaults are fine for most machines.

gc

Background garbage collection for stale index entries. Enabled by default.

mcp

MCP server your AI assistant connects to. orkai mcp-config reads the live URL and token from the running daemon — you rarely edit this block by hand.

See Daemon & MCP for client setup.

admin

Local HTTP endpoints for health checks and metrics. Used by orkai top and orkai status.

annotations (optional)

AI-generated purpose and insight layers attached to indexed code symbols when enabled here. The annotation pipeline runs in the background after orkai index. Off by default. See Knowledge layer for tags, enriched source, and MCP usage.

orkai config set annotations.enabled true
orkai config set annotations.provider ollama
orkai config set annotations.model qwen2.5-coder:7b-instruct

chat (optional — for review)

LLM providers for orkai review. Distinct from embeddings: review needs a chat model, not an embedding model. The easiest path is orkai review setup, which writes chat.providers[] for you.

chat:
  providers:
    - provider: openai
      model: gpt-4o-mini
      apiKey: sk-...
      default: true
    - provider: ollama
      model: llama3.1:8b
      apiBase: http://127.0.0.1:11434

Each review process in .orkai.yaml can select a provider by model: matching one entry’s model field. Exactly one provider should have default: true. See Review setup.

limits (advanced)

Optional guardrails for concurrent requests and rate limiting. Omit this section unless you hit capacity issues.

debug (advanced)

Enable Go pprof profiling for deep performance investigation. Leave disabled unless you know you need it.