# pikopod

> Rehearse API failures before you ship, and replay the ones production already hit.

- [Introduction](https://docs.pikopod.com/getting-started/introduction.md): Rehearse API failures before you ship, and replay the ones production already hit.
- [Installation](https://docs.pikopod.com/getting-started/installation.md): One static binary for macOS, Linux and Windows. No runtime, no daemon, no account.
- [Quickstart](https://docs.pikopod.com/getting-started/quickstart.md): Import a spec, make it fail, gate a build, and reproduce a production failure in ten minutes.
- [The loop](https://docs.pikopod.com/getting-started/the-loop.md): One cycle, not three tools. Each stage feeds the next.
- [Coding agents](https://docs.pikopod.com/getting-started/coding-agents.md): Serve pikopod's checks to a coding agent over the Model Context Protocol.
- [Spec diff](https://docs.pikopod.com/gate/spec-diff.md): Fail the build on a breaking spec change. No proxy, no account, nothing in your request path.
- [Severity](https://docs.pikopod.com/gate/severity.md): One function maps the shape of a change onto ERR, WARN or INFO. No check carries a hand-assigned severity.
- [Multi-file specs](https://docs.pikopod.com/gate/multi-file-specs.md): Which $refs pikopod resolves, wherever it reads a spec.
- [CI integration](https://docs.pikopod.com/gate/ci-integration.md): One job that fails the build on a breaking spec change and annotates the pull request.
- [Sandbox](https://docs.pikopod.com/sandbox/overview.md): A deterministic, stateful simulator built from the provider's own spec. Same seed, same bytes, every run.
- [Importing](https://docs.pikopod.com/sandbox/importing.md): A spec becomes a sandbox. Formats, seeds, credentials, and refreshing the pin.
- [Importing from a docs URL](https://docs.pikopod.com/sandbox/docs-url-import.md): When the provider ships no spec, point --spec at their documentation page.
- [Running](https://docs.pikopod.com/sandbox/running.md): pikopod up serves every registered sandbox on one port, with a control plane next to it.
- [Faults](https://docs.pikopod.com/sandbox/faults.md): Every failure the sandbox can produce on demand, and what each does on the wire.
- [Modes](https://docs.pikopod.com/sandbox/modes.md): Put the served sandbox into a scenario's standing state, then run your own tests against it.
- [Webhooks](https://docs.pikopod.com/sandbox/webhooks.md): Deliveries wrapped and signed the way the provider documents, for events the spec declares and only those.
- [Request journal](https://docs.pikopod.com/sandbox/request-journal.md): What your code actually sent to the sandbox, as opposed to what it was meant to send.
- [Recordings tier](https://docs.pikopod.com/sandbox/recordings-tier.md): Serve the linked upstream's recorded traffic for requests neither the spec nor admitted traffic can answer.
- [Limits](https://docs.pikopod.com/sandbox/limits.md): Quotas and bounds on the sandbox, fixed rather than configured.
- [Scenarios](https://docs.pikopod.com/scenarios/overview.md): Failure stories run against the sandbox. Eleven bind themselves to your API; the rest you generate or write.
- [Archetypes](https://docs.pikopod.com/scenarios/archetypes.md): Eleven provider-agnostic failure stories that bind themselves to your API from its spec.
- [Binding](https://docs.pikopod.com/scenarios/binding.md): How an archetype attaches to your API, why it sometimes refuses, and how to assert a fact yourself.
- [Running scenarios](https://docs.pikopod.com/scenarios/running.md): scenario run, its flags, and how to read the result.
- [Pack format](https://docs.pikopod.com/scenarios/pack-format.md): Writing a scenario by hand. Steps, assertions, captures, seed data, and limits.
- [Generated packs](https://docs.pikopod.com/scenarios/generated-packs.md): Packs pikopod writes for you from a drift event, an incident, or recorded traffic.
- [Plain English](https://docs.pikopod.com/scenarios/plain-english.md): Draft a scenario from a sentence, grounded against the operations your API actually has.
- [Observe](https://docs.pikopod.com/observe/overview.md): A fail-open reverse proxy that forwards your traffic untouched and watches for failures and shape changes.
- [Data plane safety](https://docs.pikopod.com/observe/data-plane-safety.md): The proxy serves first and observes afterwards. Nothing internal may alter, delay or drop your traffic.
- [Redaction](https://docs.pikopod.com/observe/redaction.md): Values are classified and rewritten on the way in. What reaches disk is what you would share.
- [Warmup and baselines](https://docs.pikopod.com/observe/warmup-and-baselines.md): Learn what normal is, freeze it, then compare against the frozen copy.
- [Drift](https://docs.pikopod.com/observe/drift.md): A successful response whose shape changed against the frozen baseline.
- [Incidents](https://docs.pikopod.com/observe/incidents.md): An exchange that failed. Needs no baseline, fires from the first request, and is always reproducible.
- [Alerts](https://docs.pikopod.com/observe/alerts.md): One alert per fingerprint, forever. Dedupe, thresholds, delivery, and what ack and accept do.
- [Volatile fields](https://docs.pikopod.com/observe/volatile-fields.md): Silence values that churn by nature, without silencing the shape of the field.
- [Spec watch](https://docs.pikopod.com/observe/spec-watch.md): Re-fetch the provider's published spec, diff it against your pin, and join it with what traffic shows.
- [Contract](https://docs.pikopod.com/observe/contract.md): The effective contract is the spec plus what traffic has taught it. Conformance asks whether the provider obeys its own spec.
- [State machine](https://docs.pikopod.com/observe/state-machine.md): The transitions a provider actually makes, learned from traffic. Nothing in a specification can say this.
- [Replay gate](https://docs.pikopod.com/observe/replay-gate.md): Gate builds offline on recorded traffic against frozen baselines.
- [Inspecting](https://docs.pikopod.com/observe/inspecting.md): status, report and inspect. What the agent has seen, learned, and written.
- [Reproduce](https://docs.pikopod.com/reproduce/reproduce.md): Turn a recorded production failure into a scenario that recreates it against the sandbox, on your laptop.
- [Incident bundles](https://docs.pikopod.com/reproduce/incident-bundles.md): Move an incident from the agent host to any machine that will reproduce or fix it.
- [Fix](https://docs.pikopod.com/reproduce/fix.md): Turn a drift event into a code change in your repository, verified by your own check and reverted in full if it fails.
- [Pull requests](https://docs.pikopod.com/reproduce/pull-requests.md): Post findings on a pull request, or open one carrying a fix. GitHub and GitLab.
- [Configuration](https://docs.pikopod.com/operations/configuration.md): Every key in pikopod.yaml, every default, every environment override.
- [Deployment](https://docs.pikopod.com/operations/deployment.md): Where the agent runs, where its state lives, and how an incident reaches a developer.
- [Security](https://docs.pikopod.com/operations/security.md): How pikopod behaves in a production request path, and what leaves the machine.
- [Data directory](https://docs.pikopod.com/operations/data-directory.md): Everything pikopod persists lives under data_dir. Nothing is uploaded.
- [Exit codes](https://docs.pikopod.com/operations/exit-codes.md): Exit codes are API. Script against them.
- [Troubleshooting](https://docs.pikopod.com/operations/troubleshooting.md): Every pikopod error names what failed, why, the next action, and a docs link.
- [Development](https://docs.pikopod.com/project/development.md): Build, test and release pikopod from source.
- [Contributing](https://docs.pikopod.com/project/contributing.md): How to propose a change to pikopod.
- [Security policy](https://docs.pikopod.com/project/security-policy.md): How to report a vulnerability in pikopod.
- [License](https://docs.pikopod.com/project/license.md): pikopod is open source under Apache-2.0.
- [CLI overview](https://docs.pikopod.com/reference/cli/overview.md): Every pikopod command, grouped by what it does.
- [pikopod up](https://docs.pikopod.com/reference/cli/up.md): Serve the observing agent and every registered sandbox in one process.
- [pikopod import](https://docs.pikopod.com/reference/cli/import.md): Import an API spec, or a documentation page, into a deterministic sandbox.
- [pikopod sandbox](https://docs.pikopod.com/reference/cli/sandbox.md): Add, list, reset, and inspect sandboxes, and attach webhook envelopes.
- [pikopod scenario](https://docs.pikopod.com/reference/cli/scenario.md): List, run, create, and derive scenarios.
- [pikopod chaos](https://docs.pikopod.com/reference/cli/chaos.md): Arm, list and clear faults on a running sandbox.
- [pikopod mode](https://docs.pikopod.com/reference/cli/mode.md): Put a running sandbox into a scenario's standing failure state, and run your own tests against it.
- [pikopod webhook](https://docs.pikopod.com/reference/cli/webhook.md): Fire a declared event on a running sandbox, and see how the sink answered.
- [pikopod why](https://docs.pikopod.com/reference/cli/why.md): Replay a request against a fork of the sandbox with decision tracing, and see exactly why it answers what it answers.
- [pikopod spec-diff](https://docs.pikopod.com/reference/cli/spec-diff.md): Diff two API spec versions. Declared drift, severity derived by law.
- [pikopod spec-update](https://docs.pikopod.com/reference/cli/spec-update.md): Write a traffic-evidenced spec update. Additive patches applied in place, narrowings as suggestions.
- [pikopod incidents](https://docs.pikopod.com/reference/cli/incidents.md): List recorded incidents and drift events, and export a bundle.
- [pikopod replay](https://docs.pikopod.com/reference/cli/replay.md): Gate builds offline on recorded traffic against frozen baselines.
- [pikopod conformance](https://docs.pikopod.com/reference/cli/conformance.md): Validate recorded traffic against the spec. Does the provider obey its own documentation?
- [pikopod contract](https://docs.pikopod.com/reference/cli/contract.md): The effective contract, traffic-admitted additions, contradictions, pinned scenarios, and the observed state machine.
- [pikopod status, report, inspect](https://docs.pikopod.com/reference/cli/status-report-inspect.md): Health of the running agent, the endpoint inventory, and stored records with tokens visible.
- [pikopod ack, accept, baseline](https://docs.pikopod.com/reference/cli/ack-accept-baseline.md): Silence an alert, accept a drift as the new normal, or re-learn baselines.
- [pikopod volatile](https://docs.pikopod.com/reference/cli/volatile.md): Suggest volatile_fields entries from recorded churn, and lint the ones you have.
- [pikopod fix](https://docs.pikopod.com/reference/cli/fix.md): Turn a drift event into a code change in your repository.
- [pikopod pr](https://docs.pikopod.com/reference/cli/pr.md): Post findings to a pull request, or open one carrying a fix.
- [pikopod mcp](https://docs.pikopod.com/reference/cli/mcp.md): Serve pikopod's checks and sandbox controls to a coding agent over the Model Context Protocol.
- [pikopod init, doctor, demo](https://docs.pikopod.com/reference/cli/init-doctor-demo.md): Scaffold a config, verify the wiring, and see the whole loop in a second.
- [Control plane](https://docs.pikopod.com/reference/control-plane.md): The HTTP endpoints pikopod up serves besides your traffic.
- [MCP tools](https://docs.pikopod.com/reference/mcp-tools.md): Every tool pikopod mcp serves, its arguments, and how its verdict is decided.
- [Environment variables](https://docs.pikopod.com/reference/environment-variables.md): Every variable pikopod reads, and what it overrides.
- [Headers](https://docs.pikopod.com/reference/headers.md): The request and response headers pikopod reads, sets, and strips.
- [Drift event schema](https://docs.pikopod.com/reference/drift-event-schema.md): The one shape pikopod emits for a drift or an incident, to stdout, to Slack, and to the event log.
- [Scenario pack schema](https://docs.pikopod.com/reference/scenario-pack-schema.md): The full grammar of a scenario pack, as validated by schema/scenario-pack.schema.json.
- [Incident bundle](https://docs.pikopod.com/reference/incident-bundle.md): The self-contained file pikopod incidents export writes, and what reproduce and fix accept.