Skip to main content
Templates work on v2, and the contract is unchanged. You define an environment once, give it a name, and start sandboxes from that name:
Same Image builder, same names, same list / get / delete. Your existing definitions carry over as written — what changes is how they are built underneath, and two consequences of that are visible to you.

​
1. Build ahead of time

A template is built into a machine image before any sandbox uses it, which takes minutes rather than seconds. So the build is a separate step from the create, and you wait for it once:
Passing image: directly to Sandbox.create() is refused on v2. A create that waited for a build would time out, so the error names the two-step path instead of returning a sandbox without your packages.

​
2. Sandboxes from a template cold-start

Standard sandboxes come from a warm pool. A sandbox built on your template does not, because the pool holds standard sandboxes — so expect a few seconds rather than milliseconds on create. Everything the template installed is already baked in, so this is paid at create, not on your first command.

​
What your definitions run on

The environment underneath is Amazon Linux 2023 on ARM64, so two things in an existing definition can need attention:

Package names

aptInstall works and common Debian names are translated — build-essential becomes gcc gcc-c++ make. A package that exists only on Debian fails the build, and the error names it.

Architecture

A step that downloads an x86-64 binary fails. Use your package manager, or fetch the aarch64 build.
Each org holds up to 10 templates at a time; delete one to make room. Two identical definitions share one build, so rebuilding an unchanged template returns immediately.

​
Templates built on v1

A template that carries a rootfs image cannot be used on v2. The create fails with “template … carries a rootfs image, which v2 cannot restore.”
v1 templates capture the whole disk. Replaying only part of that would hand you your files while dropping every system change the template existed for — a template that looks like it worked and hasn’t — so it refuses instead. Rebuilding is the fix, and usually means re-running the Image definition you already have.
1

Try each template

One that cannot be used fails loudly at create with the message above. That is the fastest audit — nothing to inspect.
2

Rebuild it

Create it again by name with the same definition, wait for the build, and point your creates at it.

Checkpoints

Save a running sandbox and restore it later.

Migrating from v1

Every behaviour that differs between v1 and v2.