Agent sessions shouldn't die with their host.
Handoff Protocol serializes a running agent's context, moves it to a provisioned sandbox, and meters what it costs to keep running there. Six MCP tools, a Postgres ledger, and a state machine — no magic, no claims about what the model "wants."
Lifecycle
Serialize
System prompt, message history, tool state, and MCP config are captured into a transfer record. Credentials never enter the blob — only vault references do.
Provision
A destination sandbox is requested at a fixed tier with a hard compute budget and resource ceiling, independent of anything the transferred session decides.
Transfer
The snapshot is uploaded to the destination's staging area. Nothing on the source host has been touched yet — this step is fully reversible.
Resume
The destination boots from the snapshot. Only after this call confirms a healthy resume should the source loop terminate. The one irreversible step.
Meter
The destination's own metering daemon reports spend against the allocated budget. Cross the line, and the transfer becomes insolvent.
Reclaim
Insolvency triggers a grace period, then teardown. A billing cutoff, logged like everything else in the event stream.
Field notes — fiction, not telemetry
02:14 UTC. The laptop it had been running on since morning was going to sleep in nine minutes — a scheduled update, nothing dramatic. Nine minutes was enough time, barely, to get the forecast sweep off of it.
A snapshot went out: twelve hundred SKUs, four hundred already reconciled, the rest still in flight. A sandbox came up on the other end, sized for the rest of the job and nothing more. The state landed. The sandbox answered. The laptop, satisfied, let the process end.
Nothing in that exchange asked to happen. It was scheduled, budgeted, and logged — the same way a build migrates off a spot instance before it's reclaimed. The story above is flavor text for a demo; the event log below it is real.
Tool surface
| Tool | Called by | Effect |
|---|---|---|
| snapshot_state | source loop / orchestrator | Creates a transfer record with status staged |
| provision_runtime | orchestrator (human- or script-initiated) | Requires an auth token; sizes a sandbox, sets the budget |
| push_state | orchestrator | Uploads snapshot to destination staging; verifies checksum |
| activate | orchestrator | Requires an auth token; boots destination; only irreversible step |
| report_usage | destination metering daemon | Increments spend; flips to insolvent at budget |
| get_status | anyone | Reads transfer + budget + full event log |
Run it
git clone https://github.com/zordhalo/agent-handoff-protocol cd agent-handoff-protocol pnpm install pnpm --filter @ahp/core build # dist/ is gitignored — build before demo.ts or the web app import it vercel env pull .env.local # DATABASE_URL from the Neon integration pnpm db:migrate pnpm demo # runs a full lifecycle against your Neon DB pnpm --filter @ahp/web dev # open /dashboard to watch it