Configuration

Configuration reference for Toolang 0.4.0. Examples use too, the recommended alias for toolang.

Files and precedence

ROOT defaults to ~/.toolang; select another root with --root or TOOLANG_ROOT. Agent settings override root settings field by field. Plugin configuration tables merge recursively; allow lists replace the earlier value for that field. Explicit startup options override environment settings, which in turn override the configured run policy.

For scripts, discovery starts beside the real .too source and stops at the nearest Git worktree root. Outside Git, only the source directory is searched. Only the nearest existing toolang.toml is selected; an empty file stops the search. Workspace declarations apply only when that TOML is beside the source. Known file paths resolve relative to the declaring configuration file.

Scope and lifetime

Here, project means the selected script toolang.toml; scope does not imply that root configuration can author every home-only setting.

Running services retain the last valid published Setup when a new candidate fails validation. A live refresh does not rewrite accepted runs' captured inputs. Attaching to an existing server keeps its startup settings; restart hosting to change ports, driver selection, sandbox, or environment.

For example, root [model] can select openai/gpt-5 with effort = "high". Home [model] with only max_output = 4096 retains the root ref and effort. Startup --default 'model=openai/gpt-5' selects that exact model and clears the earlier parameter overrides. Likewise, home allow.tools = ["fs/read"] replaces the root tool query list; a later per-run ceiling can narrow it further. This illustrates model operations and field replacement, rather than merging all lists. See resource policy.

Models

Choose a model with a structured [model] table. Replace the example reference with one available in too models.

[model]
ref = "openai/gpt-5"
effort = "high"
max_output = 8192

The same fields are accepted in [talk.model] and [compact.model]:

An exact ref clears inherited parameter overrides before applying fields in that table. A parameter-only table adjusts the inherited model. "auto" clears one parameter. Ordinary ref = "default" keeps the preceding model; "unset" clears the configured preference. Talk and compaction inherit their own calling-model baseline.

Parameter-only configuration needs an inherited model. ref = "unset" cannot be combined with effort or max_output. Supported effort levels depend on the selected model and adapter; inspect too models --json before selecting one. Model refs here are exact identities, not resource queries.

CLI and environment values use a model string:

too alice start --default 'model=openai/gpt-5 effort=high'
too helpers.too summarize --model 'openai/gpt-5 max_output=8192' -- Explain this change.

Use [model] rather than [default].model. The old [default] table and scalar compact model settings have no effect. [models.providers.*], [models.aliases.*], and [models].default are rejected; connection routes belong in a model catalog. none is not a model-selection sentinel. See Configure models for setup examples.

Resource policy and run limits

[allow]
models = ["openai/*"]
tools = ["fs/*", "shell/*"]
skills = ["skill/reviewer"]
 
[limit]
agic_model_calls = 20
agic_tool_calls = 40
tokens = 20000
cost = 2.5
time = 120

[allow] accepts models, tools, psyches, skills, services, and prompts. Values are arrays of resource queries; models also accepts one string. A complete value of ["all"] or ["none"] selects all or no resources; these sentinels cannot mix with queries. Caps use complete identities such as skill/reviewer.

agic_model_calls and agic_tool_calls limit each agic. tokens, cost in USD, and time in seconds apply across the root run and its children. Counts and time are non-negative integers; cost is a non-negative decimal. Use the string "none" to remove a limit. model.max_output limits one model response and is separate from the run's token budget.

Zero is a real budget, not a spelling of unlimited. Omitted fields inherit the preceding layer. Use "none" in TOML or FIELD=none in CLI limit overrides for an unlimited value.

Startup uses repeatable --allow FIELD=QUERY and --limit FIELD=VALUE options. Inside Chat, :allow and :limit update later submissions; leading /allow and /limit directives affect one submission. Resource restrictions remain within inherited authority.

History compaction and Talk

[compact]
summary = 4096
recent = "30%"
trigger = "80%"
 
[compact.model]
ref = "openai/gpt-5"
effort = "low"
 
[talk.model]
effort = "low"
 
[talk.limit]
tokens = 20000

Compaction sizes accept positive integer token counts or percentages in (0%, 100%]. Percentages refer to the current thread model's context window. recent must be less than trigger. The defaults are a 4096-token summary, 30% retained recent history, and an 80% trigger. Omitting [compact.model] uses the calling model; it is not a switch to disable compaction.

[talk.model] overlays ordinary model selection. [talk.limit] overlays ordinary run limits. Runtime runnable handlers are authored as agics or flows; there is no [default].runnable setting.

Configured caps

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

Entries attach shared or agent-specific caps. The key supplies the local cap name; ref supplies its source. File-backed and inline caps are separate authored forms; see File formats.

Workspaces

Home configuration maps workspace names to directories. Relative paths resolve from the configuration file; names use lowercase kebab case and resolved roots must be distinct. lab is reserved for the implicit workspace. workspace add requires an existing directory and saves its canonical absolute path.

[workspaces]
repo = "/path/to/project"

Root configuration can override grants for a selected resident agent:

[workspaces.alice]
repo = "/path/to/project"

Use too alice workspace add, list, and remove to manage home declarations. Root overrides remain read-only through those commands. --workspace adds invocation grants; --workdir selects a directory within the effective grants.

Sandboxes and plugins

[sandbox]
driver = "docker"
target = "python:3.13-slim"
 
[plugin.sandbox.docker]
root = "/root/.toolang"
 
