Access configuration¶

access answers two questions before an agent can use a capability:

1. Should the tool appear in the model-visible catalog?
2. Should the tool's exact action be allowed, denied, or require approval under the built-in policy?

It does not answer whether the runtime has permission to touch a file, start a process, reach an origin, use a credential, or load an extension. Those authorities come from the sandbox, provider or integration configuration, extension trust, policy obligations, approvals, and one-use permits.

For the complete decision flow, see Access and approvals. For canonical tool and action names, see Tools and action classes.

How access resolution works¶

Colossus resolves the effective tool surface in this order:

Each stage can narrow authority. A later stage cannot use a broad access profile to repair a missing resource grant or bypass an earlier trust decision.

Choose a starting profile¶

allow_all is the default profile, and the root access block may be omitted. Child fields may also be omitted independently; the complete explicit shape is:

access:
  profile: allow_all
  tools:
    include: []
    exclude: []
  actions:
    allow: []
    requireApproval: []
    deny: []

Unknown fields are rejected.

Access profiles¶

Profiles are metadata-driven baselines. Tool includes and action overrides are applied after the baseline.

“Applicable” means the tool's prerequisites are currently satisfied. A profile does not create those prerequisites.

minimal¶

Use minimal for an offline health check or an interface that should not offer normal effectful tools. Exact includes can still make an effectful tool visible, but the profile continues to deny its action until an action override explicitly changes the decision.

access:
  profile: minimal
  tools:
    include: []
    exclude: []
  actions:
    allow: []
    requireApproval: []
    deny: []

development¶

Use development for interactive engineering work. Read and Colossus-owned state operations proceed under their normal obligations. Workspace mutation, command execution, external network access, and administration require approval.

Select development and sandbox.profile: workspace-development explicitly when you want the older approval-gated, workspace-isolated development posture. Access and the execution boundary remain independent.

allow_all¶

allow_all changes built-in action outcomes from approval-required to allowed. The separate schema default of acknowledged danger_full_access supplies ambient resource authority for process, structured filesystem, and canonical HTTP(S) effects. It does not invent credentials, provider/model routes, extension trust, configured MCP servers or tools, integration operations, action identities, or permits.

Treat that combined default as full host access. Select a platform-isolating sandbox when the blast radius must be smaller.

pinned¶

pinned is deny-by-default on both dimensions:

• Only named tool includes are selected.
• Only provider.echo is allowed by the profile's action baseline.

Selecting a tool does not allow its action. A practical pinned configuration therefore usually names both the tool and the corresponding action:

access:
  profile: pinned
  tools:
    include:
      - filesystem.list
      - filesystem.read
      - filesystem.search
      - git.status
      - git.diff
      - git.show
      - repo.map
      - repo.file_summary
    exclude: []
  actions:
    allow:
      - filesystem.list
      - filesystem.read
      - filesystem.search
      - git.status
      - git.diff
      - git.show
      - repo.map
      - repo.file_summary
    requireApproval: []
    deny: []

Under an isolating boundary, this exact example also requires a readable filesystem grant and exactly one configured or derived Git executable. Acknowledged full access supplies those resource prerequisites but does not change the pinned action list. A non-echo provider requires its exact provider action to be opted in as well. Inspect the resolved names instead of guessing them.

Tool selection¶

access.tools changes what the model can see. It does not directly change the action decision for any selected tool.

Exact selector rules¶

• Entries must be nonempty and unique.
• Every exact name must exist in the trusted runtime catalog.
• The same exact tool cannot appear in both lists.
• include: ["*"] is valid, but "*" must be its only include entry.
• exclude never accepts "*".
• Exact excludes may accompany include: ["*"] to express “all except these tools.”
• Excludes win over profile selection and wildcard inclusion.

For example:

access:
  profile: pinned
  tools:
    include: ["*"]
    exclude: [shell.run]
  actions:
    allow: []
    requireApproval: []
    deny: [shell.run]

This exposes every applicable trusted candidate except shell.run, but most effectful calls remain denied by the pinned action baseline. The explicit action deny also prevents the shell.run action outside that model-visible selection.

Includes and excludes are not action decisions¶

A visible tool may still be denied. A hidden tool's action may still be used by a separate operator or runtime operation if that path is authorized. When a capability must be unavailable at both boundaries, hide its tool and deny its exact action:

