Skip to main content

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.

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.
VariableDefaultDescription
AFK_LLM_PROVIDERlitellmDefault provider id (openai, litellm, anthropic_agent)
AFK_LLM_PROVIDER_ORDER(none)Comma-separated provider preference order for routing helpers
AFK_LLM_MODELgpt-4.1-miniDefault 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_S30Request timeout in seconds
AFK_LLM_STREAM_IDLE_TIMEOUT_S45Stream idle timeout in seconds
AFK_LLM_MAX_RETRIES3Retry attempts on transient failures
AFK_LLM_BACKOFF_BASE_S0.5Exponential backoff base in seconds
AFK_LLM_BACKOFF_JITTER_S0.15Random jitter added to backoff
AFK_LLM_JSON_MAX_RETRIES2Structured output repair attempts
AFK_LLM_MAX_INPUT_CHARS200000Input 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.
VariableDefaultDescription
AFK_MEMORY_BACKENDmemoryBackend type: inmemory/memory, sqlite, redis, postgres
AFK_SQLITE_PATHafk_memory.sqlite3SQLite file path
AFK_REDIS_URL(none)Redis connection URL (for example redis://localhost:6379)
AFK_REDIS_HOSTlocalhostRedis host when URL is not set
AFK_REDIS_PORT6379Redis port when URL is not set
AFK_REDIS_DB0Redis DB when URL is not set
AFK_REDIS_PASSWORD(none)Redis password when URL is not set
AFK_REDIS_EVENTS_MAX2000Max Redis memory events per thread
AFK_PG_DSN(none)PostgreSQL connection string
AFK_PG_HOSTlocalhostPostgreSQL host when DSN is not set
AFK_PG_PORT5432PostgreSQL port when DSN is not set
AFK_PG_USERpostgresPostgreSQL user when DSN is not set
AFK_PG_PASSWORD(none)PostgreSQL password when DSN is not set
AFK_PG_DBafkPostgreSQL database when DSN is not set
AFK_PG_SSLfalseEnable PostgreSQL SSL
AFK_PG_POOL_MIN1PostgreSQL pool minimum size
AFK_PG_POOL_MAX10PostgreSQL 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.
VariableDefaultDescription
AFK_QUEUE_BACKENDinmemoryBackend type: inmemory, redis
AFK_QUEUE_REDIS_URLfalls back to AFK_REDIS_URLRedis URL for queue backend
AFK_QUEUE_REDIS_HOSTfalls back to AFK_REDIS_HOST, then localhostRedis queue host
AFK_QUEUE_REDIS_PORTfalls back to AFK_REDIS_PORT, then 6379Redis queue port
AFK_QUEUE_REDIS_DBfalls back to AFK_REDIS_DB, then 0Redis queue DB
AFK_QUEUE_REDIS_PASSWORDfalls back to AFK_REDIS_PASSWORDRedis queue password
AFK_QUEUE_REDIS_PREFIXafk:queueRedis key prefix
AFK_QUEUE_RETRY_BACKOFF_BASE_S0.5Retry base delay in seconds
AFK_QUEUE_RETRY_BACKOFF_MAX_S30Retry max delay in seconds
AFK_QUEUE_RETRY_BACKOFF_JITTER_S0.2Random jitter added to backoff
The inmemory queue backend does not persist across restarts. Use redis for production workloads that need reliable task delivery.

​
Prompts

VariableDefaultDescription
AFK_AGENT_PROMPTS_DIR.agents/promptRoot directory for system prompt files
Agents resolve instruction_file paths relative to this directory. See System Prompts for details.

​
Runner and tool command defaults

VariableDefaultDescription
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.
VariableDefaultDescription
AFK_CORS_ORIGINS(none)Comma-separated CORS origins
AFK_MCP_NAMEafk-mcp-serverServer name
AFK_MCP_VERSION1.0.0Server version string
AFK_MCP_HOST127.0.0.1Bind host
AFK_MCP_PORT8000Bind port
AFK_MCP_INSTRUCTIONS(none)Optional server instructions
AFK_MCP_PATH/mcpHTTP MCP endpoint path
AFK_MCP_SSE_PATH/mcp/sseSSE endpoint path
AFK_MCP_HEALTH_PATH/healthHealth endpoint path
AFK_MCP_ENABLE_SSEtrueEnable SSE endpoint
AFK_MCP_ENABLE_HEALTHtrueEnable health endpoint
AFK_MCP_ALLOW_BATCHtrueAllow 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):
  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

Configuration Reference

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

Core Runner

Runner lifecycle and configuration options.