> ## Documentation Index
> Fetch the complete documentation index at: https://afk.arpan.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Environment variable reference for AFK defaults and backend configuration.

AFK is configured primarily through code. Environment variables provide fallback defaults for LLM settings, memory backends, queues, and prompt directories. **Runtime configuration APIs always take precedence.**

<Note>
  All variables are optional. If unset, AFK uses the defaults listed below.
</Note>

## LLM defaults

These variables configure the default LLM provider and behavior. They are read by `LLMSettings.from_env()` at startup.

| Variable                        | Default   | Description                                                   |
| ------------------------------- | --------- | ------------------------------------------------------------- |
| `AFK_LLM_PROVIDER`              | `litellm` | Default provider id (`openai`, `litellm`, `anthropic_agent`)  |
| `AFK_LLM_PROVIDER_ORDER`        | *(none)*  | Comma-separated provider preference order for routing helpers |
| `AFK_LLM_MODEL`                 | `gpt-5.5` | Default model name                                            |
| `AFK_EMBED_MODEL`               | *(none)*  | Embedding model for vector operations                         |
| `AFK_LLM_API_BASE_URL`          | *(none)*  | Provider API base URL                                         |
| `AFK_LLM_API_KEY`               | *(none)*  | Provider API key                                              |
| `AFK_LLM_TIMEOUT_S`             | `30`      | Request timeout in seconds                                    |
| `AFK_LLM_STREAM_IDLE_TIMEOUT_S` | `45`      | Stream idle timeout in seconds                                |
| `AFK_LLM_MAX_RETRIES`           | `3`       | Retry attempts on transient failures                          |
| `AFK_LLM_BACKOFF_BASE_S`        | `0.5`     | Exponential backoff base in seconds                           |
| `AFK_LLM_BACKOFF_JITTER_S`      | `0.15`    | Random jitter added to backoff                                |
| `AFK_LLM_JSON_MAX_RETRIES`      | `2`       | Structured output repair attempts                             |
| `AFK_LLM_MAX_INPUT_CHARS`       | `200000`  | Input truncation ceiling in characters                        |

<Tip>
  **API keys for specific providers** (e.g. `OPENAI_API_KEY`,
  `ANTHROPIC_API_KEY`) are read by the underlying provider libraries, not by AFK
  directly. Set `AFK_LLM_API_KEY` only if you want a single key shared across
  providers.
</Tip>

## Memory

Configure the persistent memory backend for thread-based conversations.

| Variable               | Default                   | Description                                                      |
| ---------------------- | ------------------------- | ---------------------------------------------------------------- |
| `AFK_MEMORY_BACKEND`   | `memory`                  | Backend type: `inmemory`/`memory`, `sqlite`, `redis`, `postgres` |
| `AFK_SQLITE_PATH`      | `afk_memory.sqlite3`      | SQLite file path                                                 |
| `AFK_REDIS_URL`        | *(none)*                  | Redis connection URL (for example `redis://localhost:6379`)      |
| `AFK_REDIS_HOST`       | `localhost`               | Redis host when URL is not set                                   |
| `AFK_REDIS_PORT`       | `6379`                    | Redis port when URL is not set                                   |
| `AFK_REDIS_DB`         | `0`                       | Redis DB when URL is not set                                     |
| `AFK_REDIS_PASSWORD`   | *(none)*                  | Redis password when URL is not set                               |
| `AFK_REDIS_EVENTS_MAX` | `2000`                    | Max Redis memory events per thread                               |
| `AFK_PG_DSN`           | *(none)*                  | PostgreSQL connection string                                     |
| `AFK_PG_HOST`          | `localhost`               | PostgreSQL host when DSN is not set                              |
| `AFK_PG_PORT`          | `5432`                    | PostgreSQL port when DSN is not set                              |
| `AFK_PG_USER`          | `postgres`                | PostgreSQL user when DSN is not set                              |
| `AFK_PG_PASSWORD`      | *(none)*                  | PostgreSQL password when DSN is not set                          |
| `AFK_PG_DB`            | `afk`                     | PostgreSQL database when DSN is not set                          |
| `AFK_PG_SSL`           | `false`                   | Enable PostgreSQL SSL                                            |
| `AFK_PG_POOL_MIN`      | `1`                       | PostgreSQL pool minimum size                                     |
| `AFK_PG_POOL_MAX`      | `10`                      | PostgreSQL pool maximum size                                     |
| `AFK_VECTOR_DIM`       | *(required for Postgres)* | Vector dimension for Postgres memory search                      |

