Control plane

pikopod up serves two listeners. Each carries a small control surface next to the traffic it handles. When a token is configured, every request to either listener must carry it in X-Pikopod-Token. On loopback with no token, the sandbox control plane is open, because it controls a fake and never a provider. All control responses are JSON with content-type: application/json; charset=utf-8.

Sandbox listener (`:4600`)

Traffic to a sandbox goes to /<name>/.... The control plane lives under /_pikopod/v1/sandboxes/<name>/. The v1 segment is the stable contract the test helpers are written against; every response carries x-pikopod-api: v1. The unversioned paths, /_pikopod/v1/sandboxes/<name>/..., keep working as aliases for one release. A fork’s control plane lives under its own name, /_pikopod/v1/sandboxes/<name>--<token>/, and resolves modes and verification against the parent’s spec and seed.

Rules

Method	Path	Body	Response
`GET`	`/_pikopod/v1/sandboxes/<name>/rules`		`{"rules": {"version": n, "rules": [...]}}`, the set the running sandbox is using
`PUT`	`/_pikopod/v1/sandboxes/<name>/rules`	A rule set, `{"version": n, "rules": [...]}`	`200` with the set now live, or `400` naming the rule the spec refuses

PUT replaces the live set at once and does not write the rules file; pikopod rule add and rule drop write the file and then push it here, so the file stays the source of truth across restarts. See Rules.

Seed, snapshot, reset and forks

Method	Path	Body	Response
`POST`	`/_pikopod/v1/sandboxes/<name>/seed`	`{"<collection>": [ {...}, ... ]}`	`{"seeded": n, "total": m}`, or `400` naming the refused item
`POST`	`/_pikopod/v1/sandboxes/<name>/snapshot`		`{"token": "snap_1"}`
`POST`	`/_pikopod/v1/sandboxes/<name>/restore`	`{"token": "snap_1"}`	`{"restored": "snap_1"}`, or `404` naming an unknown token
`POST`	`/_pikopod/v1/sandboxes/<name>/reset`		`{"reset": true, "seeded": n}`; faults, mode, journal and idempotency memory cleared
`POST`	`/_pikopod/v1/sandboxes/<name>/fork`		`201` with `name`, `url`, `credential`, `seeded`, `expires_in_seconds`
`GET`	`/_pikopod/v1/sandboxes/<name>/forks`		`{"forks": [{"name", "url", "created", "idle_seconds"}]}`
`DELETE`	`/_pikopod/v1/sandboxes/<fork>/fork`		`{"deleted": "<fork>"}`

A fork is served at /<name>--<token>/ and has its own control plane under /_pikopod/v1/sandboxes/<name>--<token>/. Seeding a fork does not change the parent’s seed file. See Running.

Faults

Method	Path	Body	Response
`GET`	`/_pikopod/v1/sandboxes/<name>/faults`		`{"faults": [...]}`
`POST`	`/_pikopod/v1/sandboxes/<name>/faults`	A fault rule (below)	`201 {"armed": <rule>}`
`DELETE`	`/_pikopod/v1/sandboxes/<name>/faults?method=&path=`		`{"cleared": n}`

A fault rule:

{
  "kind": "error",
  "method": "POST",
  "path": "/charges",
  "status": 503,
  "probability": 1,
  "delayMs": 0,
  "event": "",
  "wallclock": false,
  "times": 0,
  "per": "",
  "body": {"error": {"code": "card_declined"}},
  "headers": {"x-request-id": "req_123"}
}

kind is one of error, latency, hang, slow_body, rate_limit, connection_reset, empty_response, random_data_then_close, malformed_response, wrong_content_length, duplicate_webhook, drop_webhook, reorder_webhook, delay_webhook. Non-webhook kinds need method and path (the path template as in the spec). rate_limit is armed as an error with status 429; error with no status becomes 500. probability defaults to 1. body (a JSON object or array) and headers are optional and apply to error; without body the fault answers with the spec’s declared example for that status when there is one, else no body. Without method and path the server answers 400 {"message":"method and path are required"}. See Faults.

Requests journal

