Guides/Agent Configuration

Agent Configuration

Per-agent settings for autonomy, read-only mode, resources, capabilities, execution timeout, reliability, and runtime.

The Settings Tab

The Agent Detail page has a Settingstab (visible to owners only) — a sectioned home for per-agent configuration. Current sections:

•Guardrails — see Agent Guardrails

•Parallel Capacity — below

•Expose via MCP — publish the agent as a dedicated MCP tool; see MCP Integration

•Trinity access key — the agent-scoped key the agent uses to call Trinity's own MCP tools, with health status and a Regenerate action (the running container is replaced to pick the new key up)

•Reliability — the dispatch circuit breaker (below) and Wake this agent when an operator answers (below)

•Voice — let the agent reply with spoken voice notes on messaging channels; see Voice Replies

•Cross-model validation — appears only on entitled installations

The remaining settings below are managed from the agent header controls, the Running/Autonomy toggles on the Dashboard, or the API.

Parallel Capacity

How many tasks the agent may run concurrently (max_parallel_tasks, default 3). Work beyond the limit queues and drains as slots free up.

•Set it in the Settings tab's Parallel Capacity section; the panel shows current slot usage (“using X / Y slots”).

•Fleet ceiling (admin) — an admin caps the whole fleet via GET/PUT /api/settings/max-parallel-tasks-ceiling (default 10, range 1–32). Owners pick any value up to the ceiling. If an agent's stored value exceeds a later-lowered ceiling, the stored value is kept but the effective limit is clamped to the ceiling — the panel shows a notice when this applies.

•API — GET /api/agents/{name}/capacity returns the stored value, the ceiling, and the effective limit.

Autonomy Mode

Master gate for the agent's scheduled operations.

•Toggle from the Dashboard (Grid tile or List row) or the Agent Detail header

•When disabled, none of the agent's schedules fire

•The toggle does not change each schedule's own on/off switch: a schedule you disabled stays disabled when you turn autonomy back on, and one you left enabled resumes automatically

•API — GET /api/agents/{name}/autonomy and PUT /api/agents/{name}/autonomy

Read-Only Mode

Prevents modification of source files (*.py, *.js, etc.) inside the agent container.

•Toggle in the Agent Header

•Uses PreToolUse hooks to intercept Write, Edit, and NotebookEdit tool calls

•Allowed patterns: output/*, content/* (generated files are permitted)

•API — GET /api/agents/{name}/read-only and PUT /api/agents/{name}/read-only

Resource Allocation

Per-agent memory and CPU limits, enforced at the container level (Linux cgroups).

•Open the resource modal from the agent header (gear button, “Configure resources”). Each limit can also be left as “Inherit default”.

•Memory options: 1g, 2g, 4g, 8g, 16g, 32g, 64g. CPU options: 1, 2, 4, 8, 16 cores.

•Changes take effect on the next agent restart.

•API — GET /api/agents/{name}/resources and PUT /api/agents/{name}/resources

•Full capabilities mode — grants containers system-level access (Docker socket, network tools) when needed

Fleet-wide defaults (admin): the default CPU and memory for new agent containers are set platform-wide via GET/PUT /api/settings/agent-defaults/resources(admin-only; CPU 1/2/4/8/16, memory 1g–32g). Changes apply to new containers only — restart existing agents to pick up new defaults.

Execution Timeout

Configurable time limit for agent executions.

•Range: 60–7200 seconds (default: 3600 seconds / 60 minutes).

•Applies to all trigger methods: task, chat, schedule, MCP, and paid endpoints.

•Slot TTL is set to the timeout value plus a 5-minute buffer.

•Schedule ceiling — the agent timeout is the ceiling for every one of its schedules. Setting an agent timeout below an active schedule's timeout_seconds is rejected with 400 error=agent_timeout_below_active_schedules. Conversely, creating or updating a schedule with timeout_seconds > agent.execution_timeout_seconds is rejected with 400 error=schedule_timeout_exceeds_agent_cap. Raise the agent cap first, then the schedule.

•API — GET /api/agents/{name}/timeout and PUT /api/agents/{name}/timeout

Dispatch Circuit Breaker

Optional per-agent protection (default: off) that stops sending new work to an agent whose container repeatedly answers with authentication failures — for example, an expired API key. Instead of queueing tasks that are doomed to fail, the platform rejects new executions immediately with 503 and a Retry-After header, and fails any tasks already queued for that agent.

How it behaves when enabled:

•After 3 consecutive authentication failures, the breaker opens and new dispatches fast-fail.

•Recovery is automatic: after a cooldown, one probe execution is let through. Success closes the breaker; failure extends the cooldown (exponential backoff).

•Timeouts and ordinary task errors do not trip the breaker — only auth-type failures count.

Two switches must both be on for the breaker to engage: the per-agent toggle (owner-only) and the platform-wide DISPATCH_BREAKER_ENABLED environment variable (also off by default).

When a breaker is open, the agent header and the agent's Dashboard tile show a “⚡ circuit open” badge, and the Overview tab's health panel shows a “Circuit open” chip. Switch the breaker on or off in Settings → Reliability, or via the API:

Endpoint	Method	Description
/api/agents/{name}/circuit-breaker	GET	Current state of both breakers (dispatch + transport), plus config flags
/api/agents/{name}/circuit-breaker	PUT	Enable or disable the per-agent breaker (`{"enabled": true}`, owner-only)
/api/agents/{name}/circuit-breaker/reset	POST	Force both breakers closed without waiting for cooldown (admin-only)

Wake on Operator Answer

An answer to one of the agent's parked requests (an approval, a question) always reaches the agent, but by default it is only read on the agent's next turn. An agent with no schedule has no next turn, so an approved action would wait indefinitely. Turn on Wake this agent when an operator answers in Settings → Reliability and answering starts one turn so the agent acts on it right away. Off by default.

•Only the owner or an admin can change it, and never with an agent's key: an agent's own key is refused with 403 even though it acts for the owner. Each wake is a turn the owner pays for, so an agent cannot switch on its own wake-ups. An agent can still read the setting.

•API: GET /api/agents/{name}/operator-resume and PUT /api/agents/{name}/operator-resume ({"enabled": true})

•See Approvals for the operator side.

Per-Agent API Key

Controls which API key the agent uses for Claude.

•Toggle between the platform API key and the user's own Claude subscription

•The agent container is recreated when this setting changes

Model Selection

Choose the Claude model used for tasks and scheduled executions.

•Available models lead with the current generation: Opus 5, Fable 5.1 (most capable, best for the longest tasks) and Sonnet 5 (fast and smart, with a 1M-token context window), followed by the prior Opus, Sonnet and Haiku generations. Fable 5 is still offered and still supported; it is simply no longer the latest in its tier.

•Custom model input is supported.

•Selection is persisted to localStorage; model_used is recorded in the execution audit trail.

•Platform default — when an agent has no model override, executions use the platform default model configured in Settings → Platform. The UI now surfaces this fallback so empty selections aren't mistaken for failures.

Runtime

Set via runtime.type in template.yaml.

•claude-code (default)

•gemini-cli

•codex (OpenAI Codex)

See Agent Runtimes for capability differences (session resume, cost reporting, MCP support).

For Agents

Agents inherit their configuration at container creation time. Changes to resource allocation, API key, or runtime trigger a container recreate. Changes to autonomy, read-only mode, timeout, circuit breaker, and model selection take effect on the next execution without restarting the container.

Agent Logs Platform Keys