```python theme={null}
# Override in code — takes precedence over env vars
from afk.core import Runner

runner = Runner(memory_store=my_custom_store)
```

## Queue

Configure the task queue backend for async agent execution.

| Variable                           | Default                                          | Description                       |
| ---------------------------------- | ------------------------------------------------ | --------------------------------- |
| `AFK_QUEUE_BACKEND`                | `inmemory`                                       | Backend type: `inmemory`, `redis` |
| `AFK_QUEUE_REDIS_URL`              | falls back to `AFK_REDIS_URL`                    | Redis URL for queue backend       |
| `AFK_QUEUE_REDIS_HOST`             | falls back to `AFK_REDIS_HOST`, then `localhost` | Redis queue host                  |
| `AFK_QUEUE_REDIS_PORT`             | falls back to `AFK_REDIS_PORT`, then `6379`      | Redis queue port                  |
| `AFK_QUEUE_REDIS_DB`               | falls back to `AFK_REDIS_DB`, then `0`           | Redis queue DB                    |
| `AFK_QUEUE_REDIS_PASSWORD`         | falls back to `AFK_REDIS_PASSWORD`               | Redis queue password              |
| `AFK_QUEUE_REDIS_PREFIX`           | `afk:queue`                                      | Redis key prefix                  |
| `AFK_QUEUE_RETRY_BACKOFF_BASE_S`   | `0.5`                                            | Retry base delay in seconds       |
| `AFK_QUEUE_RETRY_BACKOFF_MAX_S`    | `30`                                             | Retry max delay in seconds        |
| `AFK_QUEUE_RETRY_BACKOFF_JITTER_S` | `0.2`                                            | Random jitter added to backoff    |

<Warning>
  The `inmemory` queue backend does not persist across restarts. Use `redis` for
  production workloads that need reliable task delivery.
</Warning>

## Prompts

| Variable                | Default          | Description                            |
| ----------------------- | ---------------- | -------------------------------------- |
| `AFK_AGENT_PROMPTS_DIR` | `.agents/prompt` | Root directory for system prompt files |

Agents resolve `instruction_file` paths relative to this directory. See [System Prompts](/library/system-prompts) for details.

## Runner and tool command defaults

| Variable               | Default  | Description                                                 |
| ---------------------- | -------- | ----------------------------------------------------------- |
| `AFK_ALLOWED_COMMANDS` | *(none)* | Comma-separated default allowlist for runtime command tools |

Runner constructors and `RunnerConfig` fields remain the preferred way to set command policy. Use this environment variable only for process-wide defaults.

## MCP server

These variables are read by the MCP server configuration helpers in `afk.config`.

| Variable                | Default          | Description                  |
| ----------------------- | ---------------- | ---------------------------- |
| `AFK_CORS_ORIGINS`      | *(none)*         | Comma-separated CORS origins |
| `AFK_MCP_NAME`          | `afk-mcp-server` | Server name                  |
| `AFK_MCP_VERSION`       | `1.0.0`          | Server version string        |
| `AFK_MCP_HOST`          | `127.0.0.1`      | Bind host                    |
| `AFK_MCP_PORT`          | `8000`           | Bind port                    |
| `AFK_MCP_INSTRUCTIONS`  | *(none)*         | Optional server instructions |
| `AFK_MCP_PATH`          | `/mcp`           | HTTP MCP endpoint path       |
| `AFK_MCP_SSE_PATH`      | `/mcp/sse`       | SSE endpoint path            |
| `AFK_MCP_HEALTH_PATH`   | `/health`        | Health endpoint path         |
| `AFK_MCP_ENABLE_SSE`    | `true`           | Enable SSE endpoint          |
| `AFK_MCP_ENABLE_HEALTH` | `true`           | Enable health endpoint       |
| `AFK_MCP_ALLOW_BATCH`   | `true`           | Allow batched MCP requests   |

## A2A

No default environment variables are required. Configure A2A host and authentication in code for an explicit security posture. See [A2A](/library/a2a) for details.

## Precedence

Configuration is resolved in this order (highest priority first):

1. **Constructor arguments** — `Runner(memory_store=...)`, `Agent(model=...)`
2. **`RunnerConfig` / `LLMSettings` objects** — passed to constructors
3. **Environment variables** — fallback defaults listed on this page
4. **Built-in defaults** — hardcoded in the source

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration Reference" icon="sliders" href="/library/configuration-reference">
    Full reference for all configurable fields across Agent, Runner, and more.
  </Card>

  <Card title="Core Runner" icon="play" href="/library/core-runner">
    Runner lifecycle and configuration options.
  </Card>
</CardGroup>