Method	Path	Response
`GET`	`/_pikopod/v1/sandboxes/<name>/requests?limit=50`	`{"requests": [...], "evicted": n, "scopes": {"live": n, "evicted": n}}`, newest last
`GET`	`/_pikopod/v1/sandboxes/<name>/requests?scope=<token>`	The same, for the requests that carried `X-Pikopod-Scope: <token>`, plus `"scope": "<token>"`
`DELETE`	`/_pikopod/v1/sandboxes/<name>/requests[?scope=<token>]`	`{"reset": true}`; with `scope`, only that partition is cleared

Each entry carries the sequence number, method, path, matched template, status, and redacted headers, query and body. evicted counts older entries the bounded journal dropped. scopes.live counts the scopes the sandbox currently keeps, at most 256, and scopes.evicted the ones it forgot to make room. See Request journal.

Mode

Method	Path	Body	Response
`GET`	`/_pikopod/v1/sandboxes/<name>/mode`		`{"mode": <spec or null>}`
`POST`	`/_pikopod/v1/sandboxes/<name>/mode`	`{"name": "<archetype or pack>", "seed": "", "bind": {"role": "operationId"}}`	`201 {"mode": <spec>}`
`DELETE`	`/_pikopod/v1/sandboxes/<name>/mode`		`{"cleared": n}`

DELETE clears every fault on the sandbox and removes the stored mode. A scenario that has no standing state is refused with 400 and the reason. See Modes.

Method	Path	Response
`POST`	`/_pikopod/v1/sandboxes/<name>/mode/verify`	`{"result": <run result>, "mode": "<name>", "scopes": {"live": n, "evicted": n}}`; `409` when no mode is set
`POST`	`/_pikopod/v1/sandboxes/<name>/mode/verify?scope=<token>`	The same, judging only the requests that carried `X-Pikopod-Scope: <token>`, plus `"scope": "<token>"`

Without scope, only the requests that carried no scope header are judged. See Scoped, or global.

Webhooks

Method	Path	Body	Response
`GET`	`/_pikopod/v1/sandboxes/<name>/webhooks`		`{"deliveries": [...], "sink": {"delivered", "failed", "dropped", "lastError"}}`
`POST`	`/_pikopod/v1/sandboxes/<name>/webhooks/emit`	`{"event": "<declared event>", "data": {...}}`	`201 {"emitted": "<event>"}`

Only events the spec declares can be emitted. See Webhooks.

Errors

Status	Body
`404`	`{"message":"unknown sandbox <name>"}` or `{"message":"Not Found"}`
`405`	`{"message":"Method Not Allowed"}`
`400`	`{"message":"<what went wrong>"}`

Request bodies are read up to 1 MiB.

Every endpoint, exercised

Each example below is the real request and response from one run of the endpoint, generated by a test in the repository so this section cannot drift from the binary. The sandbox was imported from the example spec with seed docs; the client traffic between the mode and its verification was three POST /charges under one idempotency key.

Rules: read the live set

GET /_pikopod/v1/sandboxes/examplepay/rules

200

{
  "rules": {
    "version": 0,
    "rules": []
  }
}

Rules: replace the live set

PUT /_pikopod/v1/sandboxes/examplepay/rules

{
  "version": 1,
  "rules": [
    {
      "id": "unique-reference",
      "provenance": "manual",
      "when": {
        "method": "POST",
        "path": "/charges",
        "body": {
          "reference": "exists_in_store"
        }
      },
      "respond": {
        "status": 422,
        "body": {
          "error": "reference already used"
        }
      }
    }
  ]
}

200

{
  "rules": {
    "version": 1,
    "rules": [
      {
        "id": "unique-reference",
        "when": {
          "method": "POST",
          "path": "/charges",
          "body": {
            "reference": "exists_in_store"
          }
        },
        "respond": {
          "status": 422,
          "body": {
            "error": "reference already used"
          }
        },
        "provenance": "manual",
        "version": 0
      }
    ]
  }
}

Faults: arm one

POST /_pikopod/v1/sandboxes/examplepay/faults

