Configuration

A mono-agent is declared by mono-agent.config.json in its agent folder. Start here for the loading rules and top-level structure. Use the annotated blueprint for a broad example and the generated config reference for the complete field list.

The one config file

The file brings the agent’s model routes, context, channels, memory, tools, sandbox, and observability together. In normal CLI use, relative paths resolve from the agent folder. Programmatic callers choose that base with cwd.

Scaffold a new agent with the CLI:

mono-agent init --model openai-codex:gpt-5.6-terra

A minimal valid config has exactly two fields:

{
  "runtime": { "model": "openai-codex:gpt-5.6-terra" },
  "context": { "identityPath": "./IDENTITY.md" }
}

runtime.model is a <provider>:<model> reference served by the Pi runtime (openai-codex:*, anthropic:*, opencode-go:*, local providers, and more; a legacy pi: prefix is canonicalized away). context.identityPath points at the identity markdown. All other fields are optional, but omission does not always mean disabled: the loopback tui operator endpoint defaults on, and the interaction bridge can auto-start when its tools are available.

How configuration is loaded

Core configuration has one precedence order:

mono-agent.config.json — the declared value.
Built-in default — used when the JSON field is omitted.

Former core MONO_AGENT_* configuration variables are silently ignored. The CLI still loads .env for credentials named by apiKeyEnv-style JSON fields, for adapter-owned inputs, and for operational process plumbing. Use --env-file <path> to choose another dotenv file.

See Operational environment variables for the remaining non-core environment contracts.

Sections at a glance

Each top-level key maps to one capability area. All are optional except the two required fields noted above.

Section	Purpose	Page
`agent`	Public display name; never used for paths, service ids, sessions, or provider identity	Identity & Soul
`runtime`	Model, effort, sessions, fallbacks	Runtime
`concurrency`	Per-channel admission and provider-execution bounds	Sessions and concurrency
`providers`	Provider map: local/self-hosted providers, Pi credentials, engine-turn tuning	Providers, Local Providers
`context`	Identity, soul, selected skills	Context Assembly
`memory`	Tiered memory (lite/journal/bujo), embeddings, consolidation	Capture & Recall
`tools`	Allow-all-by-default, runtime-enforced allow/deny policy; MCP servers	Tool Policy, MCP
`continuations`, `interaction`	Durable asynchronous results, ask-the-user, and progress bridges	Durable continuations, Delivery and send tools
`sandbox`	Filesystem/network sandboxing for runtime commands	Sandbox
`artifacts`, `traceability`	JSONL run artifacts and trace registry	Observability
`telegram`, `slack`	Built-in chat channels (opt-in via `enabled`)	Channels
`webhook`, `openaiApi`, `cron`	Built-in HTTP, OpenAI-compatible, and scheduled channels	Channels
`tui`	Default-on loopback operator endpoint	Operator stream endpoint
`channels.plugins[]`	External channel packages such as WhatsApp and A2A	Write your own channel adapter

Channels start independently. For most channels, omission or enabled: false reports disabled; the default-on tui endpoint reports disabled only when explicitly opted out. An enabled channel that lacks required settings reports waiting_for_config. A self-recovering transport can temporarily report degraded without stopping healthy channels.

How sections activate

Activation depends on the surface:

Core behavior is configured by its block. memory, sandbox, concurrency, and observability take effect when configured. Some supporting blocks, such as providers, only matter when another selection uses them.
Most external channels are opt-in. telegram, slack, webhook, and openaiApi require enabled: true. Cron runs only enabled jobs. Plugin channels require a channels.plugins[] entry and follow the plugin’s own config contract.
The operator endpoint is opt-out. tui defaults to enabled on loopback; set its enabled field to false to remove it.
Host bridges have their own gates. continuations uses its enabled flag. Interaction may auto-start from allowed ask tools, explicit interaction settings, or configured progress delivery.

If a channel section seems ignored, check enabled first — mono-agent validate reports it as disabled rather than waiting.

Coverage types

The Feature Registry tags each capability so you know how to reach it:

Type	Meaning
`config`	Declarable in `mono-agent.config.json`
`cli`	Reached through a `mono-agent` CLI flag/command
`auto`	Always active when the app runs; needs no declaration
`code`	Programmatic escape hatch only — intentional
`dev`	Development/test tooling, not part of a running agent

Validate before you run

mono-agent validate reports the resolved runtime, provider credentials, context, memory, tools, sandbox, observability, secret placement, and channel state. Exit code 0 means the config is structurally valid; a waiting section still needs attention and is not an Agent ready result. Duplicate JSON object keys at any depth are an error-level core finding with their path (for example, processJobs.maxActivePerConversation); doctor reports the same finding. At runtime the loader warns and continues with JSON’s last-value-wins behavior, so correct the duplicate and validate before restarting. Static validation does not make a model request. See CLI reference → validate for the liveness and guided-init distinctions.

mono-agent validate
mono-agent start     # traceability + every configured channel

On start, each channel prints its initial state: running, waiting_for_config, disabled, or failed. A running transport that later enters self-recovery can report degraded until it recovers.

Blueprint — a broad annotated mono-agent.config.json example.
Generated Config Reference — the generated key table and JSON Schema URL.
Operational Environment Variables — secrets and process plumbing.
Folder Layout — files and directories around the config.
Feature Matrix — canonical capability → config key reference.