Tutorial 1 · The counter¶

Goal: run a process whose value lives only in RAM, freeze it, thaw it, and watch the number continue — proof that Barista preserves memory across pause/resume, not just disk.

Prereq: the one-time setup (CLI + key + Docker).

Steps¶

Create a session whose workload counts up once a second, writing the current value to a file in its own RAM-backed filesystem:

barista create counter --image busybox:latest -- \
  sh -c 'i=0; while true; do i=$((i+1)); echo $i > /tmp/c; sleep 1; done'
# {"name": "counter", "status": "pending"}

(Explicit create because this session needs a custom workload command. When a template's default workload is fine, skip it — barista exec <name> … and attach create a missing session for you, and creating a name you already hold is refused rather than overwritten.)

Give the node a moment to materialise it, then confirm it's running and read the count:

barista status counter
# … "status": "running", "state": "running" …

barista exec counter -- cat /tmp/c
# 6

Create the counter session, confirm it is running, and read the count

Now freeze it, wait a few seconds, and thaw it:

barista pause counter        # {"name":"counter","status":"paused"}
barista resume counter       # {"name":"counter","status":"running"}

barista exec counter -- cat /tmp/c
# 9

The count came back 9, not reset to 1 — the process resumed from exactly where it froze.

Pause, resume, and read the count again — it continued instead of resetting

See the freeze/thaw as events¶

In another terminal, tail the node's event stream while you pause/resume:

barista events counter
# STATE_CHANGED · PAUSING
# OPERATION_PROGRESS · journal.snapshot
# STATE_CHANGED · PAUSED
# STATE_CHANGED · RESUMING
# RESTORED · restored: 32 bytes of entropy mixed; clock drift stepped
# STATE_CHANGED · RUNNING

The raw event stream across a pause/resume cycle, ending in RESTORED

That RESTORED line — entropy re-mixed, clock drift stepped — is the fingerprint of a real memory-snapshot restore. On a non-KVM runtime you'd instead see a DEGRADATION event ("paused without preserving memory: disk only") and the count would reset.

The same session, in the console¶

Everything above is also visible (and drivable) from the web console at /app/sessions/counter — spec, live lease, an exec box, and the event tail. This run had auto-paused after 5 idle minutes; the exec woke it and read the count, no explicit resume needed:

The console's session page: desired spec, live lease, and an exec that woke the auto-paused session

Clean up¶

barista rm counter

What happened¶

create wrote a desired-state record to the coordination bucket; the node reconciled it into a microVM. exec/pause/resume went over the node's Contract A. On the hypeman/KVM node, pause snapshots the VM's memory, so resume continues the exact running process. Next: put a real tool in the session — Claude Code.