Variables Reference

This page lists every Arcana environment variable, inspected from the shipped documentation and explained in detail. Environment variables override values in ~/.arcana/config.json, which makes them the fastest way to change behavior without editing files.

Two warnings before the list. First, anything marked dev only weakens a security boundary on purpose. Never use those flags against untrusted code. Second, unknown config keys are rejected with a validation error, so typos fail fast instead of being silently ignored.

Core Configuration

These variables control where Arcana finds its configuration. They matter most in CI, containers, and shared machines where you cannot or do not want to touch ~/.arcana. See Configuration for the full file format.

ARCANA_HOME

• What it does: Moves the root directory of the legacy layout. Config, state, skills cache, and data files all resolve under this path instead of ~/.arcana.
• Default: ~/.arcana
• Example: export ARCANA_HOME=/custom/path
• Notes: Useful for isolated test environments and for running two independent Arcana setups side by side.

ARCANA_CONFIG

• What it does: Points at one explicit config file, bypassing normal discovery.
• Default: none. Discovery order applies.
• Example: export ARCANA_CONFIG=/etc/arcana/prod.json
• Notes: Takes precedence over user and project config. Pair it with ARCANA_DISABLE_PROJECT_CONFIG=1 when you want exactly one source of truth.

ARCANA_CONFIG_DIR

• What it does: Points at an explicit config directory rather than a single file.
• Default: none.
• Notes: Handy when tooling manages a directory of layered config fragments.

ARCANA_CONFIG_CONTENT

• What it does: Passes the entire config as inline JSON through the environment.
• Default: none.
• Example: export ARCANA_CONFIG_CONTENT='{"provider":"openai","model":"gpt-5-mini"}'
• Notes: Highest priority of all sources. Ideal for ephemeral CI jobs that have no filesystem state at all. Mind your shell quoting.

ARCANA_DISABLE_PROJECT_CONFIG

• What it does: When set to 1, project-level arcana.json files are ignored completely.
• Default: unset. Project config loads when present.
• Notes: Protects you from a cloned repository shipping config you did not review. Recommended for untrusted checkouts.

ARCANA_PURE

• What it does: When set to 1, skips all external config, skills, and state. Arcana runs only on its built-in defaults.
• Default: unset.
• Notes: Built for reproducible runs and bug reports. If a problem disappears under ARCANA_PURE=1, the cause lives in your config, skills, or state rather than in the binary.

Model & Runtime

These choose what model answers and how much machinery sits around it. Provider-specific keys live further down on this page.

ARCANA_PROVIDER

• What it does: Selects the LLM provider. Maps to the config key provider.
• Default: whatever user config specifies.
• Notes: Bare model names without a provider prefix (for example deepseek-v4-flash instead of provider/model) resolve across all configured providers automatically.

ARCANA_MODEL

• What it does: Sets the model ID. Maps to the config key model.
• Example: export ARCANA_MODEL=deepseek-v4-flash
• Notes: Overridden per session inside the TUI model picker. Unattended runs such as cron jobs rely entirely on this value.

ARCANA_API_KEY

• What it does: Generic provider API key. Maps to the config key apiKey.
• Notes: Use the provider-native variable (see Provider API Keys below) when you mix providers. Keep keys out of shell history: prefer a dotenv file or your system keychain over inline exports.

ARCANA_UTILITY_MODEL

• What it does: Names a cheap model for utility work such as chat titles and summaries, keeping the main model budget for real tasks.
• Example: export ARCANA_UTILITY_MODEL=gpt-4o-mini
• Notes: Small savings per call, large savings across a session.

ARCANA_ML_RUNTIME

• What it does: Set to 1, enables the signal engine: quality gates and automatic model switching. See Signal Engine.
• Default: off.
• Notes: Opt-in because it changes routing behavior mid-session. Try it once you have more than one provider configured.

ARCANA_LOG_LEVEL

• What it does: Controls logging verbosity for diagnostics. See Troubleshooting.
• Notes: Raise it when filing a bug, then lower it again. Verbose logs can contain prompt and tool output.

ARCANA_AUTONOMY

• What it does: Intended selector for the five-mode autonomy ladder described in Autonomy Modes.
• Status: roadmap. Not wired up in current builds.
• Today: enforcement happens through allow/ask/deny rules per tool plus interactive approval prompts, and mode switching happens through permission policy rather than this variable.

Server & Engine

Arcana can run as a local engine process and serve HTTP. These variables control that surface. Anything beyond loopback needs authentication configured, or you are hosting an open AI endpoint on your network.

ARCANA_ENGINE_BASE_URL

• What it does: Tells client commands where the engine HTTP endpoint lives.
• Default: http://localhost:4096
• Notes: Point it at a remote engine only when that endpoint is authenticated and encrypted.

ARCANA_DEPLOYMENT_MODE

• What it does: Selects the deployment profile: LOCAL, HYBRID, or ENTERPRISE.
• Default: LOCAL.
• Notes: Gated features such as enterprise consoles expect modes other than LOCAL. Wrong values fail validation at startup.

ARCANA_SERVER_USERNAME

• What it does: Sets the username required by non-loopback arcana serve.
• Default: arcana

ARCANA_SERVER_PASSWORD

