Configuration

Arcana is configured through JSON config files — a project-level arcana.json plus an optional global file. Most settings have sensible defaults and can be overridden with environment variables.

Config file location

Arcana merges configuration from three layers, later winning:

The legacy layout is still loaded: ~/.arcana/config.json, with the root overridable via ARCANA_HOME:

export ARCANA_HOME=/custom/path
# Legacy config is then loaded from /custom/path/config.json

Escape hatches: ARCANA_CONFIG / ARCANA_CONFIG_DIR / ARCANA_CONFIG_CONTENT point config at an explicit path or inline JSON, and ARCANA_DISABLE_PROJECT_CONFIG=1 ignores project files entirely. Unknown keys are rejected with a validation error.

Full config reference

{
  "$schema": "https://arcana.otnelhq.com/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": "openai",
  "utilityModel": "gpt-4o-mini",
  "apiKey": "sk-...",
  "default_agent": "primary",
  "instructions": ["Always run tests after refactoring"],
  "agent": {
    "reviewer": { "description": "Code review agent", "model": "anthropic/claude-opus-4" }
  },
  "permission": {
    "edit": "allow",
    "bash": "ask",
    "webfetch": "deny"
  },
  "mcp": {
    "browser": { "type": "local", "command": ["agent-browser", "mcp", "--tools", "core"], "enabled": true }
  },
  "dataDir": "~/.arcana/data",
  "skillsDirs": ["~/.arcana/skills"],
  "memory": {
    "enabled": true,
    "maxSessions": 1000
  },
  "cron": {
    "enabled": true,
    "intervalSeconds": 60
  },
  "gateway": {
    "telegram": { "token": "...", "allowedUsers": ["12345678"] },
    "discord": { "token": "...", "allowedChannels": ["987654321"] },
    "slack": { "botToken": "xoxb-...", "signingSecret": "...", "allowedChannels": ["C0123"] },
    "whatsapp": { "phoneNumberId": "...", "accessToken": "...", "appSecret": "...", "allowedUsers": ["14155551234"] }
  }
}

Core settings

Provider auto-detection

If neither provider nor model is set in the config or environment, Arcana auto-detects from available API keys using the models.dev catalog (200+ models across 33 providers).

# Set a provider key — Arcana detects it automatically
export OPENAI_API_KEY=sk-...
arcana run "hello"  # Uses OpenAI automatically

Memory settings

Memory stores conversation history, extracted facts, and skill usage stats in SQLite under ~/.arcana/data/.

Session compaction

Long sessions auto-summarize near the context limit (default 85%).

{
  "compaction": {
    "auto": true,
    "threshold_percent": 85,
    "intra": true
  }
}

Set "intra": false to only compact between user turns. Set "auto": false to disable all auto compact (manual /compact still works).

Cron settings

Skills settings

Gateway settings

Configure chat platform adapters. See Gateway for full setup instructions.

Environment variables

All config file settings can be overridden with environment variables.

Provider-specific env vars

Use arcana doctor to confirm which keys are detected.

Data directory

Default: ~/.arcana/data/

Trust and security settings