Concepts

Tenki Sandbox is built around four primitives. Most workflows combine two or three of them.

Primitive	What it is	Lifetime
Session	A running Linux microVM	Until you terminate it
Volume	Workspace-scoped persistent block storage	Across sessions
Snapshot	A point-in-time capture of one session's VM state	Until deleted or expired
Template	A reusable environment recipe + its golden snapshot	Until deleted

The mental model is simple:

• VM state belongs in snapshots and templates.
• Durable data belongs in volumes.
• Live compute is a session.

Sessions

A session is the main unit you work with. It is an isolated Linux VM with:

• CPU and memory allocation
• inbound and outbound network policy
• metadata and environment variables
• optional attached volumes
• optional SSH authorized keys

Lifecycle states

The public lifecycle states surfaced today:

• CREATING
• READY
• RUNNING
• PAUSED
• TERMINATING
• TERMINATED

For day-to-day usage:

• READY means you can start working
• RUNNING is also treated as usable
• TERMINATED is final

Resource limits

Current request validation for session creation:

• cpu_cores: 1..16
• memory_mb: 512..65536

If you don't specify, sessions default to 2 vCPU, 4096 MB, outbound network on, inbound network off.

See Sessions for the full lifecycle, exec, files, ports, and SSH.

Persistent volumes

A volume is workspace-scoped block storage that survives session termination. Use volumes for:

• package and build caches
• large repositories
• datasets
• durable working data shared across sessions

A few rules to keep in mind:

• volumes are separate from the VM root disk
• volumes must be attached explicitly at create time or via attach
• restoring a snapshot or template does not automatically re-attach prior session volumes

Current size validation: 1 MiB minimum, 100 GiB maximum.

See Volumes for the full API.

Snapshots

A snapshot is a restorable VM capture of one session, including disk and memory state. Use a snapshot when:

• you want to preserve the exact state of one session
• the saved state is user-specific or temporary
• you want a fast restore point

Don't use a snapshot when:

• you want a team-wide reusable environment
• you want a declarative environment that can be rebuilt intentionally

For those cases, use a template.

Snapshot states: CREATING, READY, FAILED, DELETING, DELETED.

See Snapshots for the workflow.

Templates

A template is a workspace-scoped environment recipe:

• name
• base_image_id (default: sandbox)
• setup_script
• optional start_cmd
• optional environment variables
• optional default CPU and memory

A template record is not itself bootable. You build it first. A build:

1. boots an internal build session
2. runs the template setup_script
3. optionally starts start_cmd
4. captures a VM snapshot
5. marks the build READY

Creating a session from a template restores from the latest READY build. Build states: PENDING, BUILDING, READY, FAILED.

Use templates when you want:

• pre-installed toolchains
• prepared repos or working directories
• background processes already started
• repeatable onboarding or dev boxes
• many similar sessions from one prepared environment

See Templates for the full lifecycle.

Choosing the right primitive

You want…	Reach for…
An ephemeral VM for a single task	Session
Data that outlives the VM	Volume
Exact restore of one VM state	Snapshot
Repeatable, declarative team environment	Template