Desktop Configuration

The desktop app uses the same reeve.json configuration file as the CLI gateway. Changes made in the Cockpit UI or by editing the file directly take effect on next gateway restart.

Config File Location

~/Library/Application Support/Reeve/reeve.json

If you previously used the CLI, the app also checks ~/.reeve/reeve.json and uses whichever it finds first.

LLM Providers

The most important configuration — without an LLM key, agents can't respond.

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-api03-..."
      },
      "openai": {
        "apiKey": "sk-..."
      }
    },
    "default": "claude-sonnet-4-6"
  }
}

Fallback Chain

When the primary provider fails (rate limit, outage), Reeve falls back to the next provider in the chain. Configure the priority order in Settings → Models or in the config:

{
  "models": {
    "fallback": ["anthropic", "openai", "openrouter"]
  }
}

Workspace Path

The workspace is where agents store their configuration, memory, and context files. Default:

~/reeve

Change it in the config:

{
  "agents": {
    "defaults": {
      "workspace": "/path/to/your/workspace"
    }
  }
}

The workspace directory contains:

~/reeve/
  ├── AGENTS.md          # Agent behavior instructions
  ├── SOUL.md            # Agent personality/identity
  ├── MEMORY.md          # Long-term memory
  ├── memory/            # Daily memory logs
  │   ├── 2026-03-01.md
  │   └── 2026-03-02.md
  └── USER.md            # User preferences

Agent Configuration

Default Model

Set the default model for all agents:

{
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-6"
    }
  }
}

Heartbeat

Enable periodic autonomous check-ins:

{
  "agents": {
    "defaults": {
      "heartbeat": { "every": "2h" }
    }
  }
}

Set to null to disable heartbeats entirely.

Sandbox Mode

Control file system and command restrictions:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "enabled": true,
        "mode": "non-main"
      }
    }
  }
}

"non-main" sandboxes group/channel sessions while leaving your main chat unrestricted.

Web Search

Enable web search for agents by adding a Brave Search API key:

{
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "apiKey": "BSA..."
      }
    }
  }
}

Get a free API key at brave.com/search/api.

Gateway Settings

Port

The gateway listens on port 18789 by default. Change it:

{
  "gateway": {
    "port": 18789
  }
}

Auth Token

Secure the gateway API with a token:

{
  "gateway": {
    "auth": {
      "token": "your-secret-token"
    }
  }
}

When set, all API requests must include this token.

Applying Changes

Most settings take effect immediately via the Cockpit UI (no restart needed). For changes made directly to reeve.json:

• Model keys, tool config — Restart the gateway (quit and relaunch the desktop app)
• Agent config — Takes effect on next session start
• Workspace path — Requires app restart