• What it does: Sets the password required by non-loopback arcana serve. Binding beyond loopback without it is refused.
• Notes: This is the single most important guard on the server surface. Do not relax it on a shared network.

Trust & Security Boundaries

Workspace trust stops a cloned repository from running tools with your credentials before you have reviewed it. Gateway allowlists stop unapproved platforms from connecting. Three of these four variables deliberately weaken those boundaries. They exist for development loops and CI against code you control.

ARCANA_TRUST_WORKSPACE

• What it does: Set to 1, marks the workspace trusted without an interactive prompt.
• Use case: CI pipelines where no human can answer the trust dialog.
• Risk: every checkout in that runner is auto-trusted. Only enable on ephemeral, single-job runners.

ARCANA_DISABLE_WORKSPACE_TRUST

• What it does: Set to 1, removes trust checking entirely. Dev only.
• Risk: highest of the four. Never set it on machines that open untrusted repositories.

ARCANA_GATEWAY_OPEN

• What it does: Set to 1, allows empty platform allowlists in the gateway. Local dev only. See Gateway.
• Risk: any platform can connect while it is set. Turn it off when the demo ends.

ARCANA_WHATSAPP_INSECURE

• What it does: Set to 1, skips WhatsApp signature verification. Local dev only.
• Risk: messages can be spoofed while verification is off. Never combine with a public gateway.

Skills

ARCANA_SKILLS_DIRS

• What it does: Adds extra skill directories, separated by ;. Maps to the config key skillsDirs. See Skill Creation.
• Example: export ARCANA_SKILLS_DIRS="$HOME/team-skills;$HOME/client-acme"
• Notes: Directories are searched in order. Earlier entries win name conflicts.

Licensing, Proxy & Admin

Licensed features (gateway, enterprise consoles, hosted proxy) authenticate through these. Treat every value here as a secret: do not commit them, do not echo them into logs.

ARCANA_LICENSE

• What it does: Supplies your license key for licensed features during setup. See Quick Start.
• Example: export ARCANA_LICENSE=your-license-key

ARCANA_LICENSE_KEY

• What it does: License key required before the gateway starts. See Gateway.
• Notes: The gateway refuses to boot without a valid value present.

ARCANA_PROXY_KEY

• What it does: Authenticates you to the hosted proxy.
• Default discovery: auto-loaded from ~/.arcana/proxy_key when the variable is not set.

ARCANA_ADMIN_KEY / ARCANA_ADMIN_KEYS

• What they do: Short secret(s) accepted by the admin console for operator authentication.
• Notes: Rotate them like passwords. Prefer the JWT-based sign-in path described in Admin Console where available.

ARCANA_ADMIN_TOKEN

• What it does: Bearer token for enterprise console administration.
• Notes: Scoped to enterprise deployments (ARCANA_DEPLOYMENT_MODE other than LOCAL).

Browser Automation

The built-in browser tool has its own variable family. Each one narrows or hardens what the agent may do with a real browser. See Browser Automation.

AGENT_BROWSER_ALLOWED_DOMAINS

• What it does: Restricts navigation to the listed domains. Everything else refuses to load.
• Notes: The strongest single control here. Set it whenever the task touches known sites only.

AGENT_BROWSER_CONFIRM_ACTIONS

• What it does: Gates dangerous actions such as eval() and file downloads behind explicit confirmation.

AGENT_BROWSER_CONTENT_BOUNDARIES

• What it does: Limits which parts of a page the agent may read, keeping sensitive regions out of the model context.

AGENT_BROWSER_ENCRYPTION_KEY

• What it does: Encrypts persisted browser sessions at rest.
• Notes: Without it, saved sessions (cookies included) sit on disk in the clear.

AGENT_BROWSER_IDLE_TIMEOUT_MS

• What it does: Shuts the browser down after this many idle milliseconds.
• Example: "AGENT_BROWSER_IDLE_TIMEOUT_MS": "3600000" (one hour).

AGENT_BROWSER_MAX_OUTPUT

• What it does: Caps characters returned from a page (example: 50000), protecting context from huge documents.

Local Providers

OLLAMA_HOST

• What it does: Standard Ollama variable. Arcana's Ollama provider connects to whatever endpoint it names. Models are auto-discovered in the picker. See Ollama.
• Default: Ollama's own default (127.0.0.1:11434).
• Example: OLLAMA_HOST=http://192.168.1.100:11434 arcana targets a LAN Ollama box.

Provider API Keys

Each provider accepts its native key variable. Arcana reads these directly, so you can mix providers without touching config. Set only the ones you use. Full setup lives under Providers.

Free-tier note: some providers (DeepSeek, Gemini) offer free tiers that work well with the free tier guide. See Free Tier Guide.

Resolution Order

When several sources define the same setting, Arcana resolves them top down and the first hit wins:

1. ARCANA_CONFIG_CONTENT (inline JSON)
2. ARCANA_CONFIG / ARCANA_CONFIG_DIR (explicit paths)
3. Project arcana.json (unless ARCANA_DISABLE_PROJECT_CONFIG=1)
4. User config at ARCANA_HOME or ~/.arcana/config.json
5. Built-in defaults

Within a single source, an environment variable beats the config key it maps to (for example ARCANA_MODEL beats "model"). Unknown keys fail validation loudly, which is deliberate: silent typos are how credentials end up pointed at the wrong place.