Configuration

Config file location

~/.arcana/config.json

Override with ARCANA_HOME:

export ARCANA_HOME=/custom/path
# Config loaded from /custom/path/config.json

Full config reference

{
  "$schema": "https://arcana.otnelhq.com/schema/config.json",
  "provider": "openai",
  "model": "gpt-4o",
  "utilityModel": "gpt-4o-mini",
  "apiKey": "sk-...",
  "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/.

Cron settings

See Cron for the full scheduled jobs reference.

Skills settings

See Skills for the full skills reference.

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