Fine-grained capabilities

Every route has one endpoint id, and one rule per endpoint decides whether it can be called and which path, command, size, and rate limits apply. There is no second gate in front of the rules. agents-cli exposes only the session routes and leaves POST /shell and POST /v1/agents closed. That is this layer.

The design note is Fine-grained capabilities. Path and command enforcement is in File and command controls. Agents request and response shapes are in Agents API. The full route table is in the Agents API reference.

One switch: the endpoint

An endpoint id (upload, files_list, agents_sessions_create) is the unit everything uses: the policy, the audit log, GET /capabilities, and the client. A group is only a name for a set of endpoint ids. Writing groups: [file_ops], group:file_ops, table.enable_group(CapabilityGroup.FILE_OPS), or ABX_SERVER_ENABLED_GROUPS=file_ops expands to the ids declared in that group, and the result is the same per-endpoint rule set.

Defaults: core is always on. agents, dev_tools, and browser are opt-in and start off. file_ops, process, terminal, system, and commands start on. health, capabilities, and capabilities_check cannot be turned off.

Rules come from five layers and are merged per endpoint:

The more specific selector wins: an exact id beats a glob, a glob beats group:<name>. At equal specificity the later layer wins, and inside one layer a single enabled: false turns the endpoint off. So endpoints.code_run.enabled: false in the policy stays off even when the environment enables dev_tools.

A denial names the rule that denied it. The 404 body carries code: endpoint_disabled and rule, for example policy:endpoints.shell, policy:groups.process, preset:read-only, code:enable_group:file_ops, or default:opt-in:browser. GET /capabilities reports the same rule per endpoint. Its groups and group_summary fields are derived from the endpoint state ({"file_ops": {"enabled": 11, "total": 12}}), never stored.

ABX_SERVER_ENABLED_GROUPS is the only group environment variable. A comma list of group names, such as agents,dev_tools. An unknown name stops the process with a did-you-mean message. There is no variable to disable groups. Write groups: {process: false} or endpoints rules.

How to turn it on

Three inputs, one document. An invalid document stops the process. It does not fall open.

The server: block in template.yaml. Tooling compiles it to /etc/agent-sandbox/server-policy.json. Accepted keys: version, preset, base_dir, groups, defaults, auth, endpoints, description. groups is either a list of groups to turn on or a map of group to true/false.

server:
  endpoints:
    "*":
      enabled: false
    agents_sessions_create:
      enabled: true
    agents_sessions_events_create:
      enabled: true
    agents_sessions_items_list:
      enabled: true
    agents_runtimes_list:
      enabled: true

Group shorthand, list or map:

server:
  groups: [agents, dev_tools]     # same as {agents: true, dev_tools: true}

server:
  groups:
    process: false
    terminal: false

Inline JSON:

export ABX_SERVER_POLICY='{"groups":["agents"],"endpoints":{"*":{"enabled":false},"agents_sessions_create":{"enabled":true}}}'

Or a file:

export ABX_SERVER_POLICY_FILE=/etc/agent-sandbox/server-policy.json
agent-sandbox-server check-config --policy /etc/agent-sandbox/server-policy.json

Lookup order: ABX_SERVER_POLICY, then ABX_SERVER_POLICY_FILE, then the well-known policy file. With none of them the built-in defaults apply: opt-in groups off, everything else on, no per-endpoint limits.

Python:

from agent_sandbox.server import SandboxServer, ServerPolicy

policy = ServerPolicy.only(
    "agents_sessions_create",
    "agents_sessions_events_create",
    "agents_sessions_items_list",
    "agents_runtimes_list",
)
SandboxServer(policy=policy).serve(port=9000)

ServerPolicy.only turns "*" off, turns the listed ids on, and leaves the core endpoints on. agents-cli's commands.py is this call. only also accepts "transfer" (the four upload and download ids) and "group:<name>".

To open a whole group from commands.py without a policy document:

from agent_sandbox.server import CapabilityGroup, default_table

default_table().enable_group(CapabilityGroup.DEV_TOOLS)

enable_group and disable_group are the only code-level switches. disable_group(CORE) raises.

Selectors

If several matching rules of the same specificity and layer disagree, enabled: false wins. A more specific selector can turn the endpoint back on.

What a rule may contain

Limits every endpoint accepts: max_request_bytes, rate_per_minute, max_concurrency.

Agents endpoints are in the built-in catalogue. The default scope is agents:use. Enable one endpoint id with enabled: true, the same way as upload. They have no paths and no specialised params, so the only other keys are enabled, scopes, audit, and the three limits above. A paths or specialised params block on them fails policy load.

Presets apply before your endpoint rules:

Group names: core, commands, file_ops, process, terminal, system, dev_tools, browser, agents. core cannot be disabled.

The checker warns (L1) when one identity can both read scoped files and run shell, process_start, code_run, or a PTY. A process can bypass path rules. An Agents session starts the CLI inside the server. It does not need the process group for that.

Endpoint catalogue

This is the endpoint declaration table (agent_sandbox.server.endpoints.ENDPOINTS). The route table, the policy, and GET /capabilities are all derived from it. pty_connect is the WebSocket upgrade, served on the PTY port. Agents rows use the scope agents:use. They have fewer knobs than file routes that take a path, because these routes do not accept paths or specialised parameters.

How this meets the Agents API case

agents-cli enables only:

The local e2e recorded POST /shell as 404, POST /v1/agents (definitions) as 404, and the Codex and Qwen Code session, event, and item calls as 200 / 202. To open another route, add its endpoint id to ServerPolicy.only and to endpoints in template.yaml.