Sessions

A session is the unit of everything in Barista Cloud: a named, long-lived workload built from a digest-pinned OCI image, owned by your tenant, that pauses with its memory and wakes on demand.

Identity

Sessions have stable names, unique within your tenant (agent1, web, cc-review). The name is how every surface addresses it — CLI verbs, SDK handles, MCP tools, the console, and (if published) its public URL slug. Exactly one node owns a name at a time; deleting a session frees the name.

Resources: named sizes

Create picks a fixed resource shape by name:

size	vCPU	memory
small (default)	1	512 MiB
medium	2	2 GiB
large	4	8 GiB

The reserved shape is visible in session detail and in the console.

Idle pause and waking

Every session carries an idle timeout — your plan's default, overridable per session (--idle-pause SECONDS / idle_pause_s), with 0 meaning never. An idle session is parked: memory captured, compute released. Waking is transparent — the next exec/attach, a request to its published URL, or an explicit resume restores the same live process with a moment of added latency. Requests also absorb readiness: an exec against a session that is still booting or waking is held (up to ~60 s, tunable via ready_timeout_s) instead of erroring. See How it works for the mechanics.

One state word

Every surface reports a session as exactly one of four states, and running means ready (the guest is reachable):

state	meaning
starting	materialising, booting, or waking
running	awake and ready for exec/attach
parked	memory captured, zero compute — costs storage only
failed	the instance failed; delete frees the name

Metadata

Sessions take free-form key/value metadata at create (--meta team=ml, up to 16 pairs; the barista. key prefix is reserved). It shows in session detail and filters the list: barista ls --meta team=ml, or GET /v1/sessions?meta=team=ml — every given pair must match. Use it to tag sessions by owner, task, or experiment when names stop scaling.

Lifecycle at a glance

exec/attach a name ──▶ starting ──▶ running ──▶ (idle) parked
    (created if missing)               ▲              │
                                       └── wake ◀─────┘   delete frees the name

The happy path is one idempotent operation addressed by name: barista attach mybox (or exec) creates the session if it doesn't exist — from --template <name>, or the platform default — wakes it if parked, and proceeds. Explicit create/pause/resume remain as plumbing for callers that want each step; parking happens by policy, waking by intent. The counter tutorial shows the whole loop in two minutes.