Environment variables¶
Every environment variable woollama reads, grouped by purpose. All are optional unless you use the feature that needs them.
Provider API keys¶
Read at call time (never stored); woollama only holds the name of the var.
Required only to use (or live-discover) the matching cloud provider.
| Variable | For |
|---|---|
ANTHROPIC_API_KEY |
anthropic/<model> and the managed-agents backend (claude-agent/<model>) |
OPENAI_API_KEY |
openai/<model> |
GROQ_API_KEY |
groq/<model> |
TOGETHER_API_KEY |
together/<model> |
OPENROUTER_API_KEY |
openrouter/<model> |
| (custom) | whatever api_key_env a provider in inferencers.toml names |
ollama and claude-code (CLI/subscription) need no key.
Binding & discovery¶
| Variable | Default | Effect |
|---|---|---|
WOOLLAMA_ADDRESS |
(unset) | Override the bind address (host[:port]). The only way to bind off-loopback (e.g. 0.0.0.0:8000) — opt-in, since the router holds API keys. A non-loopback bind additionally requires WOOLLAMA_TOKEN; woollama refuses to start otherwise (fail closed). |
WOOLLAMA_TOKEN |
(unset) | Surface auth token for /v1/* and /mcp. When set, every TCP request must send Authorization: Bearer <token> — loopback included; the Unix socket stays exempt (its mode-0600 permissions are the credential). When unset, only local peers (loopback TCP / the Unix socket) are served. Required to bind off-loopback. |
XDG_RUNTIME_DIR |
/tmp fallback |
Where the Unix socket (woollama.sock, mode 0600) and the address file (woollama.addr) are written. |
Backends & config¶
| Variable | Default | Effect |
|---|---|---|
WOOLLAMA_CONFIG_DIR |
$XDG_CONFIG_HOME/woollama (~/.config/woollama) |
Where mcp.json / recipes.toml / inferencers.toml are read from. |
XDG_CONFIG_HOME |
~/.config |
Base for the default config dir (above). |
WOOLLAMA_STATE_DIR |
$XDG_STATE_HOME/woollama (~/.local/state/woollama) |
Where the durable conversation handle table (conversations.json) is stored, so a client's conversation id keeps resolving across a woollama restart. App-managed routing state (conv_id → backend + native id), not transcripts — the backend/store still owns the bytes. |
XDG_STATE_HOME |
~/.local/state |
Base for the default state dir (above). |
WOOLLAMA_OLLAMA_URL |
http://localhost:11434 |
The local Ollama endpoint (the ollama/ provider's base + its /v1/models discovery). |
WOOLLAMA_CLAUDE_BIN |
claude (on PATH) |
Path to the Claude Code CLI for claude-code/<model> (inference, delegation, and the claude-resume conversation backend). |
WOOLLAMA_TOOL_TIMEOUT |
180 (seconds) |
Wall-clock bound on one downstream MCP tool call, so a hung server bounds the turn instead of wedging the connection. <= 0 disables. |
WOOLLAMA_AGENT_NETWORKING |
limited |
Networking policy for the hosted managed-agents environment. The default is least-privilege (limited); set unrestricted to restore open egress for setups that add network-using capabilities. |
The conversation store (issue #2) that makes non-claude models stateful is selected in config, not by an env var — the top-level
conversationStorekey inmcp.json(an MCP server or an HTTP endpoint).
Claude Code child process¶
When woollama runs the claude CLI (as an inferencer, an executor, or the
claude-resume backend), the child gets an allow-listed environment only —
operational vars, no provider keys or secrets. The allow-list is:
HOME, PATH, USER, LOGNAME, SHELL, TERM, TZ, TMPDIR, LANG,
LANGUAGE, LC_*, and the proxy vars (HTTP_PROXY/HTTPS_PROXY/NO_PROXY,
lower-case too).
See Security model for why, and Configuration for the files these complement.