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.

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

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

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 run examplepay declines retry_storm

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

✓ 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; 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

pikopod scenario list examplepay shows every story that bound and, for any
that did not, which fact in the spec was missing. pikopod up serves the
sandbox on :4600/examplepay so your own tests meet the same failures, and
pikopod chaos arms one fault directly. See 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 incidents lists
what failed, newest first, each with a fingerprint:

pikopod scenario 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 run examplepay incident-14835fa32dfb

The generated pack is an ordinary scenario: commit it and it guards that path
forever. pikopod 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

License

Apache-2.0. See LICENSE.