Capabilities

Capabilities control what API endpoints an agent can access from within its sandbox. By default, sandboxed agents cannot call the VM0 API. Adding capabilities grants specific permissions following the principle of least privilege.

Capabilities are currently an experimental feature. The field name and available capabilities may change in future versions.

How Capabilities Work

Define in vm0.yaml - List the capabilities your agent needs under experimental_capabilities
Embedded in JWT - When a run starts, capabilities are embedded in the sandbox token
Enforced per request - Each API call from the sandbox is checked against the token's capabilities

If a request lacks the required capability, the API returns a 403 Forbidden response:

{
  "error": {
    "message": "Missing required capability: artifact:read",
    "code": "FORBIDDEN"
  }
}

Available Capabilities

Capability	Category	Description
`agent:read`	Agent resources	Read agent composes and volumes
`agent:write`	Agent resources	Create, update, and delete agent composes and volumes
`artifact:read`	Runtime resources	Read artifacts and memories
`artifact:write`	Runtime resources	Write artifacts and memories
`agent-run:read`	Operational	List and view agent runs
`agent-run:write`	Operational	Create and cancel agent runs
`schedule:read`	Operational	List and view schedules
`schedule:write`	Operational	Create, update, enable, and disable schedules

All capabilities follow the {resource}:{action} format where action is either read or write.

Artifacts and memories are both runtime dynamic resources, so they share the artifact:* capability. Similarly, agent composes and volumes are agent static resources sharing the agent:* capability.

Configuration

Add capabilities to your agent in vm0.yaml:

version: "1.0"

agents:
  my-agent:
    framework: claude-code
    instructions: AGENTS.md
    experimental_capabilities:
      - artifact:read
      - artifact:write
    environment:
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Only the first agent's capabilities are used. This follows the current single-agent limitation of vm0.yaml.

Example Configurations

Read-only access to artifacts

An agent that reads artifacts but cannot modify them:

experimental_capabilities:
  - artifact:read

Orchestrating sub-agents

An agent that triggers and monitors other agent runs:

experimental_capabilities:
  - agent:read
  - agent-run:read
  - agent-run:write

Full access

An agent that needs complete API access:

experimental_capabilities:
  - agent:read
  - agent:write
  - artifact:read
  - artifact:write
  - agent-run:read
  - agent-run:write
  - schedule:read
  - schedule:write