Concepts

Tenki Sandbox is built around three primitives. Most workflows combine two 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

The mental model is simple:

• VM state belongs in snapshots.
• 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 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

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

See Snapshots for the workflow.

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