Configuration

Reference. All settings. How-to guides: Install · Add a local model · Connect remote APIs.

.env (compose settings)

scripts/setup.sh writes this file from .env.example. Apply changes with docker compose up -d.

Variable	Default from setup.sh	Meaning
AGENTBOX_UID, AGENTBOX_GID	your ids	Identity of agentbox, the launcher, llm-bridge and Ollama. Owns the data dir and the repos.
DOCKER_GID	getent group docker	Lets the launcher use /var/run/docker.sock
AGENTBOX_AGENT_UID, AGENTBOX_AGENT_GID	64000	Sandbox identity. Should not exist on the host (setup warns).
AGENTBOX_DATA	~/.local/share/agentbox	State dir; see "Files" below
AGENTBOX_REPOS_ROOT	your home dir	Allowlist for the folders the planner may pass as repo_path (and for venvs). Nothing is mounted from it; each request mounts only the one repo, briefly.
AGENTBOX_VENVS	~/.cache/local-agent-venvs	Venv root for python_env
OLLAMA_MODELS_DIR	$AGENTBOX_DATA/ollama	Ollama model store
AGENTBOX_MCP_TOKEN	random	Bearer token for the MCP endpoint
AGENTBOX_BRIDGE_TOKEN	random	agentbox → llm-bridge auth
AGENTBOX_AGENT_RUNTIME	runsc if detected, else unset	Sandbox runtime. runsc (gVisor) is recommended; unset means runc.
AGENTBOX_PORT, AGENTBOX_BRIDGE_PORT	8765, 8790	Ports on 127.0.0.1

Launcher environment variables (set them in docker-compose.yml):

• AGENTBOX_AGENT_MEM_GB (8)
• AGENTBOX_AGENT_CPUS (4)
• AGENTBOX_AGENT_PIDS (512)

secrets.env (llm-bridge only)

Provider API keys, referenced by api_key_env in models.yaml. Mode 600, gitignored, and loaded only by the llm-bridge container.

config/models.yaml

Apply changes with docker compose restart agentbox agentbox-launcher llm-bridge.

Key	Applies to	Default	Meaning
paths.models_dir	vllm		Host dir mounted at /models (read-only)
paths.vllm_cache	vllm		Host dir mounted at /cache
default_model		first model	Used when delegate_task gets no model
models.<id>.backend	all	required	vllm · ollama · openai · anthropic
description	all		Shown by list_models
max_agents	all	4	Concurrent tasks for this model
token_budget	all	20M local · 3M remote	Input + output tokens per task
port	vllm	required	Must match --port in args
image	vllm	required	vLLM image (pin a tag)
entrypoint	vllm	image default	e.g. [vllm]
args	vllm		String split on whitespace, or a list
env	vllm		Container environment
memory	vllm		Container memory cap, e.g. 100g
shm_size / ipc_host	vllm		Shared memory: size, or host IPC
load_timeout_s	vllm	1800	Max wait for /health
ollama_model	ollama	required	e.g. qwen3-coder:30b
endpoint	openai, anthropic	required	openai: base URL with /v1; anthropic: base URL without /v1
model_name	openai, anthropic	required	Name sent upstream
api_key_env	openai, anthropic		Env var in secrets.env
max_output_tokens	openai		Clamp for max_tokens
token_param	openai	max_tokens	e.g. max_completion_tokens
drop_params	openai	[]	e.g. [temperature, top_p]
extra_body	openai	{}	Merged into every request

Files ($AGENTBOX_DATA, mode 0700)

Path	Contents
run/launcher.sock	Launcher API socket
worktrees/<id>/	Scratch clones (owned by the agent uid while it runs)
sockets/<id>/llm.sock	Per-task gateway sockets (dir mode 0711)
git/<id>.git	Shadow git dirs
logs/delegations.jsonl	One record per delegation: task_id, model, backend, status, num_turns, wait_s, wall_s, input/output tokens, requests, gateway_errors, diff_lines, guide, task