Configuration Reference

AURA is configured with a single TOML file. The file path defaults to config.toml in the working directory; override it with the CONFIG_PATH environment variable.

CONFIG_PATH=configs/my-agent.toml cargo run --bin aura -- webserver

To validate a config file, start the web server or CLI against it. Both validate immediately and exit with a clear error if parsing fails, before binding to any port or entering the REPL:

cargo run --bin aura -- webserver --config your-config.toml   # exits on parse error before binding
cargo run --bin aura -- --config your-config.toml             # exits on parse error before REPL

Environment Variable Interpolation

Any string value in the config can reference an environment variable using {{ env.VAR_NAME }}. An optional | default: 'value' fallback prevents a hard error when the variable is unset.

api_key = "{{ env.OPENAI_API_KEY }}"
Authorization = "Bearer {{ env.GITHUB_PERSONAL_ACCESS_TOKEN | default: '' }}"

Root-Level Fields

Field	Type	Default	Description
`memory_dir`	string	-	Base directory for scratchpad storage and orchestration artifact persistence. Required when scratchpad is enabled.

memory_dir = "/tmp/aura-sessions"

`[agent]`

Defines the agent identity, system prompt, and behavioral settings.

Field	Type	Default	Description
`name`	string	required	Display name. Doubles as the model identifier clients send in requests.
`alias`	string	-	Stable identifier for model selection. Clients send this as the `model` field. Useful when the name contains spaces.
`description`	string	-	Optional one-line, human-readable summary of the agent. Use it to distinguish multiple loaded configs that would otherwise differ only by `name` or `alias`. Display-only. It appears in `/v1/models`, `/aura/info`, and the CLI `/model` picker, but is never part of runtime settings and never sent to the model. Omitted from `/v1/models` and `/aura/info` responses when unset. Not to be confused with the required per-worker `description` under `[orchestration]`, which guides planning and is not shown to people. It is free-form text with no enforced length limit; the CLI `/model` picker collapses whitespace and truncates it to fit the terminal.
`system_prompt`	string	required	The agent’s system prompt. Multi-line strings use TOML `"""..."""` syntax.
`turn_depth`	integer	`5`	Max tool-call rounds per user turn. Acts as a failsafe to prevent models from spinning out in unbounded tool-call loops.
`nudge_last_turn`	bool	`false`	Append a wrap-up warning to tool output on the final turn before `turn_depth` terminates the run (orchestration workers are told to call `submit_result`), rather than silently losing all gathered work.
`nudge_turns_remaining`	integer	-	Start wrap-up warnings when N or fewer tool-calling turns remain. Independent of `nudge_last_turn`; both default to off and can be enabled separately.
`mcp_filter`	list of strings	-	Tool-name patterns selecting which MCP tools to expose. When omitted, all tools are included. Accepts `<namespace>:<name>` to select tools from one MCP server.
`enable_client_tools`	bool	`false`	Allow the agent to invoke client-side tools advertised in the request. See Client-Side Tools for security implications.
`client_tool_filter`	list of strings	-	Tool-name patterns narrowing which client tools are allowed (requires `enable_client_tools = true`).
`model_owner`	string	(LLM provider name)	Overrides the `owned_by` field in `/v1/models` responses.
`created_at`	integer	(current time)	Creation timestamp in milliseconds since epoch. Shown in `/v1/models` responses.
`hidden`	bool	`false`	Hides this agent from the `/v1/models` list. Useful for agents meant only for internal callers.

[agent]
name = "DevOps Assistant"
alias = "devops"
description = "General-purpose assistant with tool access"
system_prompt = """
You are a DevOps assistant with access to GitHub.
Help with code review, PR management, and repo exploration.
"""
turn_depth = 10
mcp_filter = ["get_*", "list_*", "search_*"]
model_owner = "acme"
hidden = false

Multiple Agents

CONFIG_PATH can point to a single TOML file or a directory of .toml files. When pointed at a directory, AURA loads every .toml file and serves each as a selectable agent:

configs/
├── research-assistant.toml
├── devops-agent.toml
└── code-reviewer.toml

CONFIG_PATH=configs/ cargo run --bin aura -- webserver

Each agent is identified by its alias (if set) or name. Clients discover available agents via GET /v1/models and select one by passing its identifier as the model field in chat completion requests. The same field tools like LibreChat, OpenWebUI, and CLI clients use to present a model picker. Agent selection follows this order:

If only one config is loaded, it is always used (the model field is ignored).
Otherwise, model is matched first, then DEFAULT_AGENT if model is absent.
Returns a 400 error if multiple configs are loaded and neither model nor DEFAULT_AGENT is supplied at all.
Returns a 404 error if a model or DEFAULT_AGENT value is supplied but matches no loaded config.

[agent]
name = "DevOps Assistant"
alias = "devops"             # clients send "model": "devops"
description = "DevOps assistant with GitHub access"
system_prompt = "You are a DevOps expert."
model_owner = "mezmo"        # override owned_by in /v1/models (defaults to LLM provider)

Aliases must be unique across all loaded configs. If two configs share the same name and neither has an alias, loading fails with a validation error. Hidden agents are excluded from GET /v1/models and the CLI’s /model list but remain fully accessible when a caller targets them by exact name or alias. Set hidden = true to hide agents that are in development, restricted to known callers, or should not appear in model pickers (LibreChat, OpenWebUI, etc.):

