Configuration, env vars, and API key setup

Arka is on by default for safety, failover, and local-first routing. You only need a .env when you want to override something or add API keys.

Config paths

OS	Config	Cache
Linux	`~/.config/arka/`	`~/.cache/arka/`
macOS	`~/Library/Application Support/arka/`	`~/Library/Caches/arka/`
Windows	`%APPDATA%\arka\`	`%LOCALAPPDATA%\arka\`

Override with ARKA_CONFIG_DIR (or CONFIG_DIR), INSTALL_HOME (legacy ARKA_HOME), or ARKA_CACHE_DIR (or CACHE_DIR). Setting ARKA_CONFIG_DIR=/path/to/my-arka-config moves all user config there — .env, mcp.json, hub/, agent-memory/, skills/, and related paths.

# Show current root + shell export snippet
arka config path

# Initialize a new config directory (no automatic move)
arka config init --dir ~/my-arka-config

# Backup / restore entire config tree
arka config backup -o ~/backups/arka-2026-07-11.tar.gz
arka config restore ~/backups/arka-2026-07-11.tar.gz

# List paths and sizes
arka config list

User config includes .env, charts.yaml, llm-skill-models.json, and skills/ (plugins).

Precedence

Layer	What it is	Wins when
Shell env	`export GEMINI_API_KEY=…`	Already set in process
User `.env`	`~/.config/arka/.env`	Fills unset vars at startup
Dev checkout `.env`	`arka/.env` in a git clone	Fills vars not already set
Legacy fish `.env`	`~/.config/fish/.env`	Still read if present
Code defaults	Built into Python / `config.fish`	When var is missing

Placeholder values like your_gemini_api_key_here are ignored.

Key names

Prefer short names. Legacy ARKA_* keys still work (ARKA_ROUTE_MODE → ROUTE_MODE):

ROUTE_MODE=symbolic
LLM_AUTO_FALLBACK=1
AGENT_SPEAK=1
SECURITY=1

Built-in defaults

Area	Default	Override
Security	All layers on (`SECURITY=1`)	Set any layer to `0`
NL routing	Offline rules first (`ROUTE_MODE=symbolic`)	`ai`, `symbolic_only`, `ai_only`
LLM failover	Auto on 429/401/timeout (`LLM_AUTO_FALLBACK=1`)	`LLM_AUTO_FALLBACK=0`
Key rotation	Rotate backup keys first (`API_KEY_ROTATION=1`)	`API_KEY_ROTATION=0`
Voice TTS	Speak replies (`AGENT_SPEAK=1`)	`AGENT_SPEAK=0`
Wake listener	Off until `arka listen`	`AGENT_WAKE_AUTO=1`
Memory	Cloud when keyed, else local (`MEMORY=auto`)	`local` or `supermemory`
Goal agent	25 steps (`GOAL_MAX_STEPS=25`)	`GOAL_MAX_STEPS=30`
YouTube research	2 videos (`YT_RESEARCH_MAX=2`)	`--limit N` or env
Reminders	1 hour default (`REMIND_DEFAULT=1h`)	pass explicit time
Model label	Show under answers (`SHOW_MODEL=1`)	`SHOW_MODEL=0`

Essential API keys

GEMINI_API_KEY=your_key_here
GROQ_API_KEY=your_key_here
AI_PREFERRED_PROVIDER=gemini
AI_PREFERRED_MODEL=gemini-2.0-flash

Get free-tier keys from Google AI Studio and Groq Console.

Optional extras

Install feature groups as needed:

Extra	Adds
`[chat]`	Web search, Agno, trafilatura, sympy
`[voice]`	vosk, sounddevice
`[pdf]`	PrivateGPT client
`[charts]`	matplotlib
`[drawings]`	Pillow, pymupdf
`[video]`	Pillow, edge-tts
`[all]`	Everything above

Applying changes

arka reload              # re-read .env + config.fish
arka reload --listen     # also restart wake listener

arka setup seeds ~/.config/arka/.env from the package template on first install.

Full reference

Canonical env reference: src/arka/env.example (~500 lines) in the repo.

See LLM orchestration for failover details. See Security for security layers. See Troubleshooting for common fixes.

​Config paths

​Precedence

​Key names

​Built-in defaults

​Essential API keys

​Optional extras

​Applying changes

​Full reference