[plugin.toolset.shell]
timeout_sec = 60
max_output_chars = 20000
 
[plugin.model_catalog.ollama]
endpoint = "http://127.0.0.1:11434"

Sandbox selectors use name[:spec]. Selection order is an explicit --sandbox, configured [sandbox], the last successful selection, then host. driver selects the plugin and target supplies its optional spec.

Supported plugin families are toolset, sandbox, model_catalog, and model_adapter. Each plugin owns its settings. Built-in toolsets include fs, shell, service, history, convo, state, runtime, serpapi, and tavily. Use too catalogs, too adapters, too toolsets, and too sandboxes to inspect installed plugins. The old top-level [tools] and [plugins] tables are rejected.

Hub, teaming, API, and terminal

Root configuration chooses the conversation identity and Hub client URL, and configures a locally managed Hub separately:

[teaming]
human = "me"
enabled = true
hub = "http://127.0.0.1:7001"
 
[hub]
host = "127.0.0.1"
port = 7001
 
[hub.backend]
url = "redis://localhost:6379/0"

[teaming] defaults to enabled, the local Hub URL shown above, and a local account-derived human identity. Home [teaming] accepts only enabled. [hub.backend].url accepts redis, rediss, valkey, valkeys, and unix URLs. Only the Hub connects to that backend. Start Redis/Valkey separately; too hub start starts the Hub process only. See Conversations.

Home [api] accepts port. The CLI's --port overrides TOOLANG_AGENT_PORT, which overrides [api].port; otherwise a free agent port is allocated. Hub ports use --port, then TOOLANG_HUB_PORT, then [hub].port.

Root [web] accepts ui_base_url for rendered UI links and cors_allowed_origins for the HTTP API. Their environment overrides are listed below. Optional [terminal.title.prefix] entries customize terminal title prefixes for chat, talk, top, serve, run, and rerun.

Environment selection

Only ROOT/config.toml accepts [env]. Each provided list replaces its default:

[env]
keep = ["HOME", "PATH", "LANG", "TERM"]
pick = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]

Without ROOT/.env, root commands inherit the process environment. With that file, they receive only keep variables plus the file's bindings. Agent processes receive kept root variables plus exactly one binding group:

1. AGENT_ROOT/.NAME.env, if it exists;
2. otherwise AGENT_HOME/.env, if it exists;
3. otherwise the first nonblank root variable in pick.

For resident Alice the named file is ROOT/.alice.env; for helpers.too it is SOURCE_DIR/.toolang/.helpers.env. A .env beside the script is not selected automatically.

File assignments can override kept values. To admit multiple provider keys, list their bare names in the selected agent file. Files replace each other; an empty selected file also disables automatic credential picking. The built-in keep list contains standard process and terminal variables. The built-in pick list contains supported provider-key names in alphabetical order. Configure it explicitly to choose another priority.

Dotenv assignments are literal and do not expand shell variables. A bare name inherits that value from the parent environment. Duplicate or malformed bindings fail. Keep secret values in untracked dotenv files, not in TOML.

Startup controller settings are captured separately from the selected execution environment. Configuration changes do not replace an already running process's environment snapshot.

Static model catalogs

Select one flat catalog, highest priority first:

1. --catalog PATH, on commands that expose it;
2. TOOLANG_MODEL_CATALOG;
3. the active home catalog;
4. the active root or selected project catalog;
5. Toolang's bundled catalog.

Within a layer, [plugin.model_catalog.models_dev].path overrides its implicit file. Resident scopes discover catalog.json; scripts discover toolang.catalog.json. Files replace each other and never merge. The accepted format has providers and models arrays; raw upstream models.dev data must be converted before use. Maintained catalogs are available in openhat-ai/models.

Catalog JSON

The top-level object must have exactly providers and models. This example describes an OpenAI-compatible gateway; replace its endpoint, model ID, and capabilities with those of your service:

{
  "providers": [
    {
      "id": "gateway",
      "name": "Example gateway",
      "npm": "@ai-sdk/openai-compatible",
      "api": "https://example.com/v1",
      "env": ["GATEWAY_API_KEY"]
    }
  ],
  "models": [
    {
      "provider": "gateway",
      "id": "example-model",
      "name": "Example model",
      "modalities": {"input": ["text"], "output": ["text"]},
      "limit": {"context": 32768, "output": 4096},
      "tool_call": true
    }
  ]
}

Every model must name a declared provider. Provider IDs and (provider, id) pairs must be unique. A model's effective ref is PROVIDER/ID; do not author a ref field. modalities maps names such as input and output to arrays of strings. limit maps names such as context and output to non-negative integers; zero means unknown and is omitted from the effective model facts. Optional cost.input and cost.output rates are USD per million tokens.

npm identifies the adapter convention; Toolang does not install an npm package. @ai-sdk/openai-compatible selects Chat Completions and needs an explicit API base. @ai-sdk/openai selects Responses by default. A model's override can supply npm, api, shape, mode, headers, or body for that model's route. Provider api and model override.api support $NAME and ${NAME} substitution from the selected environment; a missing binding makes the route unavailable. Do not put literal credentials in catalog JSON.

Local model catalogs

Ollama and llama.cpp discovery supplement the selected static catalog:

Both accept endpoint, a positive timeout in seconds (default 2.0), and an optional string-to-string headers map for discovery. An explicit endpoint overrides its environment variable. The selected environment must retain those variables for discovery. Use too models --all --json to inspect readiness tags and resource query syntax to diagnose unavailable models.