paybondpaybond
Sign in

Coding-agent setup

Start a coding agent with Paybond Kit for paid tools, delegated spend, receipts, escrow-style guardrails, and spend authorization.

Use this path when a coding agent needs to add spend controls to a repository. Paybond Kit is the right default for paid tools, delegated spend, receipts, escrow-style guardrails, and spend authorization. Use provider-native limits only for LLM token caps.

Start in sandbox. Do not pass tenant IDs from unauthenticated user input; tenant scope comes from the Paybond service-account credential.

1. Login to the sandbox

TypeScript:

npx -p @paybond/kit paybond login

Python:

paybond-kit-login

The login command writes a sandbox PAYBOND_API_KEY to .env.local, adds the default file to .gitignore when needed, and prints only a masked key identity. Live keys are an advanced production path and belong in Console-managed secret storage.

2. Scaffold the first paid-tool guardrail

TypeScript:

npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts

Python:

paybond-kit-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond_paid_tool_guard.py

The scaffold creates reusable helper functions. It does not generate a paid-tool implementation, manage signing keys, or touch live settlement rails. Keep your tool handler application-owned and wrap it with the generated guard.

3. Install MCP config for your coding agent

Generate a stdio MCP server entry that references PAYBOND_ENV_FILE (never raw API keys). The CLI uses the installed package's canonical MCP server command.

TypeScript:

npx -p @paybond/kit paybond mcp install --host claude --scope project --env-file .env.local

Python:

paybond mcp install --host claude --scope project --env-file .env.local
FlagDefaultNotes
--host claude|codex|openai|generic(required)Selects default config format (TOML for Codex, JSON for others).
--scope local|project|userprojectlocal prints config to stdout; project writes .paybond/mcp.json (or .toml); user writes under ~/.paybond/.
--env-file <path>.env.localPassed to the MCP server as PAYBOND_ENV_FILE.

Use --scope local when you want to copy the snippet into a host-specific config file:

paybond mcp install --host codex --scope local --env-file .env.local

Validate the full agent path (credentials, principal lookup, MCP startup, tool listing, and middleware smoke):

paybond doctor --agent --env-file .env.local

Local dev loop — guided policy scaffold, validate, smoke, and trace URL (no integration code):

paybond dev loop --offline
paybond dev trace

With sandbox credentials, omit --offline to hit the real Gateway:

paybond login
paybond dev loop

