#Configuration Reference

All configuration files use TOML format with a required integer format_version = 1 at the top level. Documents are validated at the load boundary by strictspec-generated validators -- malformed documents produce hard errors with diagnostic paths, never silent degradation.

#agent.toml

Agent definitions live in individual .toml files. Each file defines one agent with its identity, model routing, tool permissions, and optional inline tool declarations. Load with orxtra.agent.load_agent(path) or batch-load a directory with orxtra.agent.load_agents(directory).

Prompt text lives in a separate .md file referenced by the prompt field. The loader resolves the path relative to the TOML file, reads the markdown, and performs include resolution via orxtra.compose.

#[agent] section

Routing constraints: Exactly one routing form must be present:

• category alone (resolved against categories.toml at runtime), OR
• provider AND model together (direct provider/model specification)

Setting both category and provider/model is a validation error. Omitting both is also an error.

#[tools] section

#[[tools.define]] -- inline tool declarations

Each [[tools.define]] entry declares an inline tool. These are shape-checked at agent-load time; full parameter/execution/output validation is deferred to the DataToolDefinition schema at build time.

#Example

format_version = 1

[agent]
name = "coder"
description = "Agent that writes code, runs tests, and commits changes."
prompt = "coder_agent.md"
category = "default"

[tools]
allow = ["read", "write", "edit", "git", "custom.*", "start_task", "end_task"]

[[tools.define]]
name = "pytest"
description = "Run the test suite"
namespace = "custom.exec"
deferred = false

[tools.define.execution]
type = "command"
executable = "pytest"
arg_validation = true
timeout_ceiling = 120

#workflow.toml

Workflow definitions describe a DAG of tasks for the scheduler to execute. Load with orxtra.scheduler.load_workflow(path_or_string).

#[workflow] section

**escalation_policy values:**

#[[tasks]] -- task definitions

Each [[tasks]] entry defines one task. Tasks support exactly one execution mode, determined by which fields are present.

#Identity and common fields

#Execution modes

Exactly one of the following execution mode groups must be present. The modes are mutually exclusive.

Agent mode -- agent + task_prompt (co-present: both required together):

Callable mode -- a Python callable reference:

Subtasks mode -- nested task tree:

Wait-for mode -- event-driven waking:

Decision-point mode -- human/overseer decision gate:

#Retry fields

These fields become conditionally required when retry is set to a non-zero value.

#For-each fields

These fields become conditionally required when for_each is present.

#Pre-checks and post-checks

Both [tasks.prechecks] and [tasks.postchecks] share the same structure. They define verification gates for task entry and exit.

Each agent check entry:

#[dependencies] section (optional)

A top-level dependency map as an alternative to per-task depends_on. Keys are task names, values are arrays of dependency task names. The loader merges these into each task's depends_on field.

[dependencies]
test = ["implement"]
lint = ["implement"]

#[[services]] -- long-running process declarations (optional)

#Example

format_version = 1

[workflow]
name = "feature-pipeline"
description = "Implement a feature with tests and lint check."

[[tasks]]
name = "implement"
agent = "coder"
task_prompt = "Implement the feature described in the project spec."
timeout = 600
context_refinement = true

[[tasks]]
name = "test"
agent = "coder"
task_prompt = "Write tests for the implementation."
depends_on = ["implement"]
timeout = 600
context_refinement = true

[tasks.postchecks]
scripts = ["myproject.checks:pytest_passes"]

[[tasks]]
name = "lint"
agent = "coder"
task_prompt = "Fix any lint issues found by ruff."
depends_on = ["implement"]
timeout = 600
context_refinement = true

[tasks.postchecks]
scripts = ["myproject.checks:ruff_passes"]

#categories.toml

Maps category names to "provider/model" strings. Categories provide a layer of indirection for model routing -- agents reference a category name, and the categories file resolves it to a concrete provider and model.

Load with orxtra.agent.load_categories(path). Resolve with orxtra.agent.resolve_category(agent, categories).

#[categories] section

