Configuration, env vars, and API key setup

Configure Arka using environment variables, .env files, and config paths, with precedence rules for overriding defaults and adding API keys.

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
Model policy	Try local before hosted (ARKA_MODEL_POLICY=local-first)	hosted-first, local-only, hosted-only (see Find free models)
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
Web search timeout	20 s per DuckDuckGo call (DDGS_TIMEOUT=20)	any integer ≥ 5
Web search retries	2 attempts before giving up (DDGS_RETRIES=2)	any integer ≥ 1

Web search failures are non-fatal: if DuckDuckGo times out or errors on every retry, chat logs the error and answers from model knowledge instead of stalling. Tune both knobs when you’re on a slow or flaky network:

DDGS_TIMEOUT=30
DDGS_RETRIES=3

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.