> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent-mintlify-f21cea86.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
# 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`):

```env theme={null}
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](/guides/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:

```env theme={null}
DDGS_TIMEOUT=30
DDGS_RETRIES=3
```

## Essential API keys

```env theme={null}
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](https://aistudio.google.com) and [Groq Console](https://console.groq.com).

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

```bash theme={null}
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.

<Note>
  See [LLM orchestration](/concepts/llm) for failover details. See [Security](/concepts/security) for security layers. See [Troubleshooting](/reference/troubleshooting) for common fixes.
</Note>


## Related topics

- [Quickstart: install Arka and run your first command](/quickstart.md)
- [Arka — AI terminal agent documentation](/index.md)
- [Configuration](/guides/configuration.md)
- [Easy AI model hosting setup](/guides/model-hosting.md)
- [Compose 3D](/guides/compose-3d.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.