# Coding-agent setup

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:

```bash
npx -p @paybond/kit paybond login
```

Python:

```bash
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:

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

Python:

```bash
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:

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

Python:

```bash
paybond mcp install --host claude --scope project --env-file .env.local
```

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

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

```bash
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):

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

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

```bash
paybond dev loop --offline
paybond dev trace
```

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

```bash
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](./middleware-trace.md) 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:

```bash
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):

```bash
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](./agent-middleware.md#trace-events-and-observability).

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

```bash
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`:

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

Equivalent Codex `config.toml` entry:

```toml
[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:

```json
{
  "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:

```json
{
  "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:

```bash
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:

```toml
[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:

```json
{
  "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](./completion-presets.md#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](./one-command-guardrails.md#production-boundary).
- 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](./agent-middleware.md) (`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.

## Related

- [Agent middleware](./agent-middleware.md) — run binding, registry, and auto-evidence for multi-tool agents
- [One-command guardrails](./one-command-guardrails.md)
- [MCP server](./mcp-server.md)
- [Agent integrations](./agent-integrations.md)
- [Authentication & tenant binding](./authentication.md)