[agent]
name = "Internal Triage Agent"
hidden = true         # excluded from /v1/models and CLI model list; still callable by name
system_prompt = "..."

`[agent.llm]`

Configures the LLM provider. The provider field is a discriminant that selects the variant and its required fields.

Common Fields

These fields are available on all providers except where noted.

Field	Type	Default	Description
`provider`	string	-	Required. One of: `openai`, `anthropic`, `bedrock`, `gemini`, `ollama`, `openrouter`.
`model`	string	-	Required. Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`).
`max_tokens`	integer	-	Maximum tokens in the response.
`context_window`	integer	-	Context window size in tokens. Required when scratchpad is enabled. Used for usage reporting in `aura.session_info` events.
`temperature`	float	-	Sampling temperature (0.0–2.0). Higher values increase randomness.
`additional_params`	table	-	Provider-specific parameters merged into the API request body. Useful for features like extended thinking.

`provider = "openai"`

[agent.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"
max_tokens = 8192
context_window = 128000
temperature = 0.7
# base_url = "https://api.openai.com/v1"  # custom endpoint
# reasoning_effort = "medium"             # none, minimal, low, medium, high, xhigh (provider/model support varies)

Extra fields:

Field	Type	Default	Description
`api_key`	string	-	Required. OpenAI API key.
`base_url`	string	-	Override the API base URL (useful for compatible proxies).
`reasoning_effort`	string	-	`none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Controls reasoning depth. Support varies by model and version. Aura passes the value straight to the OpenAI API, which returns a 400 error for combinations of `model` and `reasoning_effort` that it does not support.

`provider = "anthropic"`

[agent.llm]
provider = "anthropic"
api_key = "{{ env.ANTHROPIC_API_KEY }}"
model = "claude-sonnet-4-20250514"
context_window = 200000

# Enable extended thinking:
[agent.llm.additional_params]
thinking = { type = "adaptive", budget_tokens = 8000 }

Extra fields:

Field	Type	Default	Description
`api_key`	string	-	Required. Anthropic API key.
`base_url`	string	-	Override the API base URL.

`provider = "bedrock"`

Uses AWS credentials from the environment (AWS profile, IAM role, or environment variables). No API key field.

[agent.llm]
provider = "bedrock"
model = "us.anthropic.claude-3-5-sonnet-20241022-v2:0"
region = "{{ env.AWS_REGION }}"
profile = "default"  # optional
context_window = 200000

Extra fields:

Field	Type	Default	Description
`region`	string	-	Required. AWS region (e.g. `us-east-1`).
`profile`	string	-	AWS profile name. Uses the default credential chain if omitted.

`provider = "gemini"`

[agent.llm]
provider = "gemini"
api_key = "{{ env.GOOGLE_API_KEY }}"
model = "gemini-2.0-flash"
context_window = 1000000

Extra fields:

Field	Type	Default	Description
`api_key`	string	-	Required. Google API key.
`base_url`	string	-	Override the API base URL.

`provider = "ollama"`

No API key required. Defaults to http://localhost:11434.

[agent.llm]
provider = "ollama"
model = "qwen3:30b-a3b"
base_url = "http://localhost:11434"
context_window = 32768
fallback_tool_parsing = true

# Pass Ollama-specific parameters:
[agent.llm.additional_params]
num_ctx = 32768
top_k = 40

Extra fields:

Field	Type	Default	Description
`base_url`	string	`"http://localhost:11434"`	Ollama server URL.
`fallback_tool_parsing`	bool	`false`	Parse tool calls from streamed text output. Enable for models that emit tool calls as text (e.g. some qwen3 variants) rather than native tool-call structures.

`provider = "openrouter"`

Access 300+ models through a single API key. Uses OpenRouter’s reasoning wire format (reasoning + reasoning_details). For other OpenAI-compatible APIs (Fireworks, Together), use provider = "openai" with base_url instead.

[agent.llm]
provider = "openrouter"
api_key = "{{ env.OPENROUTER_API_KEY }}"
model = "anthropic/claude-sonnet-4"
# base_url = "https://custom-endpoint/v1"  # OpenRouter-compatible proxies only

Extra fields:

Field	Type	Default	Description
`api_key`	string	-	Required. OpenRouter API key.
`base_url`	string	-	Override the base URL.

`[mcp]`

Configures Model Context Protocol (MCP) tool servers.

Field	Type	Default	Description
`sanitize_schemas`	bool	`true`	Sanitize tool schemas for OpenAI function-calling compatibility. Fixes `anyOf` unions, missing types, and optional parameters that strict mode rejects.
`user_agent`	string	`"aura/<version>"`	The identity AURA presents to every MCP server, as a `product/version` token. AURA sends it verbatim as the HTTP `User-Agent` header on `http_streamable` and `sse` connections, and splits it into `clientInfo.name` and `clientInfo.version` for the MCP `initialize` handshake on every transport, including `stdio`. When the token has no version part, AURA reports the running AURA version instead. The value must be printable ASCII with a non-empty product part, or the configuration fails to load. Set it when your MCP servers track clients and you want to tell one AURA deployment from another. A server entry can set its own `user_agent` to replace this value for that server alone.
`connect_timeout_secs`	integer	`30`	Seconds to wait for a single MCP server’s connect, initialize, and tool-discovery sequence to finish. If the server does not respond within this window, it is marked failed like any other connection error, rather than blocking the agent. Other servers are unaffected.

