Skip to main content
Upgrading the SDK is the migration. There is no ticket to file and no setting to change: v1 and v2 are chosen by the major version of the SDK you have installed. Install 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

Your API key and your existing sandboxes are unaffected. 1.1.0 is the floor only because the check below reads endAt, which was added there; any 1.x routes to v2.
If you asked us to pin your org to a runtime, the pin wins and the SDK version is ignored. That is deliberate: it stops one stale service in your fleet from quietly creating sandboxes on the other version. Ask us to remove the pin if you want version-based switching.

Verify the upgrade

A v2 sandbox carries endAt — 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.
Expect exactly this:
If you see 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:
1

A sandbox disappears after 8 hours

2

A restored checkpoint has your files but not your process

3

A create fails naming a template

Expected for templates built on v1. See Templates.

Rolling back

Reinstall the previous major. New sandboxes go back to v1 immediately; nothing needs to drain.
Sandboxes you already created on v2 keep running on v2 until they end. Rolling back does not move them, and it does not shorten their 8-hour lifetime.

Am I affected?

Seven questions. If every answer is “no”, upgrading is the whole migration.
1

Does any sandbox need to live longer than 8 hours?

v2 sandboxes have a hard 8-hour lifetime, counting hibernated time. See Sandbox lifetime.
2

Do you restore checkpoints expecting a running process?

v2 checkpoints capture the filesystem only. Restoring gives a fresh boot with your files, not a resumed process tree. See Checkpoints.
3

Do you use templates built on v1?

A template that carries a rootfs image is refused. Most v1 templates do. See Templates.
4

Do you run sandboxes larger than 8 GB?

The 16 GB tier does not exist in v2, and memory cannot change after launch.
5

Does any sandbox need more than ~16 GB of disk?

Disk is fixed at ~16 GB in v2, down from 20 GB, and diskMB is ignored.
6

Do you call scale, autoscale, or mount anything?

None of these exist in v2.
7

Do you build images or fork from checkpoints?

Image builds work, but only ahead of time — see Templates. Passing 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

A v2 sandbox is destroyed 8 hours after its host started, counting running and hibernated time. It cannot be extended, and the disk goes with it.
Read endAt 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 same Image definition under the same name. See Templates.

Sizes are fixed steps, and 16 GB is gone

Memory cannot be changed after launch. 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:
Check 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

Each of these is refused rather than silently ignored.
If something in your workload is blocked by the “in progress” items above, tell us. That list is prioritised work, not a fixed decision.
The v1 documentation stays accurate for 0.x and is archived permanently at docs-v1.opencomputer.dev.