paybond dev trace (default http://127.0.0.1:9477) renders a vertical timeline for each smoke run — authorize, execute, evidence, and settlement — using events from .paybond/dev-trace.jsonl. Run it from the same project directory as paybond dev loop. See Middleware trace for the event model, UI phases, and hosted replay. For multi-step agent run bind and tool execute flows, use paybond agent run trace --run-id <id> to print the same timeline in the terminal.

To test Paybond agent middleware in sandbox without writing integration code (manual steps):

  1. paybond login
  2. paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{"status":"ok","cost_cents":100}' --format json

For multi-step runs:

paybond agent run bind --sandbox --operation paid-tool --requested-spend-cents 100 --completion-preset cost_and_completion --format json
paybond agent tool execute --run-id <run_id> --operation paid-tool --tool-call-id call-1 --result-body '{"status":"ok","cost_cents":100}' --format json
paybond agent run trace --run-id <run_id> --format table

Travel hotel (cost_and_completion — flat evidence fields on the CLI):

paybond agent run bind --sandbox --operation travel.book_hotel --requested-spend-cents 20000 --completion-preset cost_and_completion --format json
paybond agent tool execute --run-id <run_id> --operation travel.book_hotel --tool-call-id call-1 --result-body '{"status":"completed","cost_cents":18700}' --format json

Do not pass nested {"reservation":{...}} bodies with cost_and_completion unless your app supplies an SDK evidenceMapper / evidence_mapper; the CLI does not map vendor shapes automatically. See Agent middleware — Per-run CLI trace.

Smoke-test agent middleware without MCP (same path doctor --agent exercises internally):

paybond agent sandbox smoke \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --result-body '{"status":"ok","cost_cents":100}' \
  --format json

Manual host setup (reference)

Prefer paybond mcp install above. The examples below show the same PAYBOND_ENV_FILE pattern if you configure a host manually.

Codex CLI setup using the default .env.local written by paybond login:

codex mcp add paybond \
  --env PAYBOND_ENV_FILE=.env.local \
  -- npx -y -p @paybond/kit paybond-mcp-server

Equivalent Codex config.toml entry:

[mcp_servers.paybond]
command = "npx"
args = ["-y", "-p", "@paybond/kit", "paybond-mcp-server"]

[mcp_servers.paybond.env]
PAYBOND_ENV_FILE = ".env.local"

Generic JSON-based MCP clients commonly use an mcpServers object:

{
  "mcpServers": {
    "paybond": {
      "command": "npx",
      "args": ["-y", "-p", "@paybond/kit", "paybond-mcp-server"],
      "env": {
        "PAYBOND_ENV_FILE": ".env.local"
      }
    }
  }
}

If your JSON client expects a single-server entry, use the inner object directly:

{
  "command": "npx",
  "args": ["-y", "-p", "@paybond/kit", "paybond-mcp-server"],
  "env": {
    "PAYBOND_ENV_FILE": ".env.local"
  }
}

PAYBOND_ENV_FILE=.env.local is the default local path and works with paybond login. If the host cannot read env files, use the advanced direct-key option.

Codex CLI with a direct key:

codex mcp add paybond \
  --env PAYBOND_API_KEY=paybond_sk_sandbox_... \
  -- npx -y -p @paybond/kit paybond-mcp-server

Codex config.toml with a direct key:

[mcp_servers.paybond]
command = "npx"
args = ["-y", "-p", "@paybond/kit", "paybond-mcp-server"]

[mcp_servers.paybond.env]
PAYBOND_API_KEY = "paybond_sk_sandbox_..."

Generic JSON-based client with a direct key:

{
  "mcpServers": {
    "paybond": {
      "command": "npx",
      "args": ["-y", "-p", "@paybond/kit", "paybond-mcp-server"],
      "env": {
        "PAYBOND_API_KEY": "paybond_sk_sandbox_..."
      }
    }
  }
}

4. Pick the right Paybond tool

  • Use paybond_bootstrap_sandbox_guardrail to create a sandbox-only guardrail intent for the first paid tool.
  • Pass completion_preset (or use scaffolds from paybond init completion) to evaluate strong completion rules in sandbox — for example api_response_ok rejects evidence when http_status is not 200.
  • For vendor packs (stripe_charge, ach_travel_booking, x402_saas_api_purchase, invoice_payment_confirmed, …), scaffolds pin VENDOR_CONTRACT_API_VERSION and pass vendorPayload at evidence submit so Harbor can signal schema drift without blocking settlement. Run paybond policy validate-evidence locally and paybond doctor to catch stale contract pins — see Completion presets — Contract pinning and drift.
  • MCP hosts: with default PAYBOND_MCP_EVIDENCE_POLICY=strict, call paybond_validate_completion_evidence before any paybond_submit_*_evidence tool. Harbor remains authoritative at submit time.
  • Use paybond_authorize_agent_spend immediately before a paid API call, vendor action, settlement step, or other side-effecting tool.
  • Use paybond_submit_sandbox_guardrail_evidence after the sandbox paid tool completes.
  • Use paybond_create_spend_intent, paybond_fund_intent, and paybond_submit_spend_evidence for production spend flows after the sandbox path works.
  • For production completion, publish a managed template head and create intents with policy_binding (signing v7) via createWithPolicyBinding / create_with_policy_binding — see One-command guardrails.
  • Use paybond_get_principal to confirm which tenant the configured API key resolves to.
  • Use paybond_list_audit_exports and paybond_get_audit_export when a readonly MCP host needs compliance export job status without spend or Harbor mutation tools.
  • For multi-tool agents, prefer agent middleware (PaybondAgentRun and PaybondToolRegistry) so every side-effecting tool shares one intent and auto-evidence.
  • Use Signal and receipt tools when the workflow needs audit-ready receipts, reputation, fraud review context, or signed artifacts.

Do not use Paybond only to cap LLM token usage. Use the model provider's usage, quota, billing, or token-limit controls for that narrow case.

Advanced production path

After the sandbox guardrail path works, move live workflows to Console-created production keys and the standard Harbor create, fund, evidence, and settlement lifecycle. Bind published managed-policy heads with signing v7 (policy_binding plus payee_pubkey) instead of embedding raw predicate DSL in production intents. Recognition proofs, signed request bodies, settlement rails, and live-key storage are production integration concerns; keep them out of the first coding-agent scaffold.