[mcp]
sanitize_schemas = true
user_agent = "aura-prod-us/1"  # default is "aura/<version>" (the running AURA version)
connect_timeout_secs = 30

A per-server headers = { "User-Agent" = "..." } entry replaces the header for that server only. The handshake still announces the name and version from user_agent.

`[mcp.servers.<name>]`

Each server is a named entry under [mcp.servers]. The transport field selects the connection type. The server’s key (<name>) is also the namespace of its tools. Use it in a tool-name pattern to select tools from this server only. When more than one server advertises the same tool name, see Tool Names Shared by Multiple Servers.

`transport = "http_streamable"` (recommended)

Connects to an MCP server over HTTP using the current MCP streamable transport (post-2025-11-05).

[mcp.servers.my_tools]
transport = "http_streamable"
url = "http://localhost:8081/mcp"
description = "My tool server"

[mcp.servers.my_tools.headers]
Authorization = "Bearer {{ env.MCP_TOKEN }}"

`transport = "sse"`

Connects using the legacy SSE-based MCP protocol. Supports the same headers, headers_from_request, and scratchpad options as http_streamable.

[mcp.servers.legacy_server]
transport = "sse"
url = "http://localhost:8082/sse"

`transport = "stdio"`

Spawns a local child process. Each agent request creates its own process instance. cmd is a list where cmd[0] is the executable and cmd[1..] are fixed arguments that are part of the command (e.g. a script path). args are additional arguments appended after.

[mcp.servers.everything]
transport = "stdio"
cmd = ["npx"]
args = ["-y", "@modelcontextprotocol/server-everything"]

[mcp.servers.everything.env]
MY_VAR = "value"

# Script-based example:
# cmd = ["python3", "/opt/mcp-servers/weather.py"]
# args = ["--verbose"]

Per-Server `user_agent`

Every transport accepts an optional user_agent that replaces [mcp].user_agent for that server. On http_streamable and sse it also replaces the HTTP User-Agent header; on every transport, including stdio, it replaces the handshake’s clientInfo.name and clientInfo.version. Use it when one server expects a particular product token, or when you want one server to see a deployment tag that the others should not.

[mcp.servers.my_tools]
transport = "http_streamable"
url = "http://localhost:8081/mcp"
user_agent = "aura-prod-us/1"

Static Headers

Add static headers to every request to an HTTP or SSE server:

[mcp.servers.my_tools.headers]
Authorization = "Bearer {{ env.MCP_TOKEN }}"
X-Tenant-ID = "acme"

Header Forwarding (`headers_from_request`)

Forward headers from the incoming API request to the MCP server. The table maps outgoing header name → incoming request header name. Useful for per-user auth delegation.

[mcp.servers.my_tools.headers_from_request]
# Outgoing header = Incoming request header
Authorization = "x-user-token"
X-User-ID = "x-user-id"

When headers_from_request is set, the forwarded header takes precedence over any matching static header from headers.

Per-Tool Scratchpad Thresholds

Override when a tool’s output gets intercepted by the scratchpad system. Keys are tool-name patterns matched against this server’s tool names; the most specific (longest) pattern wins.

[mcp.servers.my_tools.scratchpad]
"get_large_*" = { min_tokens = 100 }  # intercept all large-prefixed tools
"get_small_*" = { min_tokens = 99999 } # effectively disable interception
"get_report"  = { min_tokens = 200 }  # custom threshold for one tool

Tool Names Shared by Multiple Servers

AURA presents MCP tools to the model by their bare names, so only one server’s tool can hold a given name. When more than one server advertises the same tool name, the agent gets the tool from the server whose [mcp.servers.<name>] key sorts first, counting only servers whose tool passes the agent’s or worker’s mcp_filter. For example, [mcp.servers.alpha] wins over [mcp.servers.beta], whatever transport each server uses. The other servers’ tools with that name are unreachable, including through text-fallback tool calls (fallback_tool_parsing). To use the tool from a different server, scope mcp_filter to that server, for example mcp_filter = ["beta:*"], or rename the tool on all but one server. The web server logs a warning for each shared name at startup, and governance catalog sync logs the same warning. The warning names every server that advertises the tool and the server that sorts first. It doesn’t account for mcp_filter, so an agent’s filter can select a different server than the warning names. To find shared names, the web server connects to each agent’s MCP servers once before it starts accepting requests. The servers are checked one at a time, and each connection can take up to [mcp].connect_timeout_secs, so leave room for the check in startup and readiness probe timeouts. The check starts each stdio server’s command and sends only static headers. A server that needs headers from headers_from_request logs a connection warning at startup, and the web server still starts.

Tool-Name Patterns

Several fields select tools by name, and they all use the same pattern syntax:

[agent].mcp_filter and [orchestration.worker.<name>].mcp_filter
[hitl].require_approval
[agent].client_tool_filter
The keys of [mcp.servers.<name>.scratchpad]

