Runtime limits configuration¶

Colossus uses several independent limits rather than one global runtime budget. The agent and subagents blocks configure model-loop and child-scheduler bounds. Model, context, memory, research, sandbox, MCP, and storage limits live with their owning configuration blocks.

The distinction matters:

Limits are not permission grants. A run still needs tool visibility, policy authorization, sandbox grants, credentials, and approvals. A policy decision or adapter-specific declaration may narrow a configured ceiling but cannot use the ceiling to authorize an otherwise denied effect.

Choose a starting point¶

The generated configuration omits the agent and child-scheduler blocks so defaults can evolve without pinning old generated values. Omitting either block currently selects agent.maxTurns: 100 and subagents.maxConcurrent: 10.

config show states both limits even when the file omits them, so the resolved turn and concurrency bounds stay inspectable.

Add the blocks only to override those defaults. For example, a small automation worker might use:

agent:
  maxTurns: 12
subagents:
  maxConcurrent: 2

These values are operational choices, not universal recommendations. Model latency, provider quotas, workload shape, approval flow, and host resources should determine the final settings.

Agent turns¶

agent.maxTurns¶

A turn is one trip through the model loop. A model may return a final response before the limit. When it requests tools, Colossus validates and executes authorized calls, then another model continuation consumes another turn. Argument-repair and required Plan Mode recovery can also consume turns.

maxTurns is a stopping bound, not a target. It does not directly cap:

• Tool calls that may appear in a model response.
• Generated tokens in each response.
• The wall-clock duration of a provider request or tool effect.
• Child-agent or sandbox concurrency, or the number of research collection jobs.

The CLI may explicitly override the configured default for one run:

colossus --config .colossus/config.yaml run --max-turns 8 \
  "Inspect the failure and return a bounded diagnosis"

The override must still be in 1..=100; it can be higher or lower than the configured value. Durable child-agent jobs use the configured agent.maxTurns, not the parent's one-off CLI override.

The create-run API reserves zero as a transport sentinel for the configured positive default, and Desktop uses that sentinel while its override field is blank. Zero is not an unlimited mode and is not valid for agent.maxTurns in YAML.

Increasing this value can multiply provider usage because each turn may make another generation request. Raise it when runs genuinely need more model/tool continuations, not to compensate for an unrelated timeout or context-window problem.

Child-agent concurrency¶

subagents.maxConcurrent¶

Queued child jobs remain durable. When Colossus drains the queue, it starts at most maxConcurrent jobs in a batch and waits for them to reach a terminal state before starting more. Interrupted child work is not replayed automatically.

Each child is a complete bounded agent run: it selects the configured child model role, uses agent.maxTurns, and remains subject to ordinary tools, policy, sandbox, context, and audit controls. Recursive child delegation is denied.

This field is independent from:

A runtime with four concurrent children can still let each child issue effects up to its own permitted sandbox concurrency. Tune the combined envelope, not each number in isolation.

Use the queue status to observe the configured maximum, active jobs, and available slots:

colossus --config .colossus/config.yaml agents status

See Goals and subagents for queue, drain, cancellation, and recovery workflows.

Model and context budgets¶

Model limits are declared per profile. They describe the selected model; Colossus does not discover or guess them from the provider:

Colossus reserves output and a safety margin before calculating model-visible input:

safety margin = max(ceil(context window / 10), 512)
input budget  = context window - max output - safety margin

For a 128,000-token context window with 16,000 output tokens, the safety margin is 12,800 and the effective input budget is 99,200 tokens. A request may lower the output limit, but it cannot raise it above the configured model maximum.

Context compaction percentages apply to that derived input budget, not to the provider's advertised context window:

context:
  autoCompaction: true
  compactAtPercent: 70
  targetPercent: 45
  preserveRecentMessages: 8
  modelAssisted: true

With the 99,200-token input budget above, automatic compaction begins around 69,440 estimated tokens and aims for about 44,640. Colossus uses conservative byte-based token estimation, so these are planning thresholds rather than provider billing measurements.

