Configuration files

Reference for Toolang TOML configuration and environment loading.

Toolang reads TOML configuration from the root and the current agent home. For standalone roaming .too files, a sibling toolang.toml is linked into the materialized agent home as config.toml.

Locations

Root configuration is read first. Agent configuration is read second and overrides the same named entries where the loader supports merging.

Environment Files

Runtime environment is loaded in this order:

1. ${TOOLANG_ROOT}/.env
2. ${TOOLANG_ROOT}/agents/<agent>/.env
3. the process environment

Later values override earlier values. Use .env for local defaults and keep secrets out of checked-in TOML files.

Plugin config tables also support *_env keys. If a key such as token_env is present and token is not set directly, Toolang reads the named environment variable and provides it to the plugin as token.

[sandbox]
driver = "docker"
target = "python:3.13"
 
[sandbox.config]
token_env = "SANDBOX_TOKEN"

If the named environment variable is missing, Toolang raises an error that names the config key and the missing variable.

Models

Model defaults, provider overrides, and local aliases live under [models]. The root and agent config files are read in order; agent config can replace defaults or aliases.

[models]
default = ["gateway", "openai/gpt-5[openai]"]
 
[models.aliases.gateway]
ref = "openai/gpt-5"
provider = "openai"
adapter = "responses"
endpoint = "https://gateway.example.com/v1"
key_env = "GATEWAY_API_KEY"
headers = { "X-Team" = "infra" }
 
[models.providers.openrouter]
endpoint = "https://openrouter.ai/api/v1"
key_env = "OPENROUTER_API_KEY"

[models]

[models.aliases.<name>]

provider = "custom" is reserved for alias-only OpenAI-compatible endpoints and requires endpoint.

[models.providers.<name>]

Wired Caps

Remote caps can be wired through TOML tables. Root config.toml wires shared caps. Agent config.toml wires private caps for that agent.

[skills]
reviewer = { ref = "github://acme/agents/skills/reviewer@main" }
 
[services]
github = { ref = "github://acme/agents/services/github.md@main" }
 
[prompts]
rewrite = { ref = "github://acme/agents/prompts/rewrite.md@main" }
 
[psyches]
direct = { ref = "github://acme/agents/psyches/direct.md@main" }

Supported cap sections are psyches, skills, services, and prompts. Each entry name becomes the local cap name. Each entry value must contain a ref.

Tools

Tool plugin configuration lives under [tools.<plugin>] and is merged from root to agent config by plugin name.

[tools.agent_chat]
peers = [
  { name = "bob", endpoint = "http://127.0.0.1:7002" },
]

Built-in tool families include agent_chat, filesystem, shell, web_search, service_use, and agent_state.

Channels

Channel bindings live under [channels.<binding>]. Each binding must declare the channel plugin name in plugin; all other keys are passed to that plugin as config.

[channels.inbox]
plugin = "telegram"
token_env = "TELEGRAM_BOT_TOKEN"
owner_chat_id = "12345"

Root and agent channel bindings merge by binding name.

Sandbox

Sandbox config uses a top-level [sandbox] table plus optional [sandbox.config].

[sandbox]
driver = "docker"
target = "python:3.13"
 
[sandbox.config]
image = "python:3.13-slim"

driver names the sandbox plugin. plugin is also accepted as a legacy alias for driver. target is optional and is interpreted by the sandbox plugin. [sandbox.config] values from the agent config extend or override root values.

Web

Root web config lives under [web].

[web]
ui_base_url = "https://too.run"
cors_allowed_origins = ["http://localhost:3000", "https://too.run"]

TOOLANG_ROOT selects the root directory itself. PY_LOG controls logging verbosity and destinations for runtime and invoke surfaces.