Sandbox events

Sandbox events use one versioned envelope across SSE and JSON history:

{
	"id": "1042",
	"object": "sandbox.event",
	"version": "v1",
	"type": "message.updated",
	"ts": "2026-08-06T12:00:00.000Z",
	"sandbox_id": "c_…",
	"turn_id": "turn_…",
	"data": {}
}

Payloads are curated. Sparkles never forwards a raw agent-runtime event, tool payload, credential, internal session identifier, or compatibility raw field.

Event types

Type	Meaning
`snapshot`	Current resource and turn state sent when a stream connects.
`sandbox.status`	Transient lifecycle update during boot or state changes.
`turn.started`	A prompt began a new turn.
`turn.completed`	A turn settled as `succeeded`, `failed`, or `canceled`.
`message.updated`	Latest snapshot of one assistant message part.
`message.completed`	The assistant’s final message for a turn.
`tool.updated`	Curated tool-call state changed.
`approval.requested`	A tool is waiting for an approval decision.
`approval.resolved`	A pending approval was approved, denied, canceled, or failed.
`sandbox.error`	A public, sanitized execution error occurred.

Unknown internal event types are explicitly dropped by the translation layer.

Snapshot semantics

message.updated is last-write-wins. Use part_id as the key and replace the stored snapshot instead of concatenating deltas. A later message.completed marks the assistant result as final.

Resume and replay

Durable frames have an SSE id equal to the coordinator event sequence. snapshot and transient sandbox.status frames intentionally have no SSE ID because they cannot be rewound. On reconnect, send the last processed durable ID in Last-Event-ID. The since query parameter is the fallback for clients that cannot set the header. A fresh connection starts with a snapshot and follows the live tail; request ?since=0 to replay retained history. The stream sends keepalive pings and can cover the complete create-to-boot window before an agent session exists. Network delivery is at least once within retention. Deduplicate by durable id, and use the JSON events page plus GET /sandboxes/{id} to recover from a stale or pruned cursor. Browser EventSource cannot set the bearer authorization header. Use a fetch-based SSE reader.

Get started

Sparkles CLI

Sandbox API

API reference

Event types

Snapshot semantics

Resume and replay

​Event types

​Snapshot semantics

​Resume and replay

Event types

Snapshot semantics

Resume and replay