agent.toml reference

agent.toml holds the agent’s model, run settings, and per-tool policy. It is the only required file in an agent folder.

Unknown keys are rejected — a typo is an error, not a silent no-op.

Full example

[agent]
model = "openai/gpt-5.5"
instructions_file = "instructions.md"
max_turns = 6

[defaults.tool]            # applied to every tool unless overridden
timeout_ms = 5000
memory_mb = 64

[tools.fetch-weather]      # per-tool policy overlay (optional)
timeout_ms = 15000
http_allow = ["api.tfl.gov.uk", "*.metoffice.gov.uk"]
secrets = ["TFL_TOKEN"]

[agent]

Key	Type	Default	Description
model	string	— (required)	Provider-qualified model, provider/model-id (e.g. openai/gpt-5.5). See Choose a provider.
name	string	folder name	Display name for the agent.
instructions	string	—	Inline system prompt. Mutually exclusive with instructions_file.
instructions_file	string	instructions.md	Path (relative to the folder) to read the system prompt from.
max_turns	integer	8	Maximum model turns per message before the loop aborts.
temperature	float	— (unset)	Sampling temperature. Unset sends no temperature at all, which is what most agents want: gpt-5.x rejects any value but 1.0 with a 400.
memory	boolean	false	Enable built-in durable memory: adds the remember/recall tools and injects saved notes into every turn’s system prompt. See Memory.

If neither instructions nor instructions_file is set, maiden reads instructions.md if it exists, otherwise runs with an empty system prompt.

[defaults.tool]

Baseline execution policy applied to every tool. Overridden per tool by a [tools.<name>] table.

Key	Type	Default	Description
timeout_ms	integer	5000	Wall-clock deadline per tool call. Exceeding it traps the tool.
memory_mb	integer	64	Memory ceiling for the tool’s WASM instance.

[tools.<name>]

Optional overlay for a specific tool, keyed by its name (the .wasm file stem). Any field omitted here falls back to [defaults.tool].

Key	Type	Description
timeout_ms	integer	Override the wall-clock deadline for this tool. Also bounds any request it makes.
memory_mb	integer	Override the memory ceiling for this tool.
http_allow	string[]	Host globs this tool may reach. Exact (api.example.com) or single-label wildcard (*.example.com). Empty means no host is allowed.
secrets	string[]	Credential names the tool may reference. The host resolves and injects the value; the value never crosses into the tool. See the security model.

Note

http_allow and secrets are the tool’s entire reach. Both default to empty, so a tool with no policy of its own can make no request at all. The host also requires https (loopback excepted) and does not follow redirects — see the security model.