paybondpaybond
Sign in

Production attach

Bind agent middleware to an existing funded production intent with signing credentials for auto-evidence and recognition proofs.

Sandbox paths (paybond.agent(), paybond.instrument({ sandbox: true }), and paybond agent sandbox smoke) never require payee identities or signing seeds. Production attach is the step after you have a funded production intent and need middleware to sign payee evidence and tenant-registered agent recognition proofs on every auto-evidence submit.

Start in sandbox first: Agent quickstart. For intent create and fund flows, see TypeScript quickstart or Python quickstart.

When you need this

PathSigning credentials
Sandbox smoke / paybond.agent()Not required — Gateway issues sandbox capabilities
Production attach (instrument().bind(), agentRun.bind({ attach }))Required — payee binding and agent recognition key

Gateway rejects empty recognition proofs on production intent mutations. Middleware signs a fresh proof over the exact evidence body digest for each successful side-effecting call.

CLI: bind an existing intent

paybond agent run bind --production \
  --attach-intent-id <intent-id> \
  --capability-token <token> \
  --payee-did did:web:vendor.example \
  --payee-signing-seed-hex <64-hex-chars> \
  --agent-recognition-key-id <registered-key-id> \
  --agent-recognition-signing-seed-hex <64-hex-chars> \
  --policy-file paybond.policy.yaml \
  --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

Env fallbacks: APP_PAYEE_DID, APP_PAYEE_SEED_HEX, APP_AGENT_RECOGNITION_KEY_ID, APP_AGENT_RECOGNITION_SEED_HEX. The CLI stores hex-encoded seeds in .paybond/runs/<run_id>.json (mode 0600) so agent tool execute can re-attach without re-passing secrets.

Staging smoke (/harbor/* and recognition)

Sandbox CI (paybond agent sandbox smoke) exercises gateway-composed sandbox guardrails only — it does not hit live /harbor/* or agent recognition proofs. Before production attach rollouts, run the dedicated staging check against a funded intent:

export PAYBOND_PRODUCTION_ATTACH_SMOKE=1
export PAYBOND_GATEWAY_URL=https://api.staging.example
export PAYBOND_API_KEY=paybond_sk_...
export PAYBOND_ATTACH_INTENT_ID=<funded-intent-id>
export PAYBOND_CAPABILITY_TOKEN=<capability-token>
export APP_PAYEE_DID=did:web:vendor.example
export APP_PAYEE_SEED_HEX=<64-hex>
export APP_AGENT_RECOGNITION_KEY_ID=<registered-key-id>
export APP_AGENT_RECOGNITION_SEED_HEX=<64-hex>

make production-attach-staging-smoke
# or directly:
paybond agent production attach smoke \
  --attach-intent-id "$PAYBOND_ATTACH_INTENT_ID" \
  --capability-token "$PAYBOND_CAPABILITY_TOKEN" \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --result-body '{"status":"ok","cost_cents":100}' \
  --format json

Repository CI runs make production-attach-parity-gate on every PR (Go /harbor/* httptest and Kit interceptor/recognition unit tests). Staging execution (env vars, success criteria, troubleshooting) is coordinated with Paybond platform operators for design-partner attach.

SDK: agentRun.bind({ attach })

TypeScript:

const run = await paybond.agentRun.bind({
  attach: {
    intentId: process.env.PAYBOND_INTENT_ID!,
    capabilityToken: process.env.PAYBOND_CAPABILITY_TOKEN!,
    productionEvidence: {
      payeeDid: process.env.APP_PAYEE_DID!,
      payeeSigningSeed: seed32FromHex(process.env.APP_PAYEE_SEED_HEX!),
      agentRecognitionKeyId: process.env.APP_AGENT_RECOGNITION_KEY_ID!,
      agentRecognitionSigningSeed: seed32FromHex(
        process.env.APP_AGENT_RECOGNITION_SEED_HEX!,
      ),
    },
  },
  registry,
});

Python:

run = await paybond.agent_run.bind(
    {
        "attach": {
            "intent_id": os.environ["PAYBOND_INTENT_ID"],
            "capability_token": os.environ["PAYBOND_CAPABILITY_TOKEN"],
            "production_evidence": {
                "payee_did": os.environ["APP_PAYEE_DID"],
                "payee_signing_seed": seed32_from_hex(os.environ["APP_PAYEE_SEED_HEX"]),
                "agent_recognition_key_id": os.environ["APP_AGENT_RECOGNITION_KEY_ID"],
                "agent_recognition_signing_seed": seed32_from_hex(
                    os.environ["APP_AGENT_RECOGNITION_SEED_HEX"]
                ),
            },
        },
        "registry": registry,
    }
)

Pass the same productionEvidence / production_evidence on instrument({ context: { ... } }) when binding at instrument time.

Keep payee and agent-recognition signing seeds in a trusted runtime (KMS, internal signer, or agent runner) — never in model prompts or browser code.

Policy-driven intent create

When creating a production intent from paybond.policy.yaml, supply principal and payee signing material to toIntentCreateInput():

const intentInput = policy.toIntentCreateInput({
  principalDid,
  principalSigningSeed,
  payeeDid,
  headDigest,
  recognitionProof,
});
await paybond.intents.createWithPolicyBinding(intentInput);

See Agent policy for policy file format and Recognition proofs for proof issuance.

Console-managed credentials

Under Machine Access → Agent middleware keys, tenant admins mint production attach bundles for a funded intent:

  1. Enter the funded intent_id and capability_token.
  2. Copy the one-time env snippet into your secrets manager:
PAYBOND_ATTACH_INTENT_ID=<intent-id>
PAYBOND_CAPABILITY_TOKEN=<token>
PAYBOND_ATTACH_BUNDLE=ab1.<opaque-bundle>

Treat the attach bundle as a secret. The ab1. string is a self-contained AES-256-GCM envelope that embeds its own decryption key next to the ciphertext, so holding the bundle is equivalent to holding the payee and agent-recognition signing seeds in cleartext. Handle it like an API key or private key: paste it straight into a secrets manager, inject it only as the PAYBOND_ATTACH_BUNDLE env var, and never log it, print it, commit it, put it in a URL/query string, or send it back to the server. It is revealed exactly once at mint time — if it leaks or is echoed anywhere shared (CI logs, chat, shell history), revoke the credential from the console inventory and mint a new one. Kit exposes redactPaybondAttachBundle (TS) / redact_attach_bundle (Python) for safe diagnostics.

  1. In application code, bind middleware from env — no raw signing seeds in source:

TypeScript:

const agent = await paybond.agent({
  policy: "travel",
  tools,
  attach: "env",
});

Python:

agent = await paybond.agent(
    {
        "policy": "travel",
        "tools": tools,
        "attach": "env",
    }
)

attach: "env" reads PAYBOND_ATTACH_INTENT_ID, PAYBOND_CAPABILITY_TOKEN, and decrypts PAYBOND_ATTACH_BUNDLE at runtime. Revoke compromised bundles from the console inventory; recognition keys are revoked together with the credential.