A map of category name to model string. Keys must match ^[A-Za-z0-9_.-]+$. Values are "provider/model" strings and must be non-empty.

#Example

format_version = 1

[categories]
default = "anthropic/claude-sonnet-4-6"
reasoning = "anthropic/claude-opus-4-6"
fast = "openai/gpt-4o-mini"

#Run configuration (run_config.toml)

Run configuration files drive start_run_from_file in orxtra.services. They bundle all paths, database connection, provider credentials, budget, and autonomy policy for a single run.

All fields are validated by a strictspec gate at load time. Path strings are coerced to Path objects and budget strings to Decimal after validation.

#provider_configs format

Each provider entry is a map with a required type field and provider-specific settings:

[provider_configs.anthropic]
type = "anthropic"
api_key = "sk-ant-..."

[provider_configs.openai]
type = "openai"
api_key = "sk-..."

Supported provider types and their fields:

If api_key is omitted from the provider config, the provider reads it from the corresponding environment variable (see Environment Variables below).

#autonomy_level values

#budget_exhaustion_policy values

#Example

format_version = 1

workflow_path = "./workflows/pipeline.toml"
agents_dir = "./agents/"
knowledge_dir = "./knowledge/"
categories_path = "./categories.toml"
read_root = "/home/user/project"
db_url = "postgres://orxtra:password@localhost:5432/orxtra"
budget = "10.00"
autonomy_level = "medium"
budget_exhaustion_policy = "block_new"
tools_dir = "./tools/"

[provider_configs.anthropic]
type = "anthropic"
api_key = "sk-ant-..."

[secrets_env]
GITHUB_TOKEN = "GITHUB_TOKEN"
SLACK_WEBHOOK = "SLACK_WEBHOOK_URL"

#Knowledge files (knowledge.toml)

Knowledge files inject constraints into a run's constraint memory. Place them in the knowledge_dir referenced by the run configuration. Load with orxtra.overseer.load_knowledge_files(directory).

#[[constraints]]

#Example

format_version = 1

[[constraints]]
text = "All database migrations must be backward-compatible."
tier = "hard"
kind = "architecture"

[[constraints]]
text = "Prefer composition over inheritance."
tier = "soft"
kind = "style"

#Data tool definitions (tool.toml)

Data-defined tools are standalone TOML files in the tools_dir. They define custom tools with typed parameters and one of three execution backends: HTTP, Monty (sandboxed Python), or command. Load with orxtra.tool.load_tool_definitions(directory).

#[tool] section

#[params] section (optional)

A map of parameter name to parameter definition. Keys must match ^[A-Za-z_][A-Za-z0-9_]*$.

Each parameter:

#[execution] section

A discriminated union on the type field. Exactly one execution type must be configured.

#HTTP execution (type = "http")

#Monty execution (type = "monty")

Limits table:

#Command execution (type = "command")

#[output] section (optional)

#A2A skill definitions (skill.schema.toml)

A2A skill descriptors map A2A protocol skill IDs to orxtra capabilities.

#Environment variables

#LLM provider API keys

These are read by the transport providers when api_key is not explicitly passed in the provider configuration:

Missing environment variables when the provider needs them produce a KeyError, not a silent fallback.

#Worker environment variables

These are set inside Docker worker containers by DockerWorker:

#Secret substitution

Secret references in tool arguments ({{secret:NAME}}) are resolved by the secrets module. The secrets_env map in run configuration defines which environment variables back which secret names. The create_secret_registry factory reads each mapped environment variable from os.environ -- a missing variable is a hard error (KeyError), never a silent default.

#Database configuration

orxtra uses PostgreSQL (via asyncpg) for persistent state. The database URL is specified in the run configuration's db_url field as a standard PostgreSQL connection string:

postgres://user:password@host:port/database

Both userinfo passwords (postgres://u:pw@host/db) and query-parameter passwords (postgres://host/db?password=pw) are supported. Passwords are redacted in serialized run configs stored in the database.

Each module owns its own schema, managed by pgdesign via TOML schema files in the schema/ directory: