docs(env-recipes): warn that snapshotting a started runtime bakes its identity (#17001)

Snapshotting a VM on which `orca serve` has already run captures the
runtime's user-data dir into the image. Every VM booted from that image
then shares one pairing identity and one agent-session-authority key,
which defeats the per-device token design.

Confirmed by booting two VMs from one such snapshot: both emitted
identical deviceToken and pairedDeviceId.

Adds the rule to the base-snapshot section and repeats it for the
agent-auth layer, which is the likelier place to start the runtime by
hand while smoke-testing. Says to delete the whole user-data dir rather
than a named file list, since that list drifts as Orca adds state.
This commit is contained in:
Neil
2026-08-28 02:37:55 -07:00
committed by GitHub
parent a4762f1c1d
commit 2b0ee06205
2 changed files with 12 additions and 1 deletions
+11
View File
@@ -135,6 +135,13 @@ shape is §7a; key points:
- Use the VM image's package manager (`apt`/`dnf`/`apk`, per the base distro — not the provider brand).
- Clone with the git token via `GIT_ASKPASS` (§5).
- **Trap errors and remove the half-built sandbox** so a crash doesn't leave a paid resource running.
- **Never snapshot a machine on which the Orca runtime has already run.** The first `orca serve` creates
the runtime's user-data dir, and everything in it gets baked into the image and shared by every VM
booted from it: the pairing keypair and device-token registry (`orca-devices.json`,
`orca-e2ee-keypair.json`), `agent-session-authority.key`, and the build box's logs, terminal history
and orchestration db. Confirmed: two VMs from one such snapshot emitted **identical `deviceToken` and
`pairedDeviceId`**. Snapshot **before** the runtime has ever run, or `rm -rf` the whole user-data dir
(`~/.config/orca` on Linux) first — deleting a named file list will drift as Orca adds state.
- Snapshot the stopped sandbox, parse the snapshot id, and write it + scope/project/port/repo to state.
---
@@ -163,6 +170,10 @@ their own terminal, or via the Claude Code harness bang-prefix (`! <cmd>`, with
`!`). You scaffold/boot the sandbox and run steps 34, but **you cannot observe the interactive login
finishing** — so **ask the user to tell you when it's done** before you verify and re-snapshot.
This layer inherits §3's rule: if you started `orca serve` on the base or auth sandbox to smoke-test it,
delete the runtime's user-data dir (`~/.config/orca` on Linux) before re-snapshotting, or every workspace
booted from this image shares one pairing identity and one `agent-session-authority.key`.
If the agent's credentials are short-lived, warn that the snapshot may need periodic re-auth (§10).
For disposable runtimes, do **not** treat a host agent config directory (for example `~/.codex`) as the
File diff suppressed because one or more lines are too long