AURA checks every pattern when it loads the config. A pattern outside this syntax stops the web server or CLI from starting, and the error names the column of the problem. If you’re upgrading a config written for an earlier AURA release, see Breaking Changes: 5 October 2026. A pattern is built from these parts:

Part	Matches	Example
Letters, digits, `_`, `-`, `/`, and `.`	The same characters	`list_pods` matches only `list_pods`.
`*`	Any sequence of characters, including none	`mezmo_*` matches `mezmo_logs` and `mezmo_`.
`?`	Exactly one character	`tool_?` matches `tool_a` but not `tool_ab`.
`[abc]`	One character from the set	`pod[sx]` matches `pods` and `podx`.
`[!abc]`	One character not in the set	`v[!23]` matches `v1` but not `v2`.
`{a,b}`	Any one of the comma-separated alternatives	`get_{pods,events}` matches `get_pods` and `get_events`.
`<namespace>:<name>`	A tool named `<name>` from an MCP server whose key matches `<namespace>`	`github:*` matches every tool from `[mcp.servers.github]`.

Patterns follow these rules:

A pattern matches the whole tool name, not part of it. list_* matches list_pods but not k8s_list_pods.
Matching is case-sensitive. List* doesn’t match list_pods.
No other characters are allowed, including spaces and \. There is no escape character, and a pattern can’t be empty.
A class holds only letters, digits, _, -, /, and ., so [*] is invalid.
An alternative can contain wildcards and classes, but not another {...}.
A run of letters, digits, _, -, /, and . can be at most 64 characters long. A wildcard, a class, a {, ,, or }, or the : ends the run, and a class’s contents don’t count toward it.

Scope a Pattern to One MCP Server

Prefix a pattern with a namespace and : to match tools from one MCP server. The namespace is the server’s key in [mcp.servers.<name>], so github:create_issue matches create_issue from [mcp.servers.github] and no other server. A pattern without : matches tools from any server. Both segments accept the full pattern syntax, so *:list_pods and git{hub,lab}:list_* are valid. A pattern can contain only one :, and neither segment can be empty. A namespaced pattern never matches a tool that doesn’t come from an MCP server, such as a filesystem tool from [tools].filesystem or a client-side tool. The namespace form is most useful in these fields:

mcp_filter: Select tools from one server, or pick which server provides a shared tool name.
[hitl].require_approval: Gate a tool from one server without gating a tool with the same name from another.

In client_tool_filter, a namespaced pattern is accepted but never matches, because client-side tools have no MCP server. In a [mcp.servers.<name>.scratchpad] key, the namespace is compared with that table’s own server key. Under [mcp.servers.github.scratchpad], the key github:get_report matches the same tool as get_report, and gitlab:get_report matches nothing. This example assumes the config defines [mcp.servers.github] and [mcp.servers.gitlab]:

[agent]
name = "Code Review Assistant"
system_prompt = "You review code changes."
# Every GitHub tool, plus only the list_* tools from GitLab
mcp_filter = ["github:*", "gitlab:list_*"]

The model never sees the namespace. It always receives the bare tool name, such as create_issue. The namespace appears in these places:

tool_namespace on HITL approval webhook items and on aura.approval_requested and aura.approval_pending events. See Human-in-the-Loop Approval Gates.
The tool.namespace attribute on mcp.tool_call spans. See Tracing & Span Layout.
namespace on each tool entry in the governance catalog.

`[agent.scratchpad]`

Controls context window management. When enabled, large MCP tool outputs are saved to disk and replaced with a file pointer. The agent then uses eight exploration tools (head, slice, grep, schema, item_schema, get_in, iterate_over, read) to selectively read the data it needs. See Scratchpad for the full feature guide. Requires memory_dir to be set at the root level and context_window to be set on [agent.llm]. Orchestration also accepts the legacy [orchestration.artifacts].memory_dir as a fallback when the top-level field is absent.

Field	Type	Default	Description
`enabled`	bool	`false`	Activate scratchpad interception.
`context_safety_margin`	float	`0.20`	Fraction of the context window (0.0–1.0) reserved for reasoning and output. Scratchpad intercepts output before this budget is exhausted.
`max_extraction_tokens`	integer	`10000`	Maximum tokens a single exploration tool call may return, preventing a single read from flooding the context.
`turn_depth_bonus`	integer	`6`	Extra tool-call turns added when scratchpad is active, to leave room for exploration calls after interception.

memory_dir = "/tmp/aura-sessions"

[agent]
turn_depth = 10

