Skip to main content
Every registered sandbox is served at http://127.0.0.1:4600/<name>/. The agent and the sandbox run in one process and fail independently.

​
Without a config file

--spec serves one sandbox from a temporary data directory, with no pikopod.yaml and no agent. --name, --seed, --seed-data and --port apply. Ctrl-C removes the directory. Register the sandbox with pikopod import when you want it to outlive the process.

​
Seeding

A fresh sandbox holds nothing, so the first GET /charges/{id} is a 404 until something creates it. A seed file stores resources before the first request:
Each top-level key names a collection the spec declares, such as charges for /charges; a key no operation stores is refused by name. Every item is validated like a create, so a wrong type is refused naming the field. An id becomes the store key; an item without one gets the next key the sandbox would have assigned. pikopod sandbox seed <name> <file> adds more later, into the running sandbox when pikopod up is serving it and into the store otherwise, and sandbox list shows seeded: N resources.

​
Snapshot, restore and reset

The control plane can mark a point and return to it, without stopping pikopod up:
A snapshot covers stored resources; the newest sixteen are kept. reset goes further: back to the seeded state, with faults, the standing mode, the request journal and idempotency memory cleared:
pikopod sandbox reset <name> does the same, through the running server when there is one and directly on the store otherwise.

​
A fresh sandbox per test

Two test files sharing one sandbox see each other’s resources and modes. A fork is an ephemeral copy with the same spec, seed and seed data, served under its own route:
Point one test at http://127.0.0.1:4600/examplepay--c7a4716e/ and it starts from the seeded state, creates stay inside it, and two forks with one seed answer the same bytes. A fork enters modes and verifies like its parent. It is removed with DELETE /_pikopod/v1/sandboxes/<fork>/fork or after ten idle minutes; GET /_pikopod/v1/sandboxes/examplepay/forks lists the live ones. The test helpers take one per test.

​
Point staging at it

Set your application’s provider base URL to http://127.0.0.1:4600/examplepay and send the issued credential. Every response carries X-Pikopod-Operation naming the operation that matched and x-pikopod-contract-version naming the contract version it was rendered from.

​
The control plane

Under /_pikopod/v1/sandboxes/<name>/ the sandbox listener serves faults, the request journal, the standing mode, and webhook deliveries. The CLI commands chaos, mode, webhook and requests talk to it, and so do the MCP control tools. On loopback it is unauthenticated, because it controls a fake and never a provider. See Control plane.

​
Ports, addresses and tokens

Binding a non-loopback address requires a token, sent as X-Pikopod-Token on every request. See Configuration.

​
Real delays

Armed delays are virtualized by default: a latency fault of 30 seconds is instant on the wire and reported in the x-pikopod-fault-delay-ms response header, which is what scenario check measures against. To make delays and hangs real on the wire for your own tests:
Or pass --wallclock when arming one fault. See Faults.

​
Several sandboxes

Register as many as you need; each gets its own route and seed. A mode is global to one sandbox, so two suites that need different failures at once should use two sandboxes, or two pikopod up processes on different ports with their own data_dir.

​
Resetting

pikopod sandbox reset <name> returns the sandbox to its seeded state and clears faults, mode and journal, on the running server when there is one. See pikopod sandbox.