paybondpaybond
Sign in

Agent policy-as-code

Versioned paybond.policy.yaml for GitOps-friendly spend authorization, CI validation, and enterprise org inheritance.

paybond.policy.yaml is the configuration layer for agent middleware. One reviewed file defines side-effecting tools, spend rules, evidence presets, and intent alignment — then drives registry construction, sandbox bootstrap, production intent create, and CI validation.

When to use policy vs registry-only

ApproachBest for
paybond.policy.yamlMulti-tool agents, production intent binding, GitOps review, CI validation before deploy
Registry YAML only (paybond.agent.registry.yaml)Sandbox-only smoke tests, minimal tool lists without intent metadata
Inline registry in codeQuick prototypes and single-file examples

Prefer policy files when default_deny: true must catch tool/intent misalignment in CI before production.

Public reference: /docs/kit/agent-policy. Middleware overview: /guides/agent-middleware.

Bundled presets and owned policy files

Vertical presets (travel, shopping, saas, aws, read-only, strict) work inline in middleware (policy: "travel") or as editable local YAML.

Presets are starting points

Bundled presets are reference implementations — composed defaults you can fork. Run paybond init for the full wizard (policy + config + instrument stub), or scaffold policy only with paybond policy init --preset travel. Commit paybond.policy.yaml and edit freely. They are not immutable contracts for your production agents.

Browse and preview before scaffolding:

Terminal
Terminal commandSwipe to inspect long lines
paybond policy presets list
paybond policy presets show travel

GitOps workflow

Validate before bind

Run paybond policy validate-tools --file paybond.policy.yaml --local-only in CI without credentials. Add --remote after paybond login to catch Harbor template head drift before deploy.

Recommended pipeline:

  1. Commit paybond.policy.yaml alongside agent code.
  2. Run local validation in CI (--local-only).
  3. When sandbox credentials are available, add --remote for server-authoritative checks.
  4. Bind runs with --policy-file so authorization cannot drift from the reviewed file.
Terminal
Terminal commandSwipe to inspect long lines
# Full project scaffold (recommended after paybond login)
paybond init
paybond init --solution travel --max-spend-usd 500 --framework langgraph --non-interactive

# Policy file only
paybond policy init --preset travel --out paybond.policy.yaml

# Optional: raise spend cap when scaffolding
paybond policy init --preset travel --max-spend 500 --out paybond.policy.yaml

# Or compose domain + guardrails explicitly
paybond policy init \
  --domain travel \
  --guardrails read-only,max-spend:500 \
  --out paybond.policy.yaml

paybond policy validate-tools --file paybond.policy.yaml --local-only --format json

paybond agent sandbox smoke \
  --policy-file paybond.policy.yaml \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

Production attach is documented under Going to production — not required for sandbox smoke.

Server-authoritative validation

Remote validation calls Gateway POST /v1/policy/validate. Tenant scope is derived from your bearer credential — cross-tenant template rows are never returned.

Terminal
Terminal commandSwipe to inspect long lines
paybond login
paybond policy validate-tools --file paybond.policy.yaml --remote --format json

Full report shape and Kit API: /docs/kit/agent-policy-validate.

Enterprise org inheritance

Platform operators can publish org base policies that tenant overlays extend. Each business unit keeps a local overlay while inheriting shared tool definitions, evidence presets, and spend caps.

Terminal
Terminal commandSwipe to inspect long lines
paybond policy init-org --out org-base.policy.yaml
paybond policy extend --base org-base.policy.yaml --out paybond.policy.yaml

paybond policy validate-tools \
  --file paybond.policy.yaml \
  --remote \
  --resolve-inheritance \
  --format json

Tenant isolation remains absolute: overlays never merge policies from another org, and tenants cannot widen org allowed_tools or raise org spend caps.

Guide: /docs/kit/enterprise-policy-inheritance.

Long-lived agent processes

Policy loads at PaybondAgentRun.bind() by default. Daemon workers, persistent LangGraph graphs, and MCP servers can reload policy at runtime without re-bootstrapping intents.

See Policy hot-reload for file watch, Gateway poll, and in-flight semantics.