---
title: Variables
url: https://arcana.otnelhq.com/docs/variables
---

# 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`.

### `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.

### `ARCANA_PROVIDER`

- What it does: Selects the LLM provider. Maps to the config key `provider`.
- Notes: Bare model names without a provider prefix (for example `deepseek-v4-flash`) 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 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.
- 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.
- 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.
- 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.
- Status: roadmap. Not wired up in current builds.
- Today: enforcement happens through `allow`/`ask`/`deny` rules per tool plus interactive approval prompts.

## Server & Engine

Arcana can run as a local engine process and serve HTTP. 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.

### `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: The single most important guard on the server surface.

## 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.
- 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`.
- 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 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 during setup.
- Example: `export ARCANA_LICENSE=your-license-key`

### `ARCANA_LICENSE_KEY`

- What it does: License key required before the gateway starts.
- 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 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.

### `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: `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.
- 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.

| Variable | Provider |
| --- | --- |
| `OPENAI_API_KEY` | OpenAI |
| `ANTHROPIC_API_KEY` | Anthropic |
| `GEMINI_API_KEY` | Google Gemini |
| `XAI_API_KEY` | xAI Grok |
| `DEEPSEEK_API_KEY` | DeepSeek |
| `MOONSHOT_API_KEY` / `KIMI_API_KEY` | MoonshotAI (Kimi) |
| `DASHSCOPE_API_KEY` | Alibaba (Qwen) |
| `MISTRAL_API_KEY` | Mistral |
| `OPENROUTER_API_KEY` | OpenRouter |
| `TOGETHER_API_KEY` | Together AI |
| `GROQ_API_KEY` | Groq |
| `FIREWORKS_API_KEY` | Fireworks |
| `NOVITA_API_KEY` | Novita |
| `SAMBANOVA_API_KEY` | SambaNova |
| `COHERE_API_KEY` | Cohere |
| `REPLICATE_API_TOKEN` | Replicate |
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (standard AWS credential pair) |

Free-tier note: some providers (DeepSeek, Gemini) offer free tiers that pair well with the 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.