{
  "kind": "error",
  "status": 503,
  "method": "POST",
  "path": "/charges",
  "times": 2,
  "per": "idempotency-key"
}

201

{
  "armed": {
    "method": "POST",
    "path": "/charges",
    "kind": "error",
    "status": 503,
    "probability": 1,
    "times": 2,
    "per": "idempotency-key"
  }
}

Faults: list standing faults

GET /_pikopod/v1/sandboxes/examplepay/faults

200

{
  "faults": [
    {
      "method": "POST",
      "path": "/charges",
      "kind": "error",
      "status": 503,
      "probability": 1,
      "times": 2,
      "per": "idempotency-key"
    }
  ]
}

Faults: clear matching faults

DELETE /_pikopod/v1/sandboxes/examplepay/faults?method=POST&path=/charges

200

{
  "cleared": 1
}

Mode: enter a scenario’s standing state

POST /_pikopod/v1/sandboxes/examplepay/mode

{
  "name": "retry_storm"
}

201

{
  "mode": {
    "name": "retry_storm",
    "source": "archetype or pack retry_storm",
    "faults": [
      {
        "method": "POST",
        "path": "/charges",
        "kind": "error",
        "status": 503,
        "probability": 1,
        "id": "mode-1",
        "times": 2,
        "per": "idempotency-key"
      }
    ],
    "verify": {
      "inputs": [],
      "defaults": {},
      "steps": [
        {
          "key": "storm-shape",
          "assertions": [],
          "capture": {},
          "continueOnFailure": false,
          "type": "VERIFY_SEQUENCE",
          "config": {
            "requests": [
              {
                "method": "POST",
                "path": "/charges"
              },
              {
                "method": "POST",
                "path": "/charges"
              },
              {
                "method": "POST",
                "path": "/charges"
              }
            ]
          }
        }
      ]
    },
    "revision": 0
  }
}

Mode: verify what the client sent

POST /_pikopod/v1/sandboxes/examplepay/mode/verify

200

{
  "mode": "retry_storm",
  "result": {
    "status": "PASSED",
    "summary": "3 matcher(s) matched in order",
    "notEvaluated": 0,
    "resultHash": "931a201663dfd2aa60a0d4478a7c7a7867ab0eadafafca457e9928682512b1c3",
    "steps": [
      {
        "key": "storm-shape",
        "type": "VERIFY_SEQUENCE",
        "status": "PASSED",
        "summary": "3 matcher(s) matched in order",
        "virtualStartMs": 1735689600000,
        "virtualEndMs": 1735689600000,
        "detail": {
          "journaled": 3,
          "matchers": 3
        }
      }
    ]
  }
}

Mode: show the standing mode

GET /_pikopod/v1/sandboxes/examplepay/mode

200

{
  "mode": {
    "name": "retry_storm",
    "source": "archetype or pack retry_storm",
    "faults": [
      {
        "method": "POST",
        "path": "/charges",
        "kind": "error",
        "status": 503,
        "probability": 1,
        "id": "mode-1",
        "times": 2,
        "per": "idempotency-key"
      }
    ],
    "verify": {
      "inputs": [],
      "defaults": {},
      "steps": [
        {
          "key": "storm-shape",
          "assertions": [],
          "capture": {},
          "continueOnFailure": false,
          "type": "VERIFY_SEQUENCE",
          "config": {
            "requests": [
              {
                "method": "POST",
                "path": "/charges"
              },
              {
                "method": "POST",
                "path": "/charges"
              },
              {
                "method": "POST",
                "path": "/charges"
              }
            ]
          }
        }
      ]
    },
    "revision": 0
  }
}

Mode: clear it

DELETE /_pikopod/v1/sandboxes/examplepay/mode

200

{
  "cleared": 1
}

Requests: the journal

GET /_pikopod/v1/sandboxes/examplepay/requests?limit=2

200

