Concepts

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

Primitive	What it is	Lifetime
Session	A running full Linux VM	Until you pause or terminate it
Volume	Workspace-scoped persistent block storage	Across sessions
Snapshot	A point-in-time capture of one session's VM state (disk and memory)	Until deleted or expired
Template	A named, reusable definition of a prepared environment	Until deleted
Image	The session source a template build produces, addressed by a digest	Until deleted from the registry

Sessions

A session is an isolated Linux VM, and the main thing you drive in Tenki Sandbox. You control its CPU and memory, network access, and environment, and can attach volumes and SSH keys. Every session starts from the same base image, with common runtimes and tools already installed.

Lifecycle

You create a session, it enters a running state, and from there you can:

• Snapshot it to capture its state and start new sessions from it later. The session briefly pauses, then keeps running.
• Pause it to free compute while preserving files and memory, then resume later. A paused session stops accruing metered charges, and its preserved state counts against your workspace storage quota.
• Terminate it to release all resources. A terminated session cannot be resumed.

The public lifecycle states are CREATING, RUNNING, PAUSED, TERMINATING, and TERMINATED. A session is ready to use once it reaches RUNNING; TERMINATED is final.

See Sessions for exec, files, ports, and SSH, and the SDK reference for resource limits.

Persistent volumes

A volume is workspace-scoped block storage that you attach to a session and keep after the session ends. Reach for one when data needs to outlive a single VM:

• package and build caches
• large repositories
• datasets shared across sessions

A volume lives separately from the VM root disk, and it is never attached automatically; you attach it explicitly, at create time or later.

See Volumes for the full API.

Snapshots

A snapshot captures both a session's disk and memory, so a restored session comes back with its running processes and in-memory state intact, not just its files.

A snapshot is one-to-many: you can start many new sessions from the same snapshot. Reach for one when:

• you want to preserve the exact state of a session
• you want a fast restore point
• you want to fork a running environment

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

Snapshot vs pause/resume

Both hold on to a session's state, but they solve different problems:

	Pause / resume	Snapshot
The original session	Pauses (stops) the session	Session briefly pauses, then keeps running
How many you get	One-to-one: resume restores the same session	One-to-many: one snapshot starts many
When to use it	Set a session aside and pick it back up later	Create a reusable checkpoint

See Snapshots for the workflow.

Templates

A template is a typed recipe for a prepared environment, so every session can start from the same known state. You declare a base image, a Git context to fetch, ordered build steps, runtime behavior, and default resources. Tenki builds the template by fetching the context, running the steps, and capturing the result.

A successful build automatically registers a private image, addressed by a content digest, and you create sessions from its reference, like myworkspace/my-node-env. Publishing to change an image's visibility or share it across workspaces is a separate, optional step. Every session you create from the image starts from that prepared state, so you skip the install-and-warm-up step each time. See Templates for the full workflow.

Snapshots vs templates

Both give you a reusable starting point, but they are not the same:

	Template	Snapshot
How it's created	Declared before any session exists	Captured from a running session
What you get	Produces the same environment every time	Captures whatever state existed at the moment
When to use it	Repeatable environments	Checkpointing, rollback, forking

A snapshot is a low-level captured state; a template is the reusable recipe. Building a template runs your configuration and registers the result as a private image (backed by a snapshot), so every session from that image starts from the same place. Use templates when every session should start from an identical, known environment; use snapshots when you need to capture or fork live state that depends on what happened during a run.

Choosing the right primitive

You want…	Reach for…
An ephemeral VM for a single task	Session
Data that outlives the VM	Volume
An exact restore of one VM's state	Snapshot
Every session to start from an identical, prepared environment	Template