1.x and your
new sandboxes run on v2. Go back to 0.x and they run on v1 again.
Existing sandboxes never move. The version decides where new sandboxes are created, so a
rollback is a reinstall, not a recovery.
Upgrade
1.1.0 is the floor only because the
check below reads endAt, which was added there; any 1.x routes to v2.
Verify the upgrade
A v2 sandbox carriesendAt — the hard deadline its host will be destroyed at. A v1 sandbox has
no such deadline and omits the field entirely. That single difference is the check.
version: v1 after upgrading, your org is pinned — see the note above.
Then run your own test suite
The genuine check is your code, unchanged, against v2. The SDK surface is identical, so your existing tests are the migration test. Point a non-production service at it for a day before moving anything that matters. The three failures worth watching for, because they are silent in a short test and obvious in a long one:A sandbox disappears after 8 hours
A restored checkpoint has your files but not your process
A create fails naming a template
Rolling back
Reinstall the previous major. New sandboxes go back to v1 immediately; nothing needs to drain.Am I affected?
Seven questions. If every answer is “no”, upgrading is the whole migration.Does any sandbox need to live longer than 8 hours?
Do you restore checkpoints expecting a running process?
Do you use templates built on v1?
Do you run sandboxes larger than 8 GB?
Does any sandbox need more than ~16 GB of disk?
diskMB is ignored.Do you call scale, autoscale, or mount anything?
Do you build images or fork from checkpoints?
image: directly to a create is refused. Fork is unavailable today and being
worked on.Finding the calls in your code
The breaking changes
Sandboxes end after 8 hours
ReadendAt rather than computing a deadline — sandboxes come from a warm pool, so the host
often started before your create did:
endAt is on the sandbox from create() and from connect(). It is undefined on v1.
Work that assumed a long-lived sandbox needs to checkpoint and roll over, or keep its state
outside the sandbox.
Checkpoints are filesystem-only
v1 captures disk and memory. v2 captures the filesystem. Restoring gives you a freshly booted sandbox with your files in place. If your checkpoints capture an installed environment, nothing changes. If they capture a warmed process — a loaded model, an open connection pool — that state is gone on restore.kind: "full" is refused rather than silently producing a disk-only checkpoint.
Templates built on v1 are refused
A v1 template captures the whole disk. v2 can only replay the workspace half, and doing that silently would hand you your files while dropping every system change the template existed for. So it refuses, loudly, at create. Rebuild them on v2 — usually by re-running the sameImage definition under the same name.
See Templates.
Sizes are fixed steps, and 16 GB is gone
cpuCount and diskMB are accepted for compatibility
but are not controls in v2 — CPU follows memory, and disk is fixed at ~16 GB.
Hibernation suspends rather than parks
v1 hibernation writes a checkpoint and releases the host, so a sandbox can stay hibernated indefinitely. v2 suspends in place, and that time still counts against the 8-hour lifetime. A sandbox hibernated overnight will not be there in the morning.Idle timeouts are clamped
A timeout longer than the remaining lifetime cannot fire, so v2 reports what it applied instead of accepting it:applied.
Secrets: same model, one difference
Sealed placeholders, host-scoped substitution, fail-closed bypass and restart-free rotation all work exactly as in v1, and your code does not change. The difference is where the real values are held: in v2 the substituting proxy runs inside your sandbox as a root-owned process, rather than outside it. Your code runs unprivileged and cannot read them, but a privilege escalation inside a sandbox now reaches the secrets scoped to that sandbox. See Secrets.Not available in v2
0.x and is archived permanently at
docs-v1.opencomputer.dev.