[agent.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"
context_window = 128000

[agent.scratchpad]
enabled = true
context_safety_margin = 0.20
max_extraction_tokens = 10000
turn_depth_bonus = 6

`[agent.skills]`

Points the agent at directories of on-demand skills. Skills follow the Agent Skills specification: each skill is a subdirectory containing a SKILL.md file with YAML frontmatter (name, description). The name must match the directory name and consist of lowercase alphanumerics and hyphens only (1–64 characters, no leading/trailing/consecutive hyphens). See Skills for the full feature guide.

[[agent.skills.local]]
source = "skills/"        # relative to process CWD, or absolute

[[agent.skills.local]]
source = "/opt/shared-skills"

A load_skill tool is exposed to the agent that loads and executes skills on demand, along with a read_skill_file tool for fetching individual resource files from a skill’s directory. Skills the agent loads stay in context on later turns of the same chat session. See Skill Persistence Across Turns.

`[[vector_stores]]`

Configures RAG (Retrieval-Augmented Generation) stores. Each entry creates a vector_search_<name> tool the agent can call. Multiple stores create multiple search tools.

Field	Type	Description
`name`	string	Unique identifier. Used in worker `vector_stores` lists.
`context_prefix`	string	Optional hint shown to the LLM describing what the store contains.
`type`	string	Store type: `in_memory`, `qdrant`, or `bedrock_kb`.

`type = "qdrant"`

[[vector_stores]]
name = "docs"
type = "qdrant"
url = "http://localhost:6334"
collection_name = "documents"
context_prefix = "Technical documentation and API references"

[vector_stores.embedding_model]
provider = "openai"
model = "text-embedding-3-small"
api_key = "{{ env.OPENAI_API_KEY }}"

`type = "in_memory"`

[[vector_stores]]
name = "knowledge"
type = "in_memory"

[vector_stores.embedding_model]
provider = "openai"
model = "text-embedding-3-small"
api_key = "{{ env.OPENAI_API_KEY }}"

`type = "bedrock_kb"`

Managed RAG uses AWS credentials, so no embedding model is needed.

[[vector_stores]]
name = "company_docs"
type = "bedrock_kb"
knowledge_base_id = "{{ env.BEDROCK_KB_ID }}"
region = "{{ env.AWS_REGION }}"
# profile = "default"  # optional
# managed = true  # optional
context_prefix = "Company documentation"

Extra fields:

Field	Type	Default	Description
`knowledge_base_id`	string	-	Required. Bedrock Knowledge Base ID.
`region`	string	-	Required. AWS region (e.g. `us-east-1`).
`profile`	string	-	AWS profile name. Pins the Knowledge Base client to this profile; uses the default credential chain if omitted.
`managed`	bool	`false`	Set to `true` when the store points at a Bedrock managed knowledge base; Aura then sends `managedSearchConfiguration` instead of `vectorSearchConfiguration` on retrieve requests. Leave it `false` or omit it for a classic vector-store-backed knowledge base.

When you set profile, the Knowledge Base client uses only that AWS profile’s credentials, even if static AWS environment credentials (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) are also present. When you omit profile, it falls back to the default AWS credential chain. This makes profile-based cross-account access reliable alongside static environment credentials used elsewhere in the deployment. For example, an IRSA (IAM Roles for Service Accounts) profile that assumes a role via web identity. Both managed and classic Bedrock knowledge bases handle embeddings for you. The managed flag only selects which kind of knowledge base the store points at. If you leave managed unset or false for a managed knowledge base, retrieve requests fail with a ValidationException. The full error reads:

Incompatible configuration: vectorSearchConfiguration is not supported for managed knowledge bases. Use managedSearchConfiguration instead.

Set managed = true to resolve it.

Embedding Models

Used by in_memory and qdrant types.

# OpenAI:
[vector_stores.embedding_model]
provider = "openai"
model = "text-embedding-3-small"
api_key = "{{ env.OPENAI_API_KEY }}"

# AWS Bedrock:
[vector_stores.embedding_model]
provider = "bedrock"
model = "amazon.titan-embed-text-v2:0"
region = "{{ env.AWS_REGION }}"
profile = "default"  # optional

`[tools]`

Enables built-in server-side tools.

Field	Type	Default	Description
`filesystem`	bool	`false`	Expose basic read-only filesystem tools (read file, list directory) to the agent.
`custom_tools`	list of strings	`[]`	Reserved for future use.

[tools]
filesystem = true

`[hitl]`

Human-in-the-loop (HITL) approval gates let an agent ask for permission before running selected MCP tools. [hitl] is the enable bit — there is no separate enabled field; presence of the table turns it on, and route is required when it’s present. See HITL for the full route contracts, SSE lifecycle events, and current scope (single-agent vs. orchestration worker gating).

Field	Type	Default	Description
`require_approval`	list of strings	`[]`	Tool-name patterns that gate a matching MCP tool call behind approval. Accepts `<namespace>:<name>` to gate tools from one MCP server.
`route`	table	required	The decision route: see `[hitl.route]` below.

`[hitl.route]`

Tagged by mode: "conversational" or "webhook".

Field	Type	Default	Description
`mode`	string	-	Required. `"conversational"` (attended, over an open SSE stream) or `"webhook"` (unattended, posts to a URL).
`timeout_secs`	integer	`60` (conversational) / `300` (webhook)	Seconds to wait for a decision before failing closed.
`url`	string	-	Required for `webhook` mode only. Must start with `http://` or `https://`.

[hitl]
require_approval = ["kubectl_*", "restart_*", "dangerous_*"]

[hitl.route]
mode = "webhook"
url = "https://approvals.example.com/aura"
timeout_secs = 300

Session Store (Durable and Multi-Pod Deployments)

Unlike every other section on this page, the session store is not configured in TOML. It’s deployment infrastructure (one instance per server, not per-agent), so it’s configured only via environment variables. By default, cross-request session state (A2A tasks, parked HITL approvals, and skill-invocation logs) lives in process memory. Correct for a single pod, the CLI, and local dev. Behind a load balancer with multiple replicas, configure a shared Redis/Valkey backend and every cross-request flow works no matter which pod serves each request: A2A message:send → poll → list → history-by-context, A2A subscribe/cancel against a task executing on another pod, and conversational HITL approvals resolved by a POST /v1/approvals/{id} that lands away from the pod that parked them.

export AURA_SESSION_STORE=redis                          # memory (default) | redis
export AURA_SESSION_STORE_URL=redis://valkey:6379        # redis:// or rediss:// (Valkey compatible)
export AURA_SESSION_STORE_PREFIX=aura:prod               # optional namespace (default "aura")
export AURA_SESSION_STORE_CONNECT_TIMEOUT_SECS=5         # optional
export AURA_SESSION_STORE_TASK_TTL_SECS=86400            # optional; 0 = no expiry
export AURA_SESSION_STORE_SKILLS_TTL_SECS=86400          # optional; 0 = no expiry

AURA_SESSION_STORE_SKILLS_TTL_SECS sets how long a chat session’s skill-invocation log lives after the agent last calls load_skill or read_skill_file. It defaults to 86400 (24 hours), and 0 disables expiry. The Redis and file backends apply it. The memory backend has no expiry and clears its logs on restart. See Skill Persistence Across Turns. The server pings the backend at startup and fails fast if it is unreachable; /health reports the backend and its ping latency. The Redis backend requires building with the session-store-redis cargo feature (cargo build --release --features aura-cli/session-store-redis). The in-memory backend is always available. See the session storage design doc for the design and Helm packaging roadmap.

`[orchestration]`

Enables multi-agent orchestration mode. A coordinator agent decomposes user queries into tasks and delegates them to specialized worker agents for parallel execution. The coordinator’s system prompt comes from [agent].system_prompt. Workers are defined in [orchestration.worker.<name>] sections. Execution loop:

Plan: coordinator decomposes the request into a task DAG.
Execute: dependency-ready tasks run in parallel waves on worker agents.
Continue: coordinator consolidates worker outputs and routes to a final response, replan, or clarification.

Workers run with isolated task context windows and filtered MCP/vector-store access based on each worker block.

Field	Type	Default	Description
`enabled`	bool	`false`	Activate orchestration mode.
`max_planning_cycles`	integer	`3`	Maximum plan→execute→continue cycles per request.
`max_plan_parse_retries`	integer	`3`	Retries on plan parse failure before falling back to single-task execution.
`allow_direct_answers`	bool	`true`	Allow the coordinator to answer simple queries directly without delegating.
`allow_clarification`	bool	`true`	Allow the coordinator to ask for clarification on ambiguous queries.
`tools_in_planning`	string	`"summary"`	How much tool info is shown during planning: `"none"`, `"summary"` (tool names per worker), or `"full"` (names + descriptions).
`max_tools_per_worker`	integer	`10`	Truncates the tool list per worker in the planning prompt with a `(+N more)` suffix.
`coordinator_vector_stores`	list of strings	`[]`	Names of vector stores the coordinator can access.
`worker_system_prompt`	string	-	Custom system prompt injected into generic (non-specialized) workers.
`duplicate_call_nudge_threshold`	integer	`3`	Consecutive identical tool calls before appending a guidance annotation.
`duplicate_call_block_threshold`	integer	`5`	Consecutive identical tool calls before appending an abort annotation.

[orchestration]
enabled = true
max_planning_cycles = 3
allow_direct_answers = true
tools_in_planning = "full"
coordinator_vector_stores = ["runbooks"]
memory_dir = "/tmp/aura-orchestration"   # legacy flat field; prefer top-level memory_dir

`[orchestration.timeouts]`

Field	Type	Default	Description
`per_call_timeout_secs`	integer	`0` (disabled)	Per-call timeout for coordinator and worker LLM calls. Set to a positive value to enable.
`stream_inactivity_timeout_secs`	integer	`0` (disabled)	Max seconds of silence between stream items on coordinator and worker orchestration streams before Aura fails the affected task with a no-stream-progress error. Suspends during tool execution and re-arms on each stream item. Must be below `per_call_timeout_secs` (when set) to take effect. Set to a positive value to enable.

See request lifecycle for the operational guidance and caveats on this timeout.

[orchestration.timeouts]
per_call_timeout_secs = 120
stream_inactivity_timeout_secs = 60

`[orchestration.artifacts]`

Controls persistence and artifact promotion.

Field	Type	Default	Description
`memory_dir`	string	-	Base directory for run artifacts. Alias: `memory_path`. (Prefer top-level `memory_dir`.)
`result_artifact_threshold`	integer	`4000`	Character threshold for writing worker results to artifact files instead of inlining them.
`result_summary_length`	integer	`2000`	Max inline summary length when a result is promoted to an artifact.
`session_history_turns`	integer	`3`	Max prior run manifests injected as session context in the coordinator preamble. Set to `0` to disable.
`persistence_drain_timeout_ms`	integer	`2000`	Timeout (ms) for draining in-flight persistence writes between execution phases.
`tool_output_artifact_threshold`	integer	`500`	Character threshold for promoting tool outputs to artifact files.
`tool_output_duration_threshold_ms`	integer	`5000`	Duration threshold (ms) for promoting tool outputs regardless of size.
`show_tool_reasoning_in_continuation`	bool	`false`	Include condensed tool reasoning traces in continuation prompts so the coordinator can see why workers called specific tools.
`max_session_runs`	integer	`20`	Max run directories retained per session before oldest runs are pruned. Set to `0` to disable pruning.

[orchestration.artifacts]
memory_dir = "/tmp/aura-orchestration"
result_artifact_threshold = 4000
result_summary_length = 2000
session_history_turns = 3
max_session_runs = 20

`[orchestration.worker.<name>]`

Defines a specialized worker. Worker names must be unique case-insensitively (to avoid filesystem collisions) and non-empty.

Field	Type	Default	Description
`description`	string	-	Required. One-line description shown to the coordinator during planning.
`preamble`	string	-	Required. Complete system prompt for this worker (replaces the generic worker template).
`mcp_filter`	list of strings	-	Tool-name patterns selecting which MCP tools this worker can access. When omitted, all tools are included; an empty list `[]` grants no tools. Accepts `<namespace>:<name>` to select tools from one MCP server.
`vector_stores`	list of strings	`[]` (none)	Names of vector stores this worker can access. Workers have no RAG access by default.
`turn_depth`	integer	(inherits `[agent].turn_depth`)	Max tool-call rounds for this worker.

[orchestration.worker.operations]
description = "Logs, pipelines, metrics, and system analysis"
preamble = """
You are an Operations Specialist with access to observability tools.
Use tools to investigate incidents — do not fabricate data.
"""
mcp_filter = ["mezmo_*"]
vector_stores = ["runbooks"]
turn_depth = 8

Per-Worker LLM Override

Workers inherit [agent.llm] by default. Provide [orchestration.worker.<name>.llm] to use a different model for a specific worker (e.g. a cheaper model for simple tasks).

[orchestration.worker.summarizer.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o-mini"
context_window = 128000

Per-Worker Scratchpad Override

[orchestration.worker.analyst.scratchpad]
enabled = true
max_extraction_tokens = 5000

Per-Worker Skills Override

None (field absent) inherits [agent.skills]. An explicit empty list disables skills. A non-empty list replaces the agent’s skills entirely (no merging).

[[orchestration.worker.researcher.skills.local]]
source = "skills/research"

Complete Examples

Minimal: OpenAI

[agent]
name = "Assistant"
system_prompt = "You are a helpful assistant."

[agent.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"

Single Agent with MCP Tools

[mcp]
sanitize_schemas = true

[mcp.servers.github]
transport = "http_streamable"
url = "https://api.githubcopilot.com/mcp/"
description = "GitHub repository operations"

[mcp.servers.github.headers]
Authorization = "Bearer {{ env.GITHUB_PERSONAL_ACCESS_TOKEN }}"

[agent]
name = "DevOps Assistant"
system_prompt = """
You are a DevOps assistant with access to GitHub.
Help with code review, PR management, and repo exploration.
"""
turn_depth = 10

[agent.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"

Single Agent with Scratchpad

Large tool outputs are intercepted and saved to disk; the agent uses exploration tools to read what it needs.

memory_dir = "/tmp/aura-sessions"

[agent]
name = "Data Analyst"
system_prompt = """
You are a data analysis assistant. When you see a scratchpad pointer
([scratchpad: file_id=...]), use the exploration tools (head, grep, schema,
get_in, etc.) to selectively read the data you need. Do not re-call the
original tool.
"""
turn_depth = 10

[agent.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"
context_window = 128000

[agent.scratchpad]
enabled = true
context_safety_margin = 0.20
max_extraction_tokens = 10000

[mcp.servers.data_api]
transport = "http_streamable"
url = "http://localhost:9000/mcp"

[mcp.servers.data_api.scratchpad]
"get_dataset_*" = { min_tokens = 100 }

Multi-Agent Orchestration with Per-Worker Models

memory_dir = "/tmp/aura-orchestration"

[agent]
name = "SRE Coordinator"
system_prompt = """
You are an SRE coordinator. Decompose observability tasks into sub-tasks
and delegate to the appropriate specialist worker.
- Kubernetes cluster state and workloads: delegate to k8s-specialist
- Prometheus metrics and alerts: delegate to metrics-analyst
"""

[agent.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"
context_window = 128000

[mcp.servers.kubernetes]
transport = "http_streamable"
url = "http://localhost:8081/mcp"

[mcp.servers.prometheus]
transport = "http_streamable"
url = "http://localhost:8082/mcp"

[orchestration]
enabled = true
max_planning_cycles = 3
tools_in_planning = "full"
allow_direct_answers = true

[orchestration.timeouts]
per_call_timeout_secs = 120

[orchestration.worker.k8s-specialist]
description = "Kubernetes cluster inspection: namespaces, workloads, pods, events"
turn_depth = 8
mcp_filter = ["namespaces_list", "pods_*", "resources_*", "events_list"]
preamble = """
You are a Kubernetes Specialist. Use tools to inspect the cluster.
Never guess cluster state — always call the relevant tool first.
"""

[orchestration.worker.k8s-specialist.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"
context_window = 128000

[orchestration.worker.metrics-analyst]
description = "Prometheus metrics queries, target health, and alert status"
turn_depth = 8
mcp_filter = ["execute_query", "execute_range_query", "list_metrics", "get_targets"]
preamble = """
You are a Prometheus Analyst. Query metrics directly — do not fabricate values.
Report metric names, labels, and exact values from tool results.
"""

[orchestration.worker.metrics-analyst.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o-mini"
context_window = 128000

RAG with Qdrant

[[vector_stores]]
name = "docs"
type = "qdrant"
url = "http://localhost:6334"
collection_name = "documents"
context_prefix = "Technical documentation and API references"

[vector_stores.embedding_model]
provider = "openai"
model = "text-embedding-3-small"
api_key = "{{ env.OPENAI_API_KEY }}"

[[vector_stores]]
name = "runbooks"
type = "qdrant"
url = "http://localhost:6334"
collection_name = "runbooks"
context_prefix = "Operational runbooks and incident response procedures"

[vector_stores.embedding_model]
provider = "openai"
model = "text-embedding-3-small"
api_key = "{{ env.OPENAI_API_KEY }}"

[agent]
name = "Knowledge Assistant"
system_prompt = """
You are a knowledge assistant. Use the vector_search_docs and
vector_search_runbooks tools to ground your answers in documentation.
"""

[agent.llm]
provider = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"
model = "gpt-4o"

Local Ollama (No API Key)

[agent]
name = "Local Assistant"
system_prompt = "You are a helpful assistant running locally."

[agent.llm]
provider = "ollama"
model = "qwen3:30b-a3b"
base_url = "http://localhost:11434"
context_window = 32768
fallback_tool_parsing = true

[agent.llm.additional_params]
num_ctx = 32768

AWS Bedrock with Knowledge Base

[[vector_stores]]
name = "company_kb"
type = "bedrock_kb"
knowledge_base_id = "{{ env.BEDROCK_KB_ID }}"
region = "{{ env.AWS_REGION }}"
context_prefix = "Company internal documentation"

[agent]
name = "Enterprise Assistant"
system_prompt = """
You are an enterprise assistant. Use the company knowledge base
to answer questions grounded in internal documentation.
"""

[agent.llm]
provider = "bedrock"
model = "us.anthropic.claude-3-5-sonnet-20241022-v2:0"
region = "{{ env.AWS_REGION }}"
context_window = 200000

​Environment Variable Interpolation

​Root-Level Fields

​[agent]

​Multiple Agents

​[agent.llm]

​Common Fields

​provider = "openai"

​provider = "anthropic"

​provider = "bedrock"

​provider = "gemini"

​provider = "ollama"

​provider = "openrouter"

​[mcp]

​[mcp.servers.<name>]

​transport = "http_streamable" (recommended)

​transport = "sse"

​transport = "stdio"

​Per-Server user_agent

​Static Headers

​Header Forwarding (headers_from_request)

​Per-Tool Scratchpad Thresholds

​Tool Names Shared by Multiple Servers

​Tool-Name Patterns

​Scope a Pattern to One MCP Server

​[agent.scratchpad]

​[agent.skills]

​[[vector_stores]]

​type = "qdrant"

​type = "in_memory"

​type = "bedrock_kb"

​Embedding Models

​[tools]

​[hitl]

​[hitl.route]

​Session Store (Durable and Multi-Pod Deployments)

​[orchestration]

​[orchestration.timeouts]

​[orchestration.artifacts]

​[orchestration.worker.<name>]

​Per-Worker LLM Override

​Per-Worker Scratchpad Override

​Per-Worker Skills Override

​Complete Examples

​Minimal: OpenAI

​Single Agent with MCP Tools

​Single Agent with Scratchpad

​Multi-Agent Orchestration with Per-Worker Models

​RAG with Qdrant

​Local Ollama (No API Key)

​AWS Bedrock with Knowledge Base

Environment Variable Interpolation

Root-Level Fields

`[agent]`

Multiple Agents

`[agent.llm]`

Common Fields

`provider = "openai"`

`provider = "anthropic"`

`provider = "bedrock"`

`provider = "gemini"`

`provider = "ollama"`

`provider = "openrouter"`

`[mcp]`

`[mcp.servers.<name>]`

`transport = "http_streamable"` (recommended)

`transport = "sse"`

`transport = "stdio"`

Per-Server `user_agent`

Static Headers

Header Forwarding (`headers_from_request`)

Per-Tool Scratchpad Thresholds

Tool Names Shared by Multiple Servers

Tool-Name Patterns

Scope a Pattern to One MCP Server

`[agent.scratchpad]`

`[agent.skills]`

`[[vector_stores]]`

`type = "qdrant"`

`type = "in_memory"`

`type = "bedrock_kb"`

Embedding Models

`[tools]`

`[hitl]`

`[hitl.route]`

Session Store (Durable and Multi-Pod Deployments)

`[orchestration]`

`[orchestration.timeouts]`

`[orchestration.artifacts]`

`[orchestration.worker.<name>]`

Per-Worker LLM Override

Per-Worker Scratchpad Override

Per-Worker Skills Override

Complete Examples

Minimal: OpenAI

Single Agent with MCP Tools

Single Agent with Scratchpad

Multi-Agent Orchestration with Per-Worker Models

RAG with Qdrant

Local Ollama (No API Key)

AWS Bedrock with Knowledge Base