Capabilities

Capabilities define allowed API calls in UDS mode. Each capability specifies an endpoint pattern, rate limits, approval requirements, and optional secret injection.

Schema

capabilities:
  - name: string             # required, unique identifier
    description: string      # optional
    api:
      method: GET|POST|PUT|DELETE|PATCH
      url_pattern: string    # glob pattern, e.g. "https://api.example.com/**"
      url_deny_list: [string]
      headers_allowed: [string]
    rate_limit:
      requests_per_minute: integer
      burst: integer         # optional, default 1
    requires_approval:
      threshold: always|never
      timeout_seconds: integer
      default_on_timeout: deny|approve
    taint_labels: [string]
    secret_headers:
      Header-Name: "template with ${VAR}"

Fields

name

Required. Unique identifier for the capability. Used in audit logs and taint rules.

api

Defines the allowed HTTP request pattern.

Field	Description
`method`	HTTP method
`url_pattern`	Glob pattern for allowed URLs. `**` matches any path segment.
`url_deny_list`	URLs that are explicitly blocked even if they match the pattern
`headers_allowed`	Headers the agent may set. Others are stripped.

rate_limit

Token bucket rate limiter.

Field	Description
`requests_per_minute`	Sustained rate
`burst`	Maximum burst above sustained rate

requires_approval

Human-in-the-loop approval gate.

Field	Description
`threshold`	`always` requires approval; `never` skips
`timeout_seconds`	How long to wait for decision
`default_on_timeout`	Action if no decision: `deny` or `approve`

taint_labels

Labels applied to response data. Used by taint rules to restrict data flow.

secret_headers

Headers with secret values. ${VAR} is replaced with the secret value at runtime.

Example

capabilities:
  - name: stripe-charge
    description: Create Stripe charges
    api:
      method: POST
      url_pattern: "https://api.stripe.com/v1/charges"
    rate_limit:
      requests_per_minute: 10
      burst: 2
    requires_approval:
      threshold: always
      timeout_seconds: 300
      default_on_timeout: deny
    taint_labels: [payment_data]
    secret_headers:
      Authorization: "Bearer ${STRIPE_SECRET_KEY}"

Hull0