{
  "evicted": 0,
  "requests": [
    {
      "seq": 2,
      "method": "POST",
      "path": "/charges",
      "template": "/charges",
      "status": 503,
      "body": {
        "amount": 5000,
        "currency": "usd"
      },
      "headers": {
        "accept-encoding": "gzip",
        "authorization": "\u003c\u003cSUBSTITUTE:authorization\u003e\u003e",
        "content-length": "32",
        "content-type": "application/json",
        "user-agent": "Go-http-client/1.1"
      },
      "atMs": 1735689600000,
      "wallMs": 1791116413259
    },
    {
      "seq": 3,
      "method": "POST",
      "path": "/charges",
      "template": "/charges",
      "status": 201,
      "body": {
        "amount": 5000,
        "currency": "usd"
      },
      "headers": {
        "accept-encoding": "gzip",
        "authorization": "\u003c\u003cSUBSTITUTE:authorization\u003e\u003e",
        "content-length": "32",
        "content-type": "application/json",
        "user-agent": "Go-http-client/1.1"
      },
      "atMs": 1735689600000,
      "wallMs": 1791116413259
    }
  ]
}

Requests: reset the journal

DELETE /_pikopod/v1/sandboxes/examplepay/requests

200

{
  "reset": true
}

Webhooks: deliveries so far

GET /_pikopod/v1/sandboxes/examplepay/webhooks

200

{
  "deliveries": [],
  "sink": {
    "delivered": 0,
    "failed": 0,
    "dropped": 0
  }
}

Webhooks: emit an event the spec does not declare

POST /_pikopod/v1/sandboxes/examplepay/webhooks/emit

{
  "event": "charge.succeeded"
}

400

{
  "message": "webhook event is not declared: charge.succeeded is not in this sandbox's spec, and pikopod never invents an event → declare it under webhooks in the spec, with x-pikopod-emit-only: true if no API call causes it → https://github.com/pikopod/pikopod/blob/main/scenarios/README.md"
}

Seed: store resources

POST /_pikopod/v1/sandboxes/examplepay/seed

{
  "charges": [
    {
      "id": "ch_8f3a91",
      "amount": 5000,
      "currency": "usd",
      "status": "success"
    }
  ]
}

200

{
  "seeded": 1,
  "total": 1
}

Snapshot: mark a point

POST /_pikopod/v1/sandboxes/examplepay/snapshot

200

{
  "token": "snap_1"
}

Restore: return to it

POST /_pikopod/v1/sandboxes/examplepay/restore

{
  "token": "snap_1"
}

200

{
  "restored": "snap_1"
}

Reset: back to the seeded state

POST /_pikopod/v1/sandboxes/examplepay/reset

200

{
  "reset": true,
  "seeded": 1
}

Fork: a fresh copy for one test

POST /_pikopod/v1/sandboxes/examplepay/fork

201

{
  "credential": "pikopod_sbx_test_cd407f549348ce704a784a71a99566ddb44dc1394cde3354",
  "expires_in_seconds": 600,
  "name": "examplepay--eae742c9",
  "seeded": 1,
  "url": "/examplepay--eae742c9/"
}

Forks: the live copies

GET /_pikopod/v1/sandboxes/examplepay/forks

200

{
  "forks": [
    {
      "created": "2026-10-04T12:20:13Z",
      "idle_seconds": 0,
      "name": "examplepay--eae742c9",
      "url": "/examplepay--eae742c9/"
    }
  ]
}

Fork: delete it

DELETE /_pikopod/v1/sandboxes/examplepay--eae742c9/fork

200

{
  "deleted": "examplepay--eae742c9"
}

Agent listener (`:4700`)

Traffic to an upstream goes to its listen route, /<upstream>/... by default. Anything that matches no upstream answers 404.

Health

GET /healthz is public for liveness. Without a token, or with a token and the header, it returns the full payload:

{
  "status": "ok",
  "uptime_seconds": 120,
  "requests_proxied": 18,
  "upstream_errors": 0,
  "upstream_body_errors": 0,
  "recordings_written": 18,
  "recordings_dropped": 0,
  "recordings_sampled_out": 0,
  "recordings_excluded": 0,
  "observer_panics": 0,
  "events_emitted": 0,
  "divergence_checked": 0,
  "divergence_unverifiable": 0,
  "divergence_skipped": 0,
  "webhooks_received": 0,
  "webhooks_dropped": 0,
  "alerts_sent": 0,
  "last_delivery_ok": false,
  "last_delivery_err": "",
  "deliveries_dropped": 0,
  "saturation_evictions": 0,
  "tracked_fingerprints": 0,
  "baselines": [
    {"endpoint": "examplepay GET /charges", "status_class": "2xx", "samples": 12, "warmed_up": true}
  ]
}