access:
  profile: development
  tools:
    include: []
    exclude: [shell.run]
  actions:
    allow: []
    requireApproval: []
    deny: [shell.run]

Prerequisite behavior¶

Prerequisites are availability checks derived from other configuration. They never grant the underlying resource.

Provider service and authentication transports are independent from the model-network tool prerequisite. Managed Local Offline isolated retains the configured provider's exact service and authentication/refresh destinations while keeping web.fetch, docs.fetch, and network.http hidden. Search, MCP, and integration adapters remain independently governed by their own routes, declarations, trust, and host grants.

When a profile or wildcard selects a tool with an unmet prerequisite, Colossus keeps it hidden and reports the reason in config effective. A named exact include is a stronger operator assertion: an unmet non-interactive prerequisite fails runtime composition instead of silently ignoring the selection. user.ask may remain hidden when an otherwise valid process has no interactive interface.

An unknown exact name also fails closed. Configure and trust an integration or pack before referring to one of its dynamic tool names.

Wildcard boundary¶

access.tools.include: ["*"] automatically selects current and future trusted candidate tools registered in that runtime. This is intentionally broader than an explicit list and should be reviewed after upgrades or extension changes.

It is independent from similarly spelled wildcards:

Enabling one does not enable either of the others.

Action overrides¶

access.actions changes the built-in authorization result for exact trusted action names. It applies independently from tool visibility.

All entries must be nonempty, unique, exact registered action names. The three lists must be pairwise disjoint. Action wildcards are unsupported; select allow_all when that broad built-in baseline is truly intended.

An action not named in an override list receives its profile decision. Overrides can therefore tighten or loosen a profile one action at a time:

access:
  profile: development
  tools:
    include: []
    exclude: []
  actions:
    allow: []
    requireApproval:
      - context.compact
      - context.restore
    deny:
      - shell.run

Here, context snapshot changes require approval even though development normally allows local-state actions, while shell execution is denied rather than merely approval-gated.

Tool names and action names can differ¶

Most effectful built-ins use the same tool and action name. Important exceptions are:

Connected integrations and signed packs add action identities from their active trusted declarations. Use tools list and config effective for the exact runtime catalog.

Action classes and profile defaults¶

Every trusted action has one stable behavior class:

The class provides a profile default; exact overrides still win under built-in policy. See the canonical action table in Tools and action classes.

Approval interaction¶

requireApproval creates an approval obligation. The global --approval-mode controls how an existing obligation can be satisfied:

Approval mode never converts deny to allow and never creates a missing resource grant. full-access is therefore not equivalent to access.profile: allow_all, and neither setting bypasses the Safety Kernel or sandbox.

Access with OPA¶

When policy.kind: opa, OPA owns every action outcome. All local action override lists must be empty:

access:
  profile: pinned
  tools:
    include:
      - filesystem.list
      - filesystem.read
      - git.status
      - git.diff
    exclude: []
  actions:
    allow: []
    requireApproval: []
    deny: []

The profile and tool selectors still determine model visibility. The profile's built-in action baseline is replaced with external_policy decisions, and OPA must return the complete authorized resource obligations. Local Safety Kernel, permit, sandbox, quarantine, audit, and post-effect checks remain mandatory.

See Policy and audit configuration and Policy and OPA.

Access does not configure resources¶

Review Sandbox configuration, Network configuration, and Extension configuration alongside access for effectful deployments.

Common configuration mistakes¶

Validate the result¶

First parse the strict configuration:

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

Then inspect both the complete access resolution and the active model-visible catalog:

colossus --config .colossus/config.yaml config effective
colossus --config .colossus/config.yaml tools list

config effective includes active and hidden tools, selection reasons, unmet prerequisites, exact action classes and decisions, explicit and derived sandbox grants, the canonical workspace, and wildcard meaning. tools list includes active schemas, effect actions, capabilities, decisions, and output bounds.

For effectful changes, also verify the independent enforcement boundaries:

colossus --config .colossus/config.yaml policy doctor
colossus --config .colossus/config.yaml sandbox doctor

Run those commands in the same workspace and host mode used by the real agent because derived development grants, interactive availability, configured executables, and extension state affect the resolved catalog.

Return to the configuration overview.