pikopod

Their sandbox only knows how to succeed. So the first time your retry path runs for real, it runs against real money.

pikopod builds a sandbox from your provider's spec, makes it fail on purpose, learns from what the provider really sends, and replays the exact failure production hit, on your laptop, as a test you keep.

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

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: turn last week's provider incident into a test

With pikopod up in front of the real provider in staging or production, every failure the provider throws is recorded, redacted, and listed with a handle:

pikopod agent incidents

[ERR] incident upstream_error         POST /charges (examplepay) · 4 occurrence(s) · last 2026-09-19T10:00:00Z
  fp_14835fa32dfb
  reproduce: pikopod reproduce fp_14835fa32dfb
  export: pikopod agent incidents export fp_14835fa32dfb

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 on every build. When the agent runs on another host, pikopod agent incidents export <fp> writes a bundle that reproduce accepts anywhere. See Incidents and Reproduce.

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 (4 assertion(s) passed; 3 matcher(s) matched in order; 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 matcher(s) matched in order)
    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: what the provider did that the sandbox would not have

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. So does divergence: every production answer is compared with what the sandbox would have said, and a 422 on a duplicate the spec never mentions becomes an event with a fingerprint and a reproduce command. Drift waits 50 samples and 48 hours per endpoint, because a baseline built from five responses has not seen your optional fields yet.

The recordings then answer the sandbox before the spec, so the sandbox learns from production, and pikopod agent truthfulness examplepay says how much of what the provider really sent it reproduces. pikopod agent replay --ci gates every build on recorded traffic, with no network and no provider account. See Divergence, Precedence, Truthfulness and Replay gate.

Also: gate CI on a breaking spec change

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. In GitHub Actions it is two lines, with the release verified by cosign before it runs and every finding inline on the pull request diff:

- uses: Pikop