R.4
Agent file keys
Every key of the agent file at schema version 16, grouped by block, with its type, default, requirement, and meaning from agent-schema.json at v1.149.0.
The schema is titled Docker Agent Configuration, and the pinned copy is the file at tag v1.149.0, commit bf4169cdd31229d52385410c52c3dcc59b497858. Its version enum runs from "0" to "16", so "16" is the current form. The top level and every block below set additionalProperties to false, so an unknown key fails the load. The only required top-level key is agents. Required says whether the schema lists the key under required. Default is the schema default value, and none means the schema states none.
Top-level keys
All 16 keys come from the root properties object. The docs page configuration/overview explains the reusable blocks mcps, rag, commands, skills, and toolsets.
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
version | string, "0" to "16" | none | no | Configuration version |
providers | map of ProviderConfig | none | no | Reusable provider defaults: base_url, token_key, api_type |
agents | map of AgentConfig | none | yes | The agents. At least one is required |
models | map of ModelConfig | none | no | Named model configurations |
mcps | map of MCPToolset | none | no | Reusable MCP server definitions, referenced by name from a toolset |
rag | map of RAGToolset | none | no | Reusable RAG source definitions |
commands | map of Commands | none | no | Named command groups, merged with use_commands |
skills | map of SkillsConfig | none | no | Named skill groups, merged with use_skills |
toolsets | map of Toolset | none | no | Named toolset definitions, appended with use_toolsets |
metadata | Metadata | none | no | Author, license, readme, description, version, tags |
permissions | PermissionsConfig | none | no | Tool approval patterns for the whole file |
runtime | RuntimeDefaults | none | no | Execution defaults the author wants. CLI flags and user settings win |
budget | BudgetConfig | none | no | Ceilings for one run, shared by every sub-session in it |
budgets | map of BudgetConfig | none | no | Named budgets. Agents that share a name share one ceiling |
flavors | map of object or null | none | no | Named YAML patches applied with --flavor, with JSON Merge Patch rules, key+ appends, key- removes |
evaluators | map of EvaluatorConfig | none | no | Named provider-backed assessments for tool_guard and routing hooks |
Keys under agents
Every key of one agent comes from AgentConfig. The docs page configuration/agents explains them, configuration/structured-output covers structured_output, and features/harnesses covers harness.
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
model | string | none | no | A model name from models or provider/model |
fallback | FallbackConfig: models (array), retries (default 2), cooldown (default 1m) | none | no | Models tried in order when the primary fails, with retry and cool-down rules |
description | string | none | no | Description of the agent |
welcome_message | string | none | no | Message shown when the agent starts |
toolsets | array of Toolset | none | no | The toolsets of the agent |
instruction | string or array of strings | none | no | The system prompt. A list is joined with blank lines |
instruction_file | string or array of strings | none | no | Files, relative to the config file, whose content is the instruction. Exclusive with instruction |
harness | HarnessConfig: type (required, claude-code, codex, pi, opencode), model, effort, agent, thinking | none | no | An external coding CLI that runs the agent instead of a model provider |
code_mode_tools | boolean | none | no | Expose one tool that calls the others through JavaScript |
sub_agents | array of strings | none | no | Agents the parent delegates to with transfer_task: local names, OCI references, or name:reference |
handoffs | array of strings | none | no | Agents that can receive the whole conversation |
force_handoff | string | none | no | The agent that always receives the conversation after a final response |
routing | AgentRouting: allowed_agents (required), default_agent | none | no | The agents a routing hook can select, and the one used when an evaluator is uncertain |
add_date | boolean | none | no | Add the date to the context |
add_environment_info | boolean | none | no | Add cwd, git, OS, and arch to the context |
readonly | boolean | none | no | Keep only tools with a read-only annotation in every toolset |
safety | strict, balanced, restricted, autonomous | none | no | Default safety mode of new sessions on this agent, below any user choice |
redact_secrets | boolean | true | no | Install the redact_secrets builtin on tool input, model input, and tool output |
max_iterations | integer | none | no | Maximum loop iterations |
budgets | array of strings | none | no | Names of top-level budgets this agent spends against |
max_consecutive_tool_calls | integer | 0, which means 5 | no | Identical tool calls in a row before the agent stops |
max_old_tool_call_tokens | integer | none, truncation off | no | Tokens kept from old tool arguments and results. -1 turns truncation off |
max_tool_result_tokens | integer | none | no | Tokens kept from each tool result, cut middle-out |
num_history_items | integer | none | no | History items to keep |
session_compaction | boolean | true | no | Compact the session at the threshold and after a context overflow |
compaction_threshold | number | 0.9 | no | Fraction of the context window that starts compaction. The model value wins |
compaction_model | string | none | no | Model that writes the summary. Highest priority of the three levels |
add_prompt_files | array of strings | none | no | Prompt files, such as AGENTS.md, added to the context |
add_prompt_files_depth | integer | 0 | no | Levels below the working directory in which the same file names are listed by path |
commands | object or array | none | no | Named prompts for slash commands |
structured_output | object: name, description, schema, strict | none | no | A JSON schema that constrains the response, native on OpenAI and Gemini |
add_description_parameter | boolean | none | no | Add a description parameter to every tool call |
hooks | HooksConfig | none | no | Lifecycle hooks of this agent |
cache | CacheConfig: enabled (default false), case_sensitive (false), trim_spaces (false), path | none | no | Replay the previous answer to the same question |
skills | boolean or array | none | no | true loads every discovered skill. A list mixes sources, names, and inline skills |
use_commands | array of strings | none | no | Top-level command groups to merge in |
use_skills | array of strings | none | no | Top-level skill groups to merge in |
use_toolsets | array of strings | none | no | Top-level toolsets to append after the inline ones |
An inline skill under skills has name, description, and instructions as required keys, plus context: fork, model, allowed_tools, and toolsets. A command under commands is a string, or an object with description, instruction, agent, and url.
Keys under models
Every key comes from ModelConfig. The docs page configuration/models explains them, and configuration/routing covers routing.
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
provider | string | none | no in the schema, yes in the docs unless first_available is set | The provider id, such as openai, anthropic, dmr |
model | string | none | no in the schema, yes in the docs | The model name |
description | string | none | no | A human summary, not sent to the model |
temperature | number | none | no | Sampling temperature |
max_tokens | integer | none | no | Maximum output tokens per response, not the context window |
top_p | number | none | no | Top-p sampling |
frequency_penalty | number | none | no | Frequency penalty |
presence_penalty | number | none | no | Presence penalty |
base_url | string | none | no | The API base URL, with ${env.VAR} substitution |
parallel_tool_calls | boolean | none | no | Allow parallel tool calls |
token_key | string | none | no | Environment variable that holds the token |
bypass_models_gateway | boolean | none | no | Connect to the provider directly even when a models gateway is set |
provider_opts | object | none | no | Provider options. For dmr: runtime_flags, context_size, keep_alive, and more in R.6 |
track_usage | boolean | none | no | Track usage |
thinking_budget | string or integer | none | no | Reasoning effort or token budget, in the forms R.6 lists |
task_budget | integer or object | none | no | Total token budget of a task, sent to Anthropic as output_config.task_budget |
routing | array of RoutingRule: model, examples (both required) | none | no | Rules that pick a model from example phrases. This model becomes the router |
auth | AuthConfig: type (required, workload_identity_federation), workload_identity_federation | none | no | A non-API-key scheme that wins over the provider path |
first_available | array of strings | none | no | Candidates in priority order. The first with credentials is used. Exclusive with the other keys |
title_model | string | none | no | Model that writes session titles |
compaction_model | string | none | no | Model that writes compaction summaries |
compaction_threshold | number | 0.9 | no | Compaction threshold for agents on this model |
capabilities | CapabilitiesConfig: image, pdf, audio, video | none | no | Attachment capabilities, when the models.dev catalogue is wrong or silent |
output_capabilities | OutputCapabilitiesConfig: image | none | no | Whether the model can generate images |
cost | CostConfig: input, output, cache_read, cache_write, USD per million tokens | none | no | Prices that override the catalogue |
Keys under providers
Every key comes from ProviderConfig. The docs page providers/custom explains them.
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
provider | string | openai when unset | no | The underlying type: openai, anthropic, google, amazon-bedrock, dmr, or a built-in alias |
api_type | openai_chatcompletions, openai_responses | openai_chatcompletions in the schema, model-dependent in the docs | no | The API schema of an OpenAI-compatible provider |
base_url | string | none | no | The endpoint, required for OpenAI-compatible providers, with ${env.VAR} substitution |
token_key | string | none | no | Environment variable that holds the token |
unload_api | string | none | no | Path or URL of the model unload endpoint, used by the unload builtin |
temperature | number | none | no | Default temperature |
max_tokens | integer | none | no | Default output tokens |
top_p | number | none | no | Default top-p |
frequency_penalty | number | none | no | Default frequency penalty |
presence_penalty | number | none | no | Default presence penalty |
parallel_tool_calls | boolean | none | no | Default for parallel tool calls |
provider_opts | object | none | no | Provider options passed to the client |
track_usage | boolean | none | no | Default usage tracking |
thinking_budget | integer or string | none | no | Default reasoning budget |
task_budget | integer or object | none | no | Default task budget |
auth | AuthConfig | none | no | A non-API-key scheme |
compaction_model | string | none | no | Default compaction model, lowest of the three levels |
The federation block under auth requires federation_rule_id (prefix fdrl_), organization_id, and identity_token, and accepts service_account_id. The token source has file, env, command, url, headers, and response_field.
Keys under toolsets
Every key of one toolset entry comes from Toolset. The docs page configuration/tools explains the shared keys, and R.5 says which type uses which.
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
type | one of 27 names | none | no in the schema | The toolset type |
instruction | string | none | no | Replaces the built-in instructions, or extends them with {ORIGINAL_INSTRUCTIONS} |
toon | string | none | no | Comma-separated regular expressions of tools whose JSON output is re-encoded as TOON |
readonly | boolean | none | no | Keep only tools with a read-only annotation |
model | string | none | no | Model for the turn that processes results from this toolset |
ref | string | none | no | docker:<name> or a name from mcps |
config | any | none | no | Tool-specific configuration |
command | string | none | no | Command of a stdio MCP or LSP server |
remote | Remote: url (required), transport_type, headers, oauth | none | no | A remote MCP server |
args | array of strings | none | no | Arguments of the command |
tools | array of strings | none | no | Allow-list of tool names |
env | map of strings | none | no | Environment variables |
shared | boolean | none | no | Share the tool state across agents, for think and todo |
path | string | none | no | Storage path of memory or tasks |
shell | object | none | no | Script definitions of script: cmd, description, args, required, env, working_dir |
post_edit | array of PostEditConfig: path, cmd (both required) | none | no | Commands after an edit of filesystem or file |
api_config | ApiConfig: name, endpoint, method (required), instruction, headers, args, required, output_schema | none | no | The HTTP tool of api |
webhook_config | WebhookConfig: url (required), provider, headers, chat_id | none | no | The destination of webhook |
rag_config | RAGConfig: strategies (required), tool, docs, respect_vcs (default true), indexing_timeout, results | none | no | The sources and strategies of rag |
ignore_vcs | boolean | true | no | Exclude .git and .gitignore patterns from filesystem operations |
allow_list | array of strings | none | no | Directories the file tools can reach |
deny_list | array of strings | none | no | Directories the file tools cannot reach. Wins over allow_list |
defer | boolean or array | none | no | Load tools on demand through search_tool and add_tool |
timeout | integer | 30 when omitted | no | HTTP timeout in seconds for fetch, api, openapi |
max_output_bytes | integer | 30000 | no | Text cutoff of openapi output. 0 turns it off |
escape_html | boolean | false | no | Legacy HTML escaping in multi-URL fetch results |
allowed_domains | array of strings | none | no | Hosts fetch can reach |
blocked_domains | array of strings | none | no | Hosts fetch cannot reach. Exclusive with allowed_domains |
allow_private_ips | boolean | none | no | Permit non-public addresses for fetch, api, openapi, a2a, and remote mcp |
sudo_askpass | boolean | none | no | Prompt for a sudo password through the host UI, for shell |
recall | boolean | none | no | Expose a recall parameter on run_background_job |
url | string | none | no | URL of a2a, openapi, or open_url |
headers | map of strings | none | no | HTTP headers for openapi, a2a, and fetch |
name | string | none | no | Tool name of a2a |
file_types | array of strings | none | no | Extensions an lsp server handles |
allowed_servers | array of strings | none | no | Catalog server ids mcp_catalog offers |
blocked_servers | array of strings | none | no | Catalog server ids removed from the offer |
models | array of strings | none | no | Models model_picker can choose |
version | string | none | no | owner/repo@version for auto-install, or false to turn it off |
working_dir | string | none | no | Working directory of an mcp or lsp subprocess |
lifecycle | Lifecycle: profile (resilient, strict, best-effort), required, startup_timeout, call_timeout, restart, max_restarts, backoff | none | no | The supervisor rules of an mcp or lsp toolset |
A reusable entry under mcps has command, args, ref, remote, config, version, env, tools, instruction, name, defer, working_dir, and lifecycle. An OAuth block under remote has clientId, clientSecret, callbackPort, scopes, and callbackRedirectURL.
Keys under permissions
The three keys come from PermissionsConfig, and the docs page configuration/permissions gives the pattern grammar.
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
allow | array of strings | none | no | Patterns approved without confirmation, such as read_* or shell:cmd=ls* |
ask | array of strings | none | no | Patterns that always ask, even for read-only tools |
deny | array of strings | none | no | Patterns always rejected. Wins over allow |
Keys under hooks
The events come from HooksConfig, and the docs page configuration/hooks explains each one. Every event holds an array. Matcher events hold HookMatcherConfig entries with matcher, hooks (required), and preempt_yolo. The other events hold hook definitions directly.
| Event | Entries | When it runs |
|---|---|---|
prompt_file_guard | definitions | Before a loaded prompt file is stored or used. Every hook must approve |
skill_content_guard | definitions | Before raw skill text is expanded. Every hook must approve |
pre_tool_use | matchers | Before a tool runs. Can allow, deny, or modify |
post_tool_use | matchers | After a tool completes, with its response |
permission_request | matchers | Before the user is asked to approve a call |
session_start | definitions | When a session begins |
user_prompt_submit | definitions | Once per user message, before the first model call |
user_steering_messages_submit | definitions | When queued mid-turn messages are appended |
user_followup_submit | definitions | When a follow-up message starts a fresh turn |
turn_start | definitions | At the start of every model call, with transient context |
turn_end | definitions | When a turn ends, for any reason |
before_llm_call | definitions | Just before each model call |
after_llm_call | definitions | After each successful model call |
session_end | definitions | When a session ends |
pre_compact | definitions | Before the transcript is compacted |
subagent_stop | definitions | When a sub-agent finishes |
on_user_input | definitions | When the agent needs user input |
stop | definitions | When the model finishes responding |
notification | definitions | When the agent sends an error or warning |
on_error | definitions | When a turn hits an error |
on_max_iterations | definitions | When max_iterations is reached |
on_agent_switch | definitions | When the active agent changes |
on_session_resume | definitions | When the user lets the run continue past max_iterations |
on_tool_approval_decision | definitions | After the approval chain decides, before the call runs or the denial is recorded |
before_compaction | definitions | Immediately before a compaction. Can veto it |
after_compaction | definitions | After a successful compaction |
tool_response_transform | matchers | Between a tool run and the record of its response. Can rewrite the output |
tool_input_transform | matchers | Before every tool call, ahead of approval. Can patch the arguments |
tool_guard | matchers | After the input transform and before approval. No safety mode bypasses it |
before_agent_run | routing definitions | Once per agent activation. Can route to another agent |
after_agent_complete | routing definitions | After an agent completes. Can route to another agent |
worktree_create | definitions | Once, after --worktree creates a worktree |
A hook definition comes from HookDefinition.
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
type | command, builtin, model, evaluator | none | yes | What runs: a shell command, a named in-process function, a model, or an evaluator |
command | string | none | no | The shell command or the builtin name |
args | array of strings | none | no | Arguments for the handler |
name | string | none | no | A name for logs and events |
timeout | integer | 60 | no | Seconds before the hook is cut off |
env | map of strings | none | no | Environment for this hook only |
working_dir | string | none | no | Working directory of this hook |
on_error | warn, ignore, block | warn | no | What an error, timeout, or bad output does. pre_tool_use and tool_guard always fail closed |
strict_output | boolean | false | no | Require one JSON object and reject unknown fields |
model | string | none | no | The provider/model of a model hook |
prompt | string | none | no | The Go template a model hook renders |
schema | string | none | no | pre_tool_use_decision turns the model reply into a verdict |
system_prompt | string | none | no | A literal system message for a model hook |
evaluator | string | none | no | The top-level evaluator of an evaluator hook |
evaluator_policy | EvaluatorPolicy: decisions, min_probability, fallback (all required) | none | no | How an evaluator verdict maps to a guard decision |
routing_policy | RoutingPolicy: routes, min_probability (both required) | none | no | How an evaluator choice maps to an agent |
The type description names 17 builtins. They are add_context, add_date, add_environment_info, add_prompt_files, add_git_status, add_git_diff, add_directory_listing, add_user_info, add_recent_commits, max_iterations, redact_secrets, transform_json, limit_large_tool_results, safer_shell, http_post, snapshot, and unload.
Keys under runtime, budget, metadata, and evaluators
| Block | Key | Type | Default | Required | Meaning |
|---|---|---|---|---|---|
runtime | sandbox | boolean | none | no | Run in a sandbox by default, as --sandbox does |
runtime | network_allowlist | array of strings | none | no | Hosts added to the sandbox allowlist, host or host:port |
runtime | safety | one of four modes | none | no | Default safety mode of the file, below a per-agent safety |
budget | max_cost | number | none | no | Maximum USD per run, counting only priced responses |
budget | max_tokens | integer | none | no | Maximum input plus output tokens over the run |
budget | max_time | string | none | no | Maximum sum of turn durations, as a Go duration |
metadata | author, license, readme, description, version, tags | strings, tags an array | none | no | Descriptive fields. version is used for OCI publishing |
evaluators | provider, model, type, instructions | strings, type one of boolean, choice, score | none | yes | A named assessment on the typesafe or openai Decisions backend |
evaluators | base_url, endpoint, token_key, bypass_models_gateway, choices, levels, timeout, cost | mixed | timeout 10s in the description | no | Endpoint, credential, and output shape of the evaluator |
The docs pages configuration/budget and configuration/flavors explain budget and flavors with examples.
Docker Sandboxes (sbx) and Docker Agent (docker-agent) sbx 0.47.0, docker-agent 1.149.0 · bf4169c · 2026-10-07 · Edition 2026.10