pikopod

A sandbox for the third-party APIs you depend on. Built from the provider's spec,
it fails on purpose, and it replays the exact failure production hit.

Docs · Quickstart · pikopod.com

Their sandbox only knows how to succeed. It has never declined a charge in a way you didn't ask for, never timed out halfway through, never delivered the same webhook twice. So the first time your retry path runs for real, it runs against real money. pikopod builds a sandbox from your provider's own spec, makes it fail on purpose, and when production fails anyway, replays that exact failure back into it so you fix it on a laptop and keep the fix as a test.

One Go binary. Runs locally. No accounts, no telemetry, no cloud.

Install

go install github.com/pikopod/pikopod/cmd/pikopod@latest

Or with Homebrew:

brew trust pikopod/tap
brew install pikopod/tap/pikopod

Recent Homebrew requires third-party taps to be trusted explicitly; without the first line it reports Invalid formula. Or download a signed binary from Releases: macOS and Linux, amd64 and arm64, static, zero dependencies. Every release ships SHA256SUMS, cosign-signed, with SLSA provenance; the verification command is in Installation.

Try it in ten seconds

pikopod demo

Zero config. It stands up a fake provider, sends traffic, silently changes the provider's responses, and prints the alerts. Runs in about a second.

Three things, one tool

	What it does	Docs
Rehearse	A deterministic sandbox built from the provider's spec. Eleven failure stories bind to it with nothing authored: declines, timeouts, retry storms, duplicate webhooks.	Sandbox · Scenarios
Observe	A fail-open proxy in front of the real provider. It records failures from the first request and shape changes once it knows what normal is, then hands you a fingerprint.	Observe
Reproduce	The fingerprint becomes a scenario that replays the production failure against the sandbox. Commit it, and the path is guarded forever.	Reproduce

You cannot ask a provider's sandbox to return that exact 503, with that body, at that point in your state machine. pikopod can, because the same tool recorded it and owns the sandbox. See The loop.

Start here: catch a breaking change in CI

No proxy, no account, no config file. It reads two versions of a spec straight from git with no checkout and fails the build on a breaking change:

pikopod spec-diff git:origin/main:openapi.yaml openapi.yaml --fail-on ERR

1 change(s): 1 ERR, 0 WARN, 0 INFO

ERR  GET    /charges/{id}                            endpoint-removed
     endpoint removed from the spec  [fp_bcc85ba9a094]

breaking declared drift at/above ERR — failing the gate (exit 1)

Exit 0 clean, 1 breaking, 2 tool error. Add --format githubactions and every finding lands inline on the pull request diff. Severity comes from one fixed rule, so "breaking" means the same thing on every endpoint and every provider. See Spec diff and CI integration.

Rehearse: make the sandbox fail

curl -fsSL -o examplepay.spec.json https://raw.githubusercontent.com/pikopod/pikopod/main/docs/demo/examplepay.spec.json
pikopod init
pikopod import examplepay --spec ./examplepay.spec.json
pikopod scenario list examplepay

--spec also takes your provider's spec URL, or its documentation page.

archetypes vs examplepay (4 endpoints):
  ✓ happy_path                 Happy path  (1 candidate binding(s))
  ✓ unauthorized               Unauthorized  (4 candidate binding(s))
  ✓ invalid_request            Invalid request  (1 candidate binding(s))
  ✗ duplicate_delivery         Duplicate delivery
      no webhookEvent matching {} for role 'emittedEvent'
  ✓ rate_limit_backoff         Rate limit and backoff  (4 candidate binding(s))
  ✓ state_transition_sequence  State transition sequence  (1 candidate binding(s))
  ✓ retry_storm                Retry storm with recovery  (1 candidate binding(s))
  ✓ declines                   Declines  (1 candidate binding(s))
  ✓ timeouts                   Timeouts  (1 candidate binding(s))
  ✓ partial_failure            Partial failure  (1 candidate binding(s))
  ✓ downtime_recovery          Downtime and recovery  (1 candidate binding(s))

Ten stories bound to four endpoints with nothing authored. The one that did not says which fact the spec is missing.

pikopod scenario check examplepay declines retry_storm

✓ declines — PASSED (4 assertion(s) passed; 0 not evaluated)
    NOT_EVALUATED  arm-decline      armed error on POST /charges
    PASSED         declined         POST /charges → 400
    NOT_EVALUATED  clear            cleared matching faults
    PASSED         recovered        POST /charges → 201
✓ retry_storm — PASSED (7 assertion(s) passed; 0 not evaluated)
    NOT_EVALUATED  arm              armed error on POST /charges
    PASSED         attempt1         POST /charges → 503
    PASSED         attempt2         POST /charges → 503
    PASSED         attempt3         POST /charges → 201
    PASSED         storm-shape      3 matcher(s) matched in order

That proves the sandbox fails the way the story says. To prove your own code survives it, serve the sandbox with pikopod up, put it into the story's standing state, run your tests against :4600/examplepay, then ask:

pikopod mode set examplepay retry_storm
pikopod mode verify examplepay

✓ retry_storm — PASSED (3 assertion(s) passed; 0 not evaluated)
    PASSED         storm-shape      3 matcher(s) matched in order

verify reads what your client actually sent and exits 1 when it fell short, so it can sit in CI next to your test suite. pikopod chaos arms one fault directly. See Modes and Faults.

Observe and reproduce

pikopod up also starts the observing agent on :4700/examplepay. Point your app's provider base URL at it, keeping your real credentials; it forwards everything untouched and watches. Incidents fire from the first request. Drift waits 50 samples and 48 hours per endpoint, because a baseline built from five responses has not seen your optional fields yet. pikopod agent incidents lists what failed, newest first, each with a fingerprint:

pikopod reproduce fp_14835fa32dfb

reproduced fp_14835fa32dfb (examplepay answered 503 on POST /charges) as pikopod-data/scenarios/incident-14835fa32dfb.yaml
PASSED — 1 assertion(s) passed; 0 not evaluated
the failure now happens locally — fix it, then re-run: pikopod scenario check examplepay incident-14835fa32dfb

The generated pack is an ordinary scenario: commit it and it guards that path forever. pikopod agent replay --ci then gates every build on recorded traffic, with no network and no provider account. For a shape change rather than a failure, pikopod scenario from-drift <fp> pins the old contract instead. See Drift and Replay gate.

It cannot slow your traffic down

The agent serves first and observes afterwards: observation is asynchronous, bounded, and panic-isolated, so if pikopod breaks internally your traffic still flows. It never retries, because a retry in front of a payments API is a double-charge window. It redacts before anything touches disk: credentials become placeholders, identifiers become format-preserving tokens, and unclassifiable strings are dropped. See Data plane safety and Redaction.

Use it from a coding agent

pikopod mcp serves the same checks over the Model Context Protocol, and UNVERIFIABLE is never dressed up as CLEAN. See Coding agents.

{ "mcpServers": { "pikopod": { "command": "pikopod", "args": ["mcp"] } } }

Documentation

docs.pikopod.com: Quickstart · Configuration · Exit codes · Security · CLI reference

Contributing: CONTRIBUTING.md · DEVELOPMENT.md · SECURITY.md · CODE_OF_CONDUCT.md · RELEASE.md

License

Apache-2.0. See LICENSE.