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

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

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

```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)
- [Compose 3D](/guides/compose-3d.md)
- [Easy AI model hosting setup](/guides/model-hosting.md)