With a token set and no header it answers 200 {"status":"ok"} only, so a load balancer can poll it without being handed your upstream inventory. spec_watch appears when a watcher is armed. The divergence_* counters are described under Divergence and the webhooks_* counters under Incidents.

Inbound webhooks

POST /hooks/<upstream> exists for every upstream with a webhooks.receiver. It needs no token and ignores the loopback Host guard, since the provider delivering to it cannot carry either; it forwards to the configured receiver and nothing else.

Acknowledge and accept

Method	Path	Response
`POST`	`/ack?fp=<fingerprint>`	`{"acked":"<fp>"}`
`POST`	`/accept?fp=<fingerprint>`	`{"accepted":"<fp>","refrozen_families":n}`

agent ack silences a fingerprint until its diff changes. agent accept refreezes the endpoint’s baseline from live traffic and acknowledges, so the drifted behaviour becomes the new normal. Unknown fingerprints answer 404. See Alerts.

Headers the agent handles

X-Pikopod-Token is stripped before anything is forwarded, in every configuration. When an upstream cannot be reached, the agent answers 502 with X-Pikopod-Error: upstream-unreachable and never retries. See Headers.

CLI

Interfaces

Schemas

Sandbox listener (`:4600`)

Rules

Seed, snapshot, reset and forks

Faults

Requests journal

Mode

Webhooks

Errors

Every endpoint, exercised

Rules: read the live set

Rules: replace the live set

Faults: arm one

Faults: list standing faults

Faults: clear matching faults

Mode: enter a scenario’s standing state

Mode: verify what the client sent

Mode: show the standing mode

Mode: clear it

Requests: the journal

Requests: reset the journal

Webhooks: deliveries so far

Webhooks: emit an event the spec does not declare

Seed: store resources

Snapshot: mark a point

Restore: return to it

Reset: back to the seeded state

Fork: a fresh copy for one test

Forks: the live copies

Fork: delete it

Agent listener (`:4700`)

Health

Inbound webhooks

Acknowledge and accept

Headers the agent handles

​Sandbox listener (:4600)

​Rules

​Seed, snapshot, reset and forks

​Faults

​Requests journal

​Mode

​Webhooks

​Errors

​Every endpoint, exercised

​Rules: read the live set

​Rules: replace the live set

​Faults: arm one

​Faults: list standing faults

​Faults: clear matching faults

​Mode: enter a scenario’s standing state

​Mode: verify what the client sent

​Mode: show the standing mode

​Mode: clear it

​Requests: the journal

​Requests: reset the journal

​Webhooks: deliveries so far

​Webhooks: emit an event the spec does not declare

​Seed: store resources

​Snapshot: mark a point

​Restore: return to it

​Reset: back to the seeded state

​Fork: a fresh copy for one test

​Forks: the live copies

​Fork: delete it

​Agent listener (:4700)

​Health

​Inbound webhooks

​Acknowledge and accept

​Headers the agent handles

Sandbox listener (`:4600`)

Rules

Seed, snapshot, reset and forks

Faults

Requests journal

Mode

Webhooks

Errors

Every endpoint, exercised

Rules: read the live set

Rules: replace the live set

Faults: arm one

Faults: list standing faults

Faults: clear matching faults

Mode: enter a scenario’s standing state

Mode: verify what the client sent

Mode: show the standing mode

Mode: clear it

Requests: the journal

Requests: reset the journal

Webhooks: deliveries so far

Webhooks: emit an event the spec does not declare

Seed: store resources

Snapshot: mark a point

Restore: return to it

Reset: back to the seeded state

Fork: a fresh copy for one test

Forks: the live copies

Fork: delete it

Agent listener (`:4700`)

Health

Inbound webhooks

Acknowledge and accept

Headers the agent handles