Environment Variables

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.

All variables are optional. If unset, AFK uses the defaults listed below.

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

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.

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

# 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

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

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 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 for details.

Precedence

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

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

Next steps

Configuration Reference

Full reference for all configurable fields across Agent, Runner, and more.

Core Runner

Runner lifecycle and configuration options.

​LLM defaults

​Memory

​Queue

​Prompts

​Runner and tool command defaults

​MCP server

​A2A

​Precedence

​Next steps

Configuration Reference

Core Runner

LLM defaults

Memory

Queue

Prompts

Runner and tool command defaults

MCP server

A2A

Precedence

Next steps