Capability Tokens

Capability tokens are the primary access-control mechanism in Scarab-Runtime. An agent can only invoke tools, read/write memory, or access secrets that are listed in its manifest capabilities.

Token Format

<domain>.<action>
<domain>.<action>:<scope>

Examples:

fs.read
fs.write:/home/agent/workspace/**
tool.invoke:echo
tool.invoke:*
net.connect:api.example.com:443
secret.use:my-api-key
secret.use:db-*
memory.read:config
memory.write:*
obs.append
obs.query
sandbox.exec

Glob Matching on Scopes

The :<scope> portion supports glob matching:

Pattern	Matches
`fs.read`	Read any file (no scope restriction)
`fs.write:/home/agent/**`	Write files anywhere under `/home/agent/`
`tool.invoke:echo`	Invoke only the `echo` tool
`tool.invoke:fs.*`	Invoke any tool in the `fs` namespace
`tool.invoke:*`	Invoke any tool
`secret.use:openai-*`	Use any secret whose name starts with `openai-`
`net.connect:*.example.com:443`	Connect to any subdomain of example.com on port 443

Glob rules:

* matches any single path segment (no /)
** matches zero or more path segments (including /)

Capability Domains

`tool.invoke`

tool.invoke:<tool-name>

Grants permission to invoke a named tool. Without this, the tool registry will reject the call.

`fs`

fs.read:<path-glob>
fs.write:<path-glob>

Used by filesystem tools to validate the requested path against the agent's allowed scopes. If an agent has tool.invoke:fs.read but not fs.read:/etc/**, it cannot read /etc/passwd.

Note: tool.invoke:fs.read and fs.read are complementary; the tool dispatch layer checks tool.invoke:fs.read, while the fs.read tool handler additionally checks fs.read:<path>.

`memory`

memory.read:<key-pattern>
memory.write:<key-pattern>

Scoped to key patterns. memory.read:* allows reading any key. memory.read:config allows only the config key.

`secret.use`

secret.use:<secret-name-glob>

Declares which secrets the agent may reference in tool arguments using the {{secret:<name>}} handle syntax.

`obs`

obs.append
obs.query

obs.append: write to this agent's observation log. obs.query: read observation logs (own or other agents').

`sandbox.exec`

sandbox.exec

Allows use of the sandbox.exec tool to execute code in a throwaway namespace sandbox.

`net.connect`

net.connect:<host>:<port>

Low-level network connection permission (enforced by nftables). Higher-level network policy (spec.network) is the simpler interface for most use cases.

`agent.discover`

agent.discover

Allows querying the agent discovery service to find other agents by capability pattern.

Capability Enforcement

Every IPC request to agentd that involves a tool invocation goes through this check:

Is the tool in the registry? (ToolError::NotFound)
Does the agent have the required capability for this tool? (ToolError::AccessDenied)
Does the tool require human approval? If so, queue it and return RequiresApproval.
Call the tool handler. The handler may perform additional scope checks (e.g., fs.write validates the path against fs.write:* capabilities).

Capability Sets in the Manifest

The spec.capabilities list is parsed into a CapabilitySet at spawn time. The set is stored in the agent's state and injected into every ToolContext when a tool is dispatched.

spec:
  capabilities:
    - tool.invoke:lm.complete
    - tool.invoke:web.fetch
    - tool.invoke:fs.read
    - fs.read:/home/agent/**
    - memory.read:*
    - memory.write:notes
    - obs.append
    - secret.use:openai-key

Scarab-Runtime Documentation