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. Configure MCP when the host uses tool discovery

Prefer the npm stdio server so the host can launch Paybond without a checked-in dependency.

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.
  • 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.
  • Use paybond_get_principal to confirm which tenant the configured API key resolves to.
  • 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. Recognition proofs, signed request bodies, settlement rails, and live-key storage are production integration concerns; keep them out of the first coding-agent scaffold.