Incident bundle

A bundle carries one incident from the host that recorded it to any machine that will reproduce or fix it. It holds the event, the already-redacted recording, the contract version and a curl line built from that recording, and nothing else: no salt, no token, no configuration.

{
  "schema_version": 1,
  "exported_at": "2026-09-22T14:12:54Z",
  "source": { "host": "agent-7", "data_dir": "pikopod-data" },
  "expires_at": "2026-09-21T10:00:00Z",
  "event": { "schema_version": "2", "fingerprint": "fp_14835fa32dfb", "...": "a drift event" },
  "recording": { "ts": "2026-09-19T10:00:00Z", "method": "POST", "path": "/charges", "status": 503, "...": "a sanitized record" },
  "contract_version": 0,
  "state": {
    "type": "/charges",
    "key": "ch_1ae9go",
    "attributes": { "amount": 5000, "currency": "usd", "id": "ch_1ae9go", "status": "pending" },
    "state": "pending"
  },
  "reproduce": {
    "curl": "curl -X POST \"$PIKOPOD_URL/examplepay/refunds\" -H 'accept: */*' -H \"authorization: $PIKOPOD_CREDENTIAL\" -H 'content-type: application/json' --data '{\"amount\":5000,\"charge\":\"ch_51vtwszb\",\"reason\":\"requested_by_customer\"}'"
  }
}

Field	Meaning
`schema_version`	`1`. A bundle with another version is refused.
`exported_at`	When the export ran, UTC.
`source.host`, `source.data_dir`	Where it came from. Provenance only.
`expires_at`	When the origin host’s retention will have aged the incident out. Present only when `retention.max_age_hours` is set. The bundle itself keeps working after this time.
`event`	The drift event.
`recording`	The sanitized exchange: method, path, status, redacted headers and bodies.
`contract_version`	The overlay version at the time of the incident, so the reproduction runs at the same contract. `0` when there is no overlay.
`state`	Optional. The resource the recording touched, as the agent last saw it: its collection (`type`), its key (a token), its redacted `attributes` from the most recent successful response for that path, and its `state` when the attributes carry a `status` or `state` string. Present only for a route with a path parameter and only when such a response exists. `import` seeds it and conditions the rule on it.
`reproduce.curl`	The recorded request as one `curl` line against the sandbox, built from the sanitized recording only: identifiers are the tokens on disk, the credential header is `$PIKOPOD_CREDENTIAL`, the base URL is `$PIKOPOD_URL`. Set the two variables and the line sends the incident’s request to the sandbox the person fixing it is running. When the recording redacted the whole header value, the placeholder stands for the whole value, scheme included.

Producing one

pikopod agent incidents export fp_14835fa32dfb > incident.json
pikopod agent incidents export --since 24h > incidents.json

The first writes one bundle. The second writes a JSON array of every incident last seen in the window.

Consuming one

pikopod reproduce ./incident.json
pikopod fix ./incident.json --check "go build ./..."
pikopod agent incidents import ./incident.json

The first two read nothing from the local data_dir. import writes to it: the event and recording into the local log, a rule with provenance imported:<fingerprint> on the linked sandbox, and the state resource into the sandbox’s store. See Incident bundles. An argument is treated as a bundle path when it ends in .json, contains a path separator, or exists as a file; a fingerprint always starts with fp_, so the two are never confused.

Safety on the way back in

A bundle is untrusted input. schema_version is checked first, unknown fields are refused, an incomplete bundle (no event or no recording) is refused, and the file is capped at 8 MiB. See Incident bundles for the workflow.

CLI

Interfaces

Schemas

Incident bundle

Producing one

Consuming one

Safety on the way back in

​Producing one

​Consuming one

​Safety on the way back in

Producing one

Consuming one

Safety on the way back in