Increasing maxOutputTokens reduces the available input budget. Increasing compactAtPercent delays compaction but does not enlarge the model window. A large preserveRecentMessages value can also make compaction less effective because those messages are never summarized automatically.

Context preparation also keeps a conservative byte estimate below a fixed budget that leaves room inside the 1 MiB pre-effect policy and provider request ceilings. The estimate includes both the serialized logical model request and additional escaping introduced when provider adapters project structured tool-call arguments. This byte budget can trigger compaction before the configured token percentage on very large-context models. If the preserved recent messages, tool schemas, retrieved material, or instructions alone exceed it, Colossus returns a context configuration error before attempting the provider effect.

See Provider and model configuration for complete profiles and Context, memory, and research configuration for compaction behavior.

Memory and research bounds¶

These limits bound how much supporting material one operation may collect or compose:

memory:
  indexEnabled: true
  indexPath: null
  retrievalLimit: 6
  semantic:
    kind: disabled
research:
  maxSources: 20
  maxWorkers: 4

maxSources does not guarantee that many usable sources will be found. maxWorkers caps total query/lane collection work, not the child-agent scheduler, and can increase search traffic and pressure on external services.

Sandbox resource ceilings¶

Sandbox limits bound individual effects and, under an isolating backend, their process trees. On Unix direct backends, timeout and output bind the supervised request and attached group, while process-count, memory, and cleanup are best-effort for deliberately detached descendants. These are the default values; see Sandbox configuration for complete backend examples.

Backend-specific minimum timeouts are:

A policy permit, MCP declaration, pack declaration, or individual request may impose a smaller timeout or output cap. It cannot widen the sandbox ceiling. For example, an MCP server's maxOutputBytes must be at least 1,024 bytes and no greater than sandbox.maxOutputBytes.

Output limits use bytes, while model limits use tokens. For a streaming provider turn, the byte ceiling counts the complete raw SSE body, including event and JSON framing, reasoning events, tool-call arguments, usage metadata, and visible text. Increasing a model's maxOutputTokens does not widen that byte ceiling.

Process memory is not preallocated at startup. Native supervision measures the observed process-tree resident memory, OCI passes the effective ceiling as the container memory cap, and Windows applies process and job memory limits. V8 heaps, native runtime memory, loaded modules, buffers, and child processes all contribute. Raising maxConcurrency can multiply the effective process count, memory demand, network traffic, and output volume, so size it together with host and worker capacity.

Timeouts are local to an operation¶

There is no single configuration field that sets a deadline for an entire agent run. Common timeout fields apply at different boundaries:

agent.maxTurns counts model rounds and is not a timeout. A run can contain provider requests, approvals, tool effects, and context work with separate time bounds. If one operation is timing out, adjust that operation only after confirming the service and cleanup behavior are healthy.

See MCP server configuration, Search configuration, and Storage configuration for adapter-specific limits.

Consolidated numeric reference¶

Adapter protocols also impose non-configurable size, pagination, recursion, and retry bounds. Raising a value in this table does not remove those hard limits.

Common configuration mistakes¶

Validate the result¶

Parse the complete configuration and print its resolved defaults without resolving credential values:

colossus --config .colossus/config.yaml config show

Then exercise only the affected boundary:

colossus --config .colossus/config.yaml models profiles
colossus --config .colossus/config.yaml models doctor MODEL_PROFILE
colossus --config .colossus/config.yaml agents status
colossus --config .colossus/config.yaml sandbox doctor
colossus --config .colossus/config.yaml state doctor

config show proves that relationships and numeric ranges are accepted. Doctor and status commands test the provider, scheduler, sandbox, or storage boundary that will actually enforce the value. A syntactically valid high limit does not prove that the provider quota, database, or host can sustain it.

For fixed protocol and UI caps that are not part of YAML, see Output, environment, and limits.

Return to the configuration overview.