# snowglobe
> snowglobe runs a Docker image where Docker isn't. It turns the image into a folder of static
> files (GitHub Pages works; no server runs the program) that opens in a browser tab, runs from
> one binary with no Docker, daemon, root or KVM, or serves as a sandbox that agents and job
> runners drive. It starts in about a second: the site is a snapshot taken once the app was
> ready. Under it is real Linux on a 64-bit ARM CPU emulated in WebAssembly (armless), so
> guests must be arm64 Alpine images (FROM alpine, built for arm64, or FROM arm64v8/alpine) and
> run slower than native.
Live demos: https://filipecabaco.github.io/snowglobe/ (Supabase, Elixir IEx, PostgreSQL,
Elixir + Postgres, Python + Rich, TypeScript + Zod, Go + Bubble Tea, Rust + clap, Java + Gson,
curl + jq, DuckDB). Docs: https://filipecabaco.github.io/snowglobe/docs/ (guides and the full CLI
reference). Source: https://github.com/filipecabaco/snowglobe
Install: a release binary (Linux x86-64 or arm64, macOS on Apple silicon; one file that carries
its own snowglobe-vm, unpacked into the cache on first native use) from
https://github.com/filipecabaco/snowglobe/releases, or
`curl -fsSL https://filipecabaco.github.io/snowglobe/install.sh | sh` (checks the release's
SHA256SUMS, installs to ~/.local/bin; `SNOWGLOBE_VERSION`, `SNOWGLOBE_INSTALL_DIR`), or
`go install github.com/filipecabaco/snowglobe/cmd/snowglobe@latest`.
## Commands
- `snowglobe build
[flags]` builds the site
into `--out` (default `dist`). With Docker by default; `--builder native` (or
`SNOWGLOBE_BUILDER=native`) needs no Docker: it pulls the image from its registry (Docker Hub,
GHCR, any registry serving public images) or reads a `docker save` / OCI layout archive.
- `snowglobe serve [dir] [--port N]` previews a built site on localhost.
- `snowglobe pool ` makes every site under a directory share one content-addressed blob store.
- `snowglobe pwa [--name N] [--short-name N]` makes a built site an installable Progressive
Web App that works offline once it has run. Run it after `pool`.
- `snowglobe agent-pages ` puts every `--agent` site under a directory on the agent page,
`/agent/` (its `runtimes.json`, scripts and service worker; the page is the demo site's
`site/templates/agent.html.eex`). Sites built from the same source are one machine (the one named after
it). Run it after `pool` and `pwa`.
- `snowglobe pack [-o site.tar.gz]` writes a site as one self-contained tarball (.tar.gz or
.tar.zst, pooled blobs included) to publish on a CDN.
- `snowglobe run [site] [--name N] [--detach] [--runtime docker|native]` restores a built site
headlessly. `docker` (the default) is a sandboxed container (unprivileged, read-only,
memory-capped, offline unless built with a network); `native` (or `SNOWGLOBE_RUNTIME=native`, and
whenever there is no Docker) runs snowglobe-vm here, which sandboxes itself: no_new_privs,
Landlock and seccomp on Linux, Seatbelt on macOS. In a terminal it is an interactive session
(ctrl-] quits); with stdin piped, each line is typed in as a command and the output printed as
plain text. The site can be a directory, a tarball, a tarball URL, or a deployed site's URL
(e.g. https://filipecabaco.github.io/snowglobe/python/), fetched into a local cache first.
Native instances of one site share its snapshot's memory: the first writes it to an image in
the cache (`ram/`, one per snapshot, named by its hash) and every instance maps it
copy-on-write, so pages no instance writes are held once and a restore takes a few
milliseconds (Linux: ~46 MB PSS per Python instance instead of ~111 MB).
`SNOWGLOBE_RAM_IMAGE=off` restores into memory of the instance's own.
- `-p HOST:GUEST` (repeatable) forwards a host port to a guest port (127.0.0.1 unless
IP:HOST:GUEST); needs a site built with `--network fetch`.
- `--max-runtime DURATION` ends the run after that long (exit 124); `--stop-file PATH` ends it
once PATH exists (exit 143). Either way the job running in the guest is killed first.
- `--log-dir DIR` keeps durable logs: `console.log` (the app's terminal), `serial.log` (kernel
messages, the job shell) and `events.jsonl` (start, restored, job_start, job_end, stop; one
JSON object a line). Named native instances log to the user cache's `snowglobe/logs/`.
- `--tunnel [HOST:]PORT=URL`, `--tunnel-token URL`, `--allow-private`, `--record-reads FILE`.
- `--fork` (with `--detach --name`, native) makes the instance a template: it restores once,
and every `snowglobe sh` on it runs in a fresh copy of the machine, forked in milliseconds and
sharing its memory. Nothing one command does is seen by the next; `sh` is all it takes.
- `snowglobe exec ` types one command into a running instance's app and prints
only what it printed (plain text when piped): the way to drive a REPL.
- `snowglobe sh [--json] [--timeout SECS] ''` runs a shell command, passed as one
quoted argument (its own flags would otherwise be read as snowglobe's), on a native
instance's serial root shell, whatever its app is, with the app's environment, starting in the
home directory (`$EXCLAVE_WORKSPACE` is a scratch directory of its own): its output and
exit status (`{"exit", "output", "timed_out", "killed"}` with `--json`). Out of time (default
300 s), the command and everything it started are killed (exit 124).
- `snowglobe cp ` copies files or directories in or out of a native instance
(`name:/path` on one side).
- `snowglobe mcp [--name N] [--keep] [--log-dir DIR]` serves a site to an agent as an
MCP server over stdio: an isolated Linux machine with `run_command` (with `timeout_seconds`),
`write_file` and `read_file`. No Docker, KVM or privileges. Example:
`claude mcp add sandbox -- snowglobe mcp https://filipecabaco.github.io/snowglobe/python/`
- `snowglobe mcp --daemon` serves the daemon to an agent over MCP (stdio): `status`,
`list_templates`, `add_template`, `remove_template`, `list_machines`, `up`, `stop_machine`,
`run_command` (on a `machine`, a fresh fork of a `template`, or a `service`'s replica),
`write_file`, `read_file`, `snapshot_machine`, `list_snapshots`, `remove_snapshot`,
`list_services`, `add_service`, `remove_service`, `heal_service`, `set_health`, `list_supervisors`,
`add_supervisor`, `restart_supervisor`, `remove_supervisor`, `build` (waits by default), `build_status`,
`list_builds`, `cancel_build`, `submit_run`, `run_status` (`wait_seconds`), `list_runs`,
`list_ports`, `check_port`, `recent_events`, `fleet_diff`, `fleet_plan`, `fleet_apply` (one
`step` too), `graph`, `list_links`, `link`, `unlink`, and fleets kept like compose projects:
`list_fleets`, `add_fleet`, `write_fleet`, `read_fleet`, `apply_fleet`, `start_instance`,
`stop_instance`, `forget_fleet`. Example:
`claude mcp add snowglobe -- snowglobe mcp --daemon`
- `snowglobe bundle [-o FILE] [--target linux|darwin] [--runtime snowglobe-vm]`
makes a site one executable (snowglobe-vm with the site appended) that takes `run`'s flags, plus
one-shot jobs: `--workspace DIR --cmd COMMAND [--env K=V] [--env-file JSON] [--timeout SECS]`
writes DIR into a fresh machine, runs the command, and returns its output, exit status and
`out/`. `--serve SOCKET --jobs-root DIR` restores once and forks per job; `--server SOCKET` is
its client. A job's limits, each a flag and the same request field (per fork with `--serve`):
`--disk-limit MB` (`disk_limit_mb`, ENOSPC past it), `--max-rss MB` (`max_rss_mb`, exit 137),
`--memory-limit MB` / `--cpus-limit N` / `--pids-limit N` (`memory_limit_mb`, `cpus_limit`,
`pids_limit`: a guest cgroup v2, ending what the job left running; guest OOM is 137; the memory
limit needs a site built with `--memory-limits`), `--cpu-time S` (`cpu_time_s`, exit 152),
`--output-limit BYTES` (`output_limit`, exit 153), `--copy-limit MB` (`copy_limit_mb`, default
2048), `--read-only-in` (`read_only_in`), `--egress none|https|internet|private` (`egress`).
`--status-file PATH` writes `{status, exit, timed_out, killed, oom, output_truncated, disk_full,
cpu_time_exceeded, out_truncated, ms}`; a server's answer has the same fields. A forked job is
confined to its own workspace, connects to no Unix socket, writes nothing its server shares (the
JIT profile is read only; the server's `--log-dir` is closed in each job and holds the server's
own events, and its stdout/stderr go to /dev/null in each job), and is cancelled when its client disconnects. macOS (Seatbelt) is for development;
run other people's jobs on Linux.
- `snowglobe daemon [--listen ADDR --token-file F] [--detach]` is the orchestrator: it keeps templates (a
site restored once) and machines forked from them, with an HTTP/JSON API on a Unix socket in the
user cache (`/v1/templates`, `/v1/machines`, `/v1/machines/{name}/jobs`,
`/v1/templates/{name}/jobs` for a job on a fresh fork), and over TCP for requests bearing the
token with `--listen`. `SNOWGLOBE_DAEMON=http://HOST:PORT` and `SNOWGLOBE_DAEMON_TOKEN` point
the CLI at a remote one. Nothing it starts outlives it: stopped (ctrl-c, SIGTERM, `snowglobe
daemon stop`; a second ctrl-c skips the grace), it stops its template servers, machines and builds; killed outright, they stop
themselves (each holds a lifeline to it). Started again, it restores its templates from their
sites and starts its services' replicas; machines are not brought back.
A job (`POST /v1/templates/{name}/jobs`, `/v1/machines/{name}/jobs`, `/v1/services/{name}/jobs`)
is `{"files": {path: base64}, "cmd", "env", "timeout", "workdir", "memory_limit_mb",
"cpus_limit", "pids_limit", "disk_limit_mb", "max_rss_mb", "cpu_time_s", "output_limit",
"copy_limit_mb", "egress": "none|https|internet|private", "read_only_in", "labels"}` (all but
`cmd` optional) and answers `{"status", "output", "out", "timed_out", "cancelled", "killed",
"ms", "oom", "disk_full", "output_truncated", "cpu_time_exceeded", "out_truncated"}`. `workdir`
runs it in an absolute guest path (its files copied there, out/ read from there: only what it
wrote). A limit the machine can't enforce is answered 200 with `"error"` (non-2xx is for the
API: 400, 404, 429 when the memory budget refuses it). The client disconnecting cancels the job
and frees its fork. A job on a machine has the machine's egress (`POST /v1/machines
{"template", "name", "labels", "ttl", "egress"}`); each machine gets a directory of its own under
its template's jobs root, all of the root it can touch. `GET /v1/templates?label=k=v` and `GET
/v1/snapshots?label=k=v` filter; both report `size_bytes`. Labelled jobs end with a `job.ended`
event carrying their labels. The full contract: docs/design/exclave-contract.md in the repo.
It builds too: `POST /v1/builds {"name","source"|"dockerfile"|"context","network","memory_mb",
"cpus","kernel","builder","memory_limits","no_template","artifact"}` runs `snowglobe build` (a directory by its
full path, an image reference, a Dockerfile's text, or a context uploaded with `POST
/v1/contexts` (a tar, `?format=zst|gz`; answers `{"context","digest","bytes","files"}`); Docker
when there, else natively for images) and makes the site a template; `"kernel": "linux"|"none"`;
`"artifact": true` packs the site for the page instead (no template), cached by the input's
digest and the options: a second request answers the same build with `"cached": true`, or joins
the one running. `GET /v1/builds/{id}/artifact[?format=gz]` downloads it (.tar.zst, or .tar.gz;
ETag and Digest are its sha256, Cache-Control immutable, ranges served); `GET /v1/builds`,
`/v1/builds/{id}`, `/v1/builds/{id}/log?follow=1&offset=N`, `DELETE /v1/builds/{id}` (cancels, or
removes a finished one). `GET /v1/version` says the daemon's version, mode and features. A machine's terminal is a WebSocket
at `/v1/machines/{name}/attach?rows=R&cols=C`. `/v1/metrics?since=MS` is a sample every 5 s for
an hour (memory, machines, replicas, jobs, latencies) and totals; `/metrics` is Prometheus text.
- `snowglobe daemon --mode provider [--cache-size 20G] [--build-timeout 30m] [--max-context 1G]
[--max-artifact 8G]` is a template provider: it only builds (images, Dockerfiles, uploaded
contexts) into sites for the page, packed, with no kernel unless a request asks for linux; every
other route answers 404 `{"error": "the daemon runs in provider mode: builds only", "mode":
"provider"}`, on the socket and on `--listen` alike (health, version, stats, shutdown stay).
`snowglobe provide [--kernel none|linux] [--network fetch]
[--cpus N] [--memory MB] [-o site.tar.zst]` builds on such a daemon (or a full one), streams the
log, downloads the artifact and prints its size and sha256. The artifact is a static site for
any host or CDN, at any path.
- `snowglobe template add [--name T] [--max-machines N] [--idle 30m]`, `template ls`,
`template rm T` (removes its machines too). `--idle` stops the template's server after that long
with no machine; the next `up` or job restores it (about a second). `--warm CMD` (repeatable,
`--warm-runs N`, default 3; `warm`/`warm_runs` in the API and on `/v1/builds`) runs CMD on the
site N times as one-shot runs first, so the JIT profile its server compiles before forking (and
its jobs only read) has that code: the profile learns from those trusted runs only.
- `snowglobe daemon --memory 8G [--wait 30s]` caps what templates and machines take together: a
machine that doesn't fit waits for room, then is refused (429) with the reason. `up --ttl 1h`
stops a machine after that long.
- `snowglobe up [--name N] [-p [IP:][HOST:]GUEST]... [--label K=V]...` forks a machine
in tens of milliseconds, sharing the template's memory: it lasts until stopped, keeps what it
writes, and the daemon forwards its ports (-p 8000 picks a host port). `sh`, `cp`, `exec`,
`attach`, `ps` and `stop` reach the daemon's machines like instances.
- `snowglobe snapshot save [--name S]` saves a machine whole (memory, running processes,
the files it wrote); `up --snapshot S` starts a machine from it, and
`template add --snapshot S [--name T]` makes it a template, every machine of which starts there.
`snapshot ls`, `snapshot rm S`.
- `snowglobe service add --template T [-p [IP:]HOST:GUEST]... [--min 0] [--max 1]
[--idle 5m] [--concurrency 10] [--state discard|keep]` puts a template's machines behind host
ports the daemon holds: each connection (or `sh `) goes to a replica started on demand.
`--min 0` scales to zero: replicas idle for `--idle` stop, and the next request forks one (about
20 ms to the first answer when the template is a snapshot with its server listening).
`--state keep` saves the replica before it stops and the next one carries on (max 1);
`discard` starts each from the template. `service ls`, `service rm `, `service heal `; API
`/v1/services`, `/v1/services/{name}/jobs`, `POST /v1/services/{name}/heal`.
A health check on each running replica: `--health-http PORT[/PATH]` (a GET whose status must be in
`--health-status`, 200-399 by default) or `--health-cmd CMD` (exit 0), every `--health-interval`
(10s), unhealthy after `--health-failures` (3) in a row once `--health-grace` (30s) is over.
`--heal replace` (the default) takes it out of service, gives connections `--drain` (30s) and
stops it unsaved (another starts at once below `--min`, else on the next use); `drain` takes it
out of service and keeps it until idle; `hook` runs `--heal-cmd` in the guest first; `none` only
reports. Whatever the strategy, an unhealthy replica gets a connection only when no other can (below
`--max` and not degraded, a new replica starts instead). Checks never wake a service at zero nor
count as use; heals back off and stop after 5 in a row (degraded) until a replica passes or
`service heal ` starts them over. `--wait-ready` holds a new replica's first connection until it passes. Each
replica's `health` (state, failures, last result) and the service's `service_health` are in
`/v1/services` (`inherited_health` when the check is its template's, `supervisor` when it has one).
Machines and templates take the same flags: `up --health-*` checks a machine (heal `none`, the
default, or `hook`: a machine is restarted only by a supervisor; its state is `checks` in
`/v1/machines`), and `template add --health-*` is the check its services and machines take when
they have none of their own. `snowglobe health service|machine|template [--health-* |
--none]` changes one in place, restarting nothing: `PUT /v1/{services,machines,templates}/{name}/health
{"health": {...} | null}`.
- `snowglobe supervisor add --child KIND/NAME[:RESTART]... [--strategy S] [--max-restarts N]
[--max-seconds D]`, `supervisor ls`, `supervisor restart `, `supervisor rm `: an Elixir
style supervisor over services, machines and supervisors, in order. A child fails when its health
check makes it (or a service's replica) unhealthy, or its process ends unasked. `one_for_one` (the
default) restarts that child (a service: its failed replica), `one_for_all` every child,
`rest_for_one` that child and those after it; stopped in reverse order, started in order. A
machine starts again as it was (name, ports, labels, snapshot, links, what is left of its ttl); a
service's running replicas are replaced, as many as ran. Restart types: `permanent` (default),
`transient` (restarted when it fails a check, not when its process ends), `temporary` (never, and
restarts nothing else). More than `max_restarts` (3) in `max_seconds` (60s) and it fails itself:
its parent decides, or (top level) it is `degraded` until `supervisor restart`. A supervised
service's own `heal` isn't used. API: `/v1/supervisors` (GET, POST `{name, strategy, children:
[{kind, name, restart}], max_restarts, max_seconds}`), `GET/PUT/DELETE /v1/supervisors/{name}`,
`POST /v1/supervisors/{name}/restart`.
- `snowglobe daemon --detach` starts the daemon in the background, in a session of its own so it
outlives the terminal, its log in `daemon.log` beside the socket; it returns once the daemon
answers, and does nothing if one runs. `snowglobe daemon stop` stops it, and everything it
started, and returns once they have stopped.
- `snowglobe ui [--port 7777] [--no-open] [--start-daemon]` serves the daemon in a browser on 127.0.0.1
(the link carries a session token; `--start-daemon` starts a detached daemon first when none runs),
one view at a time: Overview (the last hour on one time axis, a lane per template with machine
lifespans), Network (the plan's templates and links dotted, then a group per fleet instance with its
machines, solid edges where one really reaches another by name, and each host port it opens; drag
one node onto another to link them), Fleets (each fleet file, its instances, its plan as steps that
each apply on their own, and an editor for the file), Machines (one control per task, and the
templates, machines, services, ports and snapshots), Run (a command on a fresh fork) and Builds. A
terminal on any machine is ghostty-web over `/v1/machines/{name}/attach`. The page is Preact + htm,
served gzipped from inside the binary, with no build step.
- Links: nothing joins the daemon's machines but a link. `POST /v1/links {"from","to","port","as",
"as_port"}` lets a machine, or every machine of a template, reach a machine, a service (one of its
replicas, started if none runs) or a template's machines as `as:as_port`; `GET /v1/links`,
`DELETE /v1/links/{name}`. Each source machine gets a Unix socket of its own per link (mode 0600,
in its template's socket directory), so no TCP port opens on the host, and links work under egress
`none`. The machine doesn't connect to that socket (its sandbox reaches no Unix socket): it asks
the daemon for each connection, which the daemon opens and hands over. `GET /v1/graph` returns nodes (templates, services, machines, ports, snapshots, with fleet
and instance) and edges (fork, replica, serves, link, reach, port, saved, made). MCP: `graph`,
`list_links`, `link`, `unlink`.
- `snowglobe submit '' [--timeout S] [--env K=V]...` is fire and forget: the
command runs once on a fresh fork, thrown away after, and the run's id is printed at once.
`snowglobe runs [ [--wait]] [--json]` lists runs or shows one's output and exit status
(`--wait` exits with it). API: `POST /v1/runs {"template","cmd","env","timeout"}`,
`GET /v1/runs`, `GET /v1/runs/{id}`.
- `snowglobe ports [--json]` lists the host ports the daemon holds and where each leads (machine
or service, guest port, open or at zero); `snowglobe ports check [--ip IP]` says whether
one is free or what holds it (exit 1 when taken). API: `/v1/ports`, `/v1/ports/check?port=N`.
- `snowglobe events [--json] [--after SEQ]` streams the daemon's events (kind, subject, message:
machine.up, machine.stopped, machine.expired, service.replica_up, service.replica_unhealthy,
service.replica_replaced, service.degraded, service.heal_reset, machine.unhealthy,
supervisor.restarted, supervisor.escalated, supervisor.degraded, template.asleep,
template.awake, snapshot.saved, admission.refused, ...), the last 200 first; `snowglobe top
[--once]` shows it live (memory and budget, templates, services, machines, recent events). API:
`/v1/events` (server-sent events, `?after=SEQ`), `/v1/stats`.
- Randomness after a restore: the guest kernel is reseeded at every restore (a new VM generation id),
so `/dev/urandom`, `getrandom` and processes started after it draw their own. A process already
running when a machine was saved is copied with its random state into every machine of it (Node's
`Math.random`, `crypto.randomBytes`, `randomUUID`; Erlang's `:crypto`; Python's `random`): the same
tokens, keys and ids in each. Start servers in a template's `start` (`snowglobe template add --start
CMD`, the fleet file's `start`), not in a snapshot's `run`; `apply` warns when a snapshot's commands
leave a process running (not one the site's own processes started, as Postgres its backends). A site whose image runs its server before it is built (its Dockerfile's command, held running by its snapshot): `restart_app = true` on the template (`snowglobe template add --restart-app`) starts the site's app again in each machine as it comes up, after its links and before `start`, handed over once it prints the site's ready text (100 s, or the machine goes); or restart it yourself in `start`.
- `snowglobe apply [-f snowglobe.toml]` gets the daemon to what a fleet file says (`name` = the fleet's
name, default its directory's): `[templates.N]`
(`site`, or `build` = a Dockerfile directory built first with optional `network`, or `snapshot`;
`idle`, `max_machines`, `allow_private`, `egress` = none (the default) | internet | private, `expose` = guest ports
the others reach under mode all, `start` = commands each of its machines runs as it comes up, after its
links and before it is used, each a string or `{ cmd, timeout }` (2m) that must succeed or the machine
goes, `restart_app` = true to start the site's app again in each machine first), `[network]` (`mode` = exclusive (the default: each instance
reaches only its own machines) | inclusive (every machine of a template reaches the target's
template's, across instances) | all (as inclusive, plus every template reaches every other's
`expose`d ports by its name)), `[links.N]` (`from`, `to` = a template, service or machine of the
file, `port`, `as`, `as_port`), `[snapshots.N]` (`template`, `run` = commands that must succeed, each a
string or `{ cmd, timeout }` for a time limit of its own, `ready` = a command retried until it
succeeds, `timeout` = each command's limit when it has none (10m) and how long `ready` is retried
(2m)), `[services.N]` (`template`, `ports`, `min`,
`max`, `idle`, `concurrency`, `state`, `labels`, and `[services.N.health]`: `cmd` or
`[services.N.health.http]` (`port`, `path`, `status`), `interval`, `timeout`, `failures`, `grace`,
`heal` = replace | drain | hook | none, `heal_cmd`, `drain`, `wait_ready`), `[machines.N]` (`template`, `count`, `ports`,
`ttl`, `labels`, `[machines.N.health]` healed by none or hook), `[templates.N.health]` (what its
services and machines without one take), `[supervisors.N]` (`strategy`, `children` = names of the
file's services, machines and supervisors in order, `max_restarts`, `max_seconds`, `labels`,
`[supervisors.N.restart]` = a child's name = permanent | transient | temporary). What changed is
replaced with what is made from it, but a health check, which is changed in place (`* service
web (health check, in place)`); what left the file is removed. `snowglobe diff` shows the plan; `snowglobe down [-f F | --name FLEET]` removes it all.
Examples: examples/fleet/snowglobe.toml, examples/todo-fleet/snowglobe.toml (an Elixir app and
Postgres, linked as db.internal:5432, egress none).
- Fleets as compose projects: the daemon keeps a list of fleet files. `GET/POST /v1/fleets` (POST
`{"file"}` adds one where it is; `{"name","text"}` writes a new one, checked before it is saved),
`GET/PUT/DELETE /v1/fleets/{name}` (GET plans it, `?instance=ID`; DELETE `?down=1` removes what it
made first), `POST /v1/fleets/{name}/apply {"instance","step"}` (all of the plan, or one step by its
key once the steps it waits on are done), `POST /v1/fleets/{name}/down`. A fleet runs as
instances, like `docker compose -p`: templates and snapshots are shared, services, machines and
links are made per instance (label `snowglobe.instance`); `main` keeps the file's names, another
gets `-ID` names and host ports the system picks. `POST /v1/fleets/{name}/instances {"instance"}`
starts one, `DELETE /v1/fleets/{name}/instances/{id}` removes it.
- `snowglobe attach ` joins a running instance (ctrl-] detaches); `snowglobe ps` lists them;
`snowglobe stop ` stops one (natively: through its stop file, killing its job and logging
why).
- `snowglobe warm ` adds the files runs recorded to the site's warm pack.
- `snowglobe tools` builds or finds the tools image; `snowglobe version`.
## Build flags (and the image labels they override)
- `--cmd CMD`: the program to run (default: the image's ENTRYPOINT + CMD). Drops the image's ready and exercise labels.
- `--ready TEXT` / `snowglobe.ready`: snapshot once this text appears on the console (default: after 5 s of quiet).
- `--title TEXT` / `snowglobe.title`: the page title.
- `--memory MB` / `snowglobe.memory`: guest RAM (default 512).
- `--cpus N` / `snowglobe.cpus`: guest CPUs, 1 to 8 (default 1); each runs in a Web Worker.
- `--exercise CMD` (repeatable) / `snowglobe.exercise` (JSON array): commands typed after the snapshot; the files they read are preloaded.
- `--warm REGEX` / `snowglobe.warm`: extra guest paths to preload.
- `--network fetch` / `snowglobe.network`: give the guest a network (default `none`).
- `--tunnel [HOST:]PORT=URL` (repeatable) / `snowglobe.tunnels`: carry other TCP over a WebSocket.
- `--tunnel-token URL` / `snowglobe.tunnel-token`: a fresh token per tunnel connection, put where the URL says `{token}`.
- `--allow-private`: let the build's snapshot reach loopback and private addresses.
- `--builder docker|native`: build with Docker (default) or with none.
- `--sandbox`: keep the guest's file cache in the snapshot, for bundles and native runs.
- `--memory-limits`: boot the guest with its kernel's memory cgroup controller, so jobs may ask for
`memory_limit_mb` (off by default: it costs fork-heavy jobs ~5%; a job asking for it on a site
built without it fails, saying so). `cpus_limit` and `pids_limit` need nothing.
- `--no-chunks`: don't split large files into content-defined chunks.
- `--agent` / `snowglobe.agent="true"`: make the machine one of the agent page's, `/agent/` (below). Off by default. With `snowglobe.agent-purpose` (one line: what it is good for) and `snowglobe.agent-sample` (a command to try), the page lists it. `snowglobe.agent-name` names the machine on the page when its site's directory is called something else (the page's `python` is built from `examples/python-agent`, which has a network for `pip install`; `examples/python`, the page at `/python/`, has none).
- `snowglobe.agent-name`: the machine's name on the agent page, when its site's directory has another (see `python` below).
- `--agent-exposed-to ORIGIN` (repeatable) / `snowglobe.agent-exposed-to` (JSON array): also share the agent page's WebMCP tools with these https origins (default: none). The page shares its one set of tools with an origin only if every one of its machines does.
Example Dockerfile labels:
LABEL snowglobe.title="My app" snowglobe.ready="iex(1)> " snowglobe.memory="640" \
snowglobe.network="fetch" snowglobe.exercise='["h Enum.map"]'
## The agent page (`/agent/`)
One page for agents, with every agent runtime of the site in it: https://filipecabaco.github.io/snowglobe/agent/
Each runtime is a Linux machine (arm64) that runs in the tab, in a Web Worker of its own; nothing
runs on a server, and the page is static files. Its headline is a studio laid out as AI app
builders are: an agent builds a React app on Supabase in `web`, and the person sees it live in the
page's preview, rebuilt after each change, with its code and database as tabs and, beside it, the
agent's steps as a conversation. The page has no AI of its own: the agent is the person's, connected
over WebMCP or driving the page's controls. `snowglobe agent-pages ` writes its
list of machines (`agent/runtimes.json`, from each site's `run.json`) and its scripts when a site of
several runs is assembled; a site's own page links there ("For agents", `../agent/?runtime=`),
and the old `/agent//` addresses go there too. `?runtime=` only preselects: nothing
runs because of the address.
- The page has a service worker (`agent/sw.js`). It makes the page cross-origin isolated, which a
machine on several CPUs needs (`supabase` runs on 2: SharedArrayBuffer), and carries the
preview's requests. The first visit installs it and reloads once. Where it can't run (no service
workers, a hard reload), the several-CPU machines are refused with the reason and the others run.
- Machines start lazily: nothing boots until a command (or a copy) needs it. Each shows its
state: asleep, waking, awake, busy, suspending, or failed (with Retry).
- A few are awake at once: 2 by default ("2 of 2 awake"). The number field "Machines awake at once",
`set_awake_limit {count}` and `setAwakeLimit(count)` change it, 1 to 8, for this page load. Each awake machine is about 540 to 740 MB of memory (supabase,
on 2 CPUs, about 730). Waking another suspends the least recently used idle one first; a busy
machine (a job, a copy or an open preview in it) is never suspended: the wake waits, and the
status line says so. A lower limit suspends idle
machines, least recently used first; busy ones that keep it over the limit are said so, and
suspended as they finish. Suspends and wakes go one at a time. Idle for 5 minutes, or hidden for
a minute, a machine is suspended too.
- Suspended, a machine's state is saved in this browser (IndexedDB, a scope per runtime): only a
suspended machine's state is kept across a reload. What an awake machine did since its last
suspend is lost on reload, and the browser asks before leaving while there is any. "Start
fresh…" (always with a confirmation) goes back to the machine as built.
- A machine that fails (it powered off, its worker crashed, a capture hung) is ended at once, its
job finished as failed; Retry starts it again. When a machine's files can't be fetched (the blob
store is unreachable), the page says so: "can't reach the machine's files ()".
- Operations on one machine go one at a time, in the order asked: a run asked during a copy waits
for it; a run beside a running job is refused (one job at a time).
- Agents can run commands in the page's machines straight away: no run, copy or preview, by the
form, a WebMCP tool or `window.snowglobeAgent`, asks anyone first. Only "Start fresh…" and
"Revert to starter…" confirm. In another page's frame the page refuses to run and
offers no tools. It needs the network: it doesn't work offline.
- For agents that click and type: the form "Run a command" has the combobox "Runtime", the
textbox "Shell command", and the buttons "Run" and "Cancel". The region "Result" holds
the latest run: "Exit status: N" and "Command output" ending `[exit N]`, `[timed out]` or
`[stopped]`; "Earlier runs" lists the ones before it, each tagged with its runtime. These, the
machines' list and the forms below are in the "Machines" section, under the studio. The status
line under Run (the one `role=status`) says what is happening. "Earlier runs" also lists what
agents ran and copied through WebMCP or a script, tagged "by WebMCP" or "by a script". "Copy a file between machines"
has "From runtime", "From path", "To runtime", "To path", "Copy" and "Cancel copy". The selected
machine's terminal is under "Show 's terminal". "Preview a machine's web server" has
"Runtime", "Port", "Path", "Open preview" and "Close preview".
- The studio, at the top: the tabs "Preview", "Code" and "Database". Preview: "Open the app" (web's
port 4173) until a preview is open; then the frame, the widths "Desktop width", "Tablet width,
820 pixels" and "Phone width, 390 pixels", an address field ("Address in the preview"), "Reload"
and "New tab"; a failed build shows its error over the preview (an alert; "Hide"). Code: "Show
the files", then the navigation "Files of web's app" (a button a file; "new" or "edited" after
the agent's changes) and the open file in a `pre` labelled "Code of ", with "Last change"
(that file's diff) and "Refresh". Database: "Show the tables": each table of Supabase's public
schema with its columns and whether row level security is on (or "No tables yet; your agent
creates them with run_sql."). Beside it (below it on narrower
screens), "Agent": "Connect an agent" (the prompt to give your agent, "Copy the prompt"), then a
list, "Agent activity, newest first" (shown oldest at the top, as a chat), of every step in
every machine (filter: "Show", a machine or "All machines"): "Edited src/App.jsx", "Changed 3
files", "Ran npm install zustand", "Ran SQL on supabase", "Read 2 files", "Built version 7 in
3.0 s", "Build 8 failed" (with the error), each tagged with its runtime and who asked, its exit
status, and the changed files, each a disclosure whose diff is a `pre` labelled "Changes to
". "Undo last change" and "Revert to starter…" (asks first) take web's app back.
- `window.snowglobeAgent` (promises): `listRuntimes()` (name, purpose, state, sample, saved),
`capabilities()`, `status(runtime)`, `runCommand({runtime, command, timeoutSeconds, requestId})`
→ `{jobId, runtime}` at once (wakes or boots the machine first), `readJob(jobId)`,
`cancelJob(jobId)` (job ids are unique across runtimes), `writeFile({runtime, path, content})` →
`{bytes, changes}` once written, `writeFiles({runtime, files: [{path, content}], move, delete})`
→ `{written, bytes, changes}`, `readFiles({runtime, paths})` → `[{path, size, text, truncated} |
{path, binary} | {path, error}]`, `listFiles({runtime, path, depth})` → `{dir, entries, truncated}`,
`revert({runtime, to: "previous" | "start"})` → `{changes, output}`, `runSql({sql, runtime})` →
`{exitStatus, output}`, `buildStatus({runtime, port})` → `{version, state, error, ms, at}`, `copyFile({fromRuntime, fromPath,
toRuntime, toPath})` → `{bytes, sha256, readSeconds, writeSeconds}`, `cancelCopy()`,
`suspend(runtime)`, `wake(runtime)`, `startFresh(runtime)` (asks the person), `setAwakeLimit(count)`
→ `{awakeLimit, awake, overLimit}`, `openPreview({runtime, port, path})` → `{url, base, status |
error}`, `closePreview()`, `preview()`, `previewSnapshot({maxChars})` → `{text, url, title,
outline, console}`, `previewInteract({actions, maxChars})` → `{text, done, error}`, `unsaved()`,
`metrics()`.
- WebMCP tools, registered once where the browser has `document.modelContext` (or a polyfill such
as MCP-B's `@mcp-b/global`, even one added up to 15 s after the page starts; the first drafts'
`provideContext` works too): `list_runtimes`; `run_command {runtime, command, timeout_seconds,
request_id}` returns a job id; `job_status {job_id}` returns its output, ending `[running]`,
`[exit N]`, `[timed out]` or `[stopped]` (in a watched project, then `[changed in : ]`);
`cancel_job {job_id}`; `write_file {runtime, path, content}` writes a UTF-8 text file (at most
1 MiB; its directory is made) with no shell quoting, as a job in its turn, and returns once it is
written, with what changed (`wait_for_build: true` also waits for web's rebuild); `list_files
{runtime, path, depth}` lists a directory as an indented tree (default: the watched project, web's
`/root/app`; `node_modules`, `dist`, `.git` not entered); `read_file {runtime, path | paths}`
returns up to 20 files' text in one call (256 KiB of each, 640 KiB in all; cut files say so);
`write_files {runtime, files: [{path, content}], move: [{from, to}], delete: [path], wait_for_build}`
changes several files in one job (written to temporary names, then moved into place together: one
rebuild), says what changed and, by default, waits for web's rebuild and returns `[build N ok in
S s]` or `[build N FAILED: ]`; `revert_changes {runtime, to: "previous" |
"start"}` undoes the last change (the last 20 are kept; call again to go further back) or goes
back to how the project began (itself undoable), never touching `node_modules`, `dist` or `.git`;
`build_status {runtime, port}` returns web's last build (`/__build`); `run_sql {sql, runtime}`
runs SQL on `supabase` (default) or `postgres` through psql with `ON_ERROR_STOP` (the SQL is a
file of the job's: no quoting), then `notify pgrst, 'reload schema'`; `copy_file {from_runtime,
from_path, to_runtime, to_path}` returns the bytes copied and their sha256 (a client's cancel
signal stops it); `open_preview {runtime, port, path}` opens the page's preview on a server in a
machine and returns its address and what its first request got; `preview_snapshot {maxChars}`
reads the open preview's page: its address and title, an outline of landmarks, headings and
controls (labels, values, checked state), each control with a ref like `e3`, its visible text,
what it logged since it loaded (console errors and warnings, uncaught errors, rejected promises,
failed requests: the service worker puts `preview-hook.js` first in each HTML page it shows) and
whether what it shows is web's latest build; `preview_interact {actions: [{type, ref | selector |
text, value, key, gone, timeoutMs}], maxChars}` runs `click`, `type`, `press`, `select`, `check`,
`scroll` and `wait_for` in that page with real DOM events (typing through the input's own value
setter, so React sees it), waits for the page to settle after each, stops at the first that fails
(a ref from before a re-render or reload is refused: snapshot again) and returns a fresh snapshot;
`close_preview`;
`set_awake_limit {count}` (1 to 8); `list_runtimes` reports `awake_limit`, `preview_base` and
the open `preview`.
- Jobs: one at a time in each machine, as root on its serial shell (never the visible terminal),
from `/root`, so relative paths work and files persist between jobs. Default timeout 300 s, at
most 3600; out of time or cancelled, everything the command started is killed. A repeated
`requestId` returns the same job. Jobs run with `NO_COLOR=1` and `TERM=dumb`; escape sequences
are stripped from their output.
- Copies: one file, binary-safe, at most 8 MiB, checked by sha256 on both ends; the target is
replaced only once its copy checks out (its directory is made). It goes over the machines'
serial lines as base64, so it is slow: tens of KiB a second. Cancellable.
- Watched projects: a machine whose image has the label `snowglobe.agent-watch=` (web:
`/root/app`) reports, after each command, the files under `` it added, changed or deleted
(`node_modules`, `dist` and `.git` aside), with a unified diff of each (at most 40 files, 300
lines a file; none for binary files or files over 256 KiB). The diff is measured against a copy
the machine keeps (`/var/lib/snowglobe/watch/`), taken before the first command and brought
up to date after each; the report is taken out of the job's output, so the output is the
command's own. `readJob` gives it as `changes: {files: [{status, path, diff, added, removed}], more}`.
### The preview
A server in a machine, seen in the page, over HTTP/1.1, plus the WebSockets a page in the preview opens (up to 32). Its address is
// preview_base: https://filipecabaco.github.io/snowglobe/agent/preview/
The page's service worker hands each request under it to the agent page, which opens a TCP
connection to `` on the machine's network address, writes the request (Connection: close),
and streams the answer back: a length, chunked, or to the close; binary as it is. A redirect's
Location on the server (`/login`, `http://localhost:/...`) stays inside the preview.
Cookies a server sets are not kept (a service worker can't set them): use tokens, as supabase-js
does. A port with nothing listening answers 502, "Nothing is listening".
- A server must listen on `0.0.0.0`, not `127.0.0.1` or `localhost` (the page connects from outside
the machine): `serve --watch dist 4173` on `web` (running from its boot), `vite preview --host
0.0.0.0`, Bun with `hostname: "0.0.0.0"`.
- Live reload without WebSockets: `serve --watch` runs Vite's build in watch mode and answers
`GET /__build` with `{version, state: "building" | "ok" | "error", error, ms, at}`. While a
preview is open the page reads it (every 0.5 s for 45 s after a command in that machine, every
5 s otherwise) and reloads the preview when a new build is written; a failed build is shown in
the feed and the preview keeps the last page that built. A server with no `/__build` (plain
`serve dist`, `vite preview`) has the preview reloaded after each command in its machine. Vite's
dev server and hot module reload are untested in the preview, which does carry WebSockets now
(see the fleet page section); use `serve --watch`.
- Build pages with relative asset paths: they are served under a prefix. The `web` project's Vite
config has `base: "./"`.
- The page in the preview is this site's own (same origin): it reaches any machine's server at
`//`. Supabase's API is on port 54321 of `supabase` (Postgres,
PostgREST and Auth; `/rest/v1` and `/auth/v1`), so supabase-js's URL is
`supabase/54321`, and its key is `$ANON_KEY` on `supabase`. From inside the page:
`location.href.split("/preview/")[0] + "/preview/supabase/54321"`.
- A machine with the preview open, and every machine the page in it reaches, is busy: never
suspended until the preview is closed. One preview at a time. The machines a preview uses count
as one against the awake limit: a machine the page reaches is woken even beyond the limit, beside
the preview's own (so `web` and `supabase` together work at any limit). When every awake machine
is busy with something else (a job, a copy), a preview request or `open_preview` waits up to 30 s
for one to be free, then fails: 503 "No machine slot free" (raise the awake limit, or close the
preview).
- Answered only while a preview is open; a preview address
opened from anywhere but the agent page (typed in, linked from another site) is refused (403).
### Building a web app on Supabase, seen live
Both machines come ready and connected, and the app starts empty: the agent builds it from
nothing. `supabase` runs Postgres, Auth and the Data API, with no tables of the app's yet (its
public schema has `notes`, the table of the Supabase demo's own command-line app: leave it be).
`web` has a blank React project in `/root/app` (Vite 8, React 19, `@supabase/supabase-js`, Tailwind
v4 through `@tailwindcss/vite`, TypeScript with React's types and a `tsconfig.json`, React Router,
Zustand and clsx, all installed and pinned by its lockfile: no network needed): `src/App.jsx` is an
empty page, and `src/supabase.js` a ready client for `supabase`. From its boot `serve --watch dist
4173` builds it, serves it, and builds it again on every change. `.ts` and `.tsx` files build as they are (Vite
strips the types); `npm run typecheck` runs `tsc --noEmit`. Tailwind classes work in any component
(`src/styles.css` imports it, and its own base rules sit in `@layer base`: keep the app's rules in a
layer too, since CSS outside a layer wins over every utility class).
`npm install ` works in `web`, in the browser too: every HTTP request the machine makes is the
page's own `fetch()`, so CORS applies; registry.npmjs.org answers GETs with
`access-control-allow-origin: *` but answers no preflight (OPTIONS is a 404), and npm's own headers
(`npm-command`, `npm-session`, `pacote-*`) would need one. So the machine's `/root/.npmrc` points
npm at `http://127.0.0.1:4874/`, a relay in `serve` that asks the registry with nothing but
`Accept` (a simple request), for metadata (npm's abbreviated form) and tarballs alike. It is slow,
as everything in the emulated machine is: most of a minute for a small package. Publishing and
logging in don't work through it.
1. `open_preview {runtime: "web", port: 4173}`: the app, live. supabase-js's URL is
`supabase/54321` (`src/supabase.js` works it out from the page's address), and its
key is in `/root/app/.env` (`VITE_SUPABASE_ANON_KEY`: the Supabase CLI's fixed local key, which
is `$ANON_KEY` on `supabase`).
2. See it: `list_files {runtime: "web"}`, then `read_file {runtime: "web", paths: [...]}`. Files:
`src/App.jsx` (the app: an empty page to start), `src/main.jsx`, `src/supabase.js` (the client:
`import { supabase } from "./supabase.js"`), `src/styles.css`, `index.html`, `package.json`,
`vite.config.js`, `tsconfig.json`, and `supabase/migrations/` (empty: the app's migrations go
there).
3. Change it: `write_files {runtime: "web", files: [{path, content}, ...]}` with each file's whole
new text (or `run_command` with sed). The page shows the diffs, `web` rebuilds (a few seconds in
the tab, where the build runs in the emulated machine), the preview reloads, and the tool returns
the build's result: a failed build's error is the compiler's, with file and line, and the preview
keeps the last page that built. `revert_changes {runtime: "web", to: "previous"}` undoes it.
4. Change the schema on `supabase` with `run_sql` (it reloads the Data API's schema after), and
keep the migration in web's project, `/root/app/supabase/migrations/_.sql`, so
it shows, and is undone, with the rest. Every new table the app reads needs row level security
and policies for `authenticated`, for example:
create table public.todos (
id bigint generated always as identity primary key,
user_id uuid not null default auth.uid() references auth.users on delete cascade,
title text not null,
done boolean not null default false,
created_at timestamptz not null default now()
);
alter table public.todos enable row level security;
grant select, insert, update, delete on public.todos to authenticated;
create policy "own todos" on public.todos for all to authenticated
using ((select auth.uid()) = user_id) with check ((select auth.uid()) = user_id);
The app sees it on its next request (supabase-js asks the Data API each time).
5. Check it as a person would: `preview_snapshot {}` shows the page as built (with any runtime
error the build didn't catch, and the requests that failed), then `preview_interact {actions:
[{type: "type", ref: "e2", value: "Buy milk"}, {type: "click", ref: "e3"}, {type: "wait_for",
text: "Buy milk"}]}` uses it and returns it as it is after.
6. On `supabase`: `psql "$DB_URL" -c "select t.id, t.title, u.email from todos t join auth.users u
on u.id = t.user_id"` shows what the person added in the preview, with their user. Local Auth
confirms sign-ups at once: `supabase.auth.signUp` returns a session.
Without a second machine: copy the built `dist` (as a tarball, `copy_file`) to `supabase` and serve
it there with Bun (`BUN_BE_BUN=1 supabase run serve.ts`, `Bun.serve({hostname: "0.0.0.0", port:
3000, ...})`), then `open_preview {runtime: "supabase", port: 3000}`.
### The runtimes on this site
- runtime `conduit`: Conduit blogging app and Supabase together; open port 4173 to use the app. Select conduit, then "Open the app".
- runtime `supabase`: Supabase for web app building: Postgres, Auth and the Data API, with a preview (2 CPUs; the API on port 54321; `$DB_URL`, `$API_URL`, `$ANON_KEY` in every shell; try `psql "$DB_URL" -c "select now()"`)
- runtime `web`: build web apps: a blank React project on Supabase, rebuilt and served on port 4173 as it changes (Vite, Tailwind, TypeScript, npm) (the app in `/root/app`, watched: each command's changes are reported; try `cd /root/app && sed -i 's/Nothing here yet/Hello/' src/App.jsx`)
- runtime `python`: run Python: scripts, numpy and pandas for data work; pip install adds packages from PyPI (try `python3 -c 'import numpy, pandas; print(numpy.__version__, pandas.__version__)'`)
- runtime `duckdb`: DuckDB for analytics: SQL over CSV, Parquet and JSON files (try `duckdb -c 'select 6 * 7'`)
- runtime `bun`: Bun on a little memory: JavaScript and TypeScript run as they are, a web server (Bun.serve), fetch and WebSocket, no build step (160 MB: the fleet example's viewer; try `bun -e 'console.log(6 * 7)'`)
- runtime `postgres`: PostgreSQL for database work: load CSV files and query them with psql (try `psql -h /run/postgresql -U postgres -tAc 'select version()'`)
`python` can `pip install `: wheels from PyPI, fetched through the visitor's browser (numpy and pandas are already in
the image). A package with no wheel for 64-bit ARM musl Linux fails with pip's "No matching distribution" error.
Only this machine has a network; the Python page at `/python/` has none.
For example: write `/root/data.csv` in `python`, `copy_file` it to `duckdb`, query it with
`duckdb -csv -c "select count(*) from 'data.csv'"`, export a CSV, and load it into `postgres` with
`psql -h /run/postgresql -U postgres -c "\copy t from '/root/x.csv' csv header"`.
The other runs (IEx, TypeScript, Go, Rust, curl + jq, Elixir + Postgres and Java) are for people,
on the landing page, not on the agent page.
## The fleet page (`/fleet/`)
A `snowglobe.toml` run in one tab, on the agent page's machines: https://filipecabaco.github.io/snowglobe/fleet/
The file is read in the browser (`fleet.js`) into steps: a snapshot's `run` commands and `ready` check, a `[links.*]` entry,
a `[machines.*]` wake, a `[services.*]` opened in a frame; each has its own Run, or Run all, and Stop ends the run, closes the
frame, clears the links and sends the machines back to their image. The page draws the machines and links as a graph and
colours the file; a `run` command may be a multi-line string (three single quotes as written, three double quotes with escapes;
heredoc terminators need column 0). Starting a command wakes its machine if it sleeps and may take up to 3 minutes; a machine that
then stops answering is given up after 30 seconds. Small fleets to try are in `examples/fleet/templates/`, in the page's Templates menu. A template names a site the
page has (`build = "../python"` is the `python` machine). One site is one machine on the page. Links are real, both ends
need a network, and a machine reads its links when it wakes. The guest of `from` that connects to `as` on port 80 or 443
makes an HTTP(S) request, which the page answers from `to`'s server on `port` (machine-core.js sends it to
`/preview///…`, the service worker hands it to the page, the page to the machine). Any other port
(`as_port`, default `port`) is a raw TCP stream: armless's tunnel option carries it as binary messages over a stand-in
`WebSocket` (a private `wss://link.invalid//` URL, machine-core.js) to the page, which opens a connection into
`to`'s machine and pipes bytes both ways (orchestrator.js: 64 connections per link, 8 MiB in flight each way; an open
connection keeps `to` awake; either machine ending closes the connection). WebSockets work three ways: on any port but
80 and 443 a guest speaks WebSocket itself over that raw TCP stream; a guest's `ws:///` on 80 or 443 is spoken by
`ws-client.js` (an RFC 6455 client, no permessage-deflate) over the same stream; and a page in the preview can open
`new WebSocket("/preview///…")`: the service worker can't see WebSockets, so `preview-hook.js` replaces
`WebSocket` in the preview's pages with a proxy that passes the socket to the page (up to 32 at once, while the preview is open),
which runs `ws-client.js` into the machine. UDP is not carried.
Health checks (`[services.N.health]`, `[machines.N.health]`, a template's) run in the tab once a step is done, with the
daemon's defaults and rules. A check never wakes a sleeping machine and isn't use (orchestrator.js `healthCheck`). `replace`
starts the machine from its image and runs its steps again, `hook` runs `heal_cmd` and checks again, and `drain` only
reports (one machine, nothing to take out of service). After 5 heals in a row with no check passing, the step is degraded.
`wait_ready` holds a service's step until it passes. `[supervisors.N]` restart their children as the daemon's do
(strategies, restart types, `max_restarts` in `max_seconds`; a nested one that gives up fails its parent, and a top-level
one is degraded until its Restart button). A child is restarted by starting its machine from its image and running that
machine's steps again, so children of one site restart together. A supervised machine that stops by itself has ended.
Scale (`min`, `max`, `idle`), `ttl`, `egress`, labels and `network.mode` are read, not applied. The page's example is
`examples/fleet/snowglobe.toml`, which `snowglobe apply` runs for real too: Supabase (machine `db`) and a viewer on the bun machine
(160 MB, so on a phone most of the tab's memory is Supabase's), joined by a link (`supabase.internal:54321`). In `db`, one Bun
process (the Supabase CLI's, `BUN_BE_BUN=1`) inserts a row a second over the Data API; its `/healthz` answers 200 only if a row went
in within 5s. The viewer (service `viewer`, on 8080) is one Bun process: Bun's WebSocket subscribes to the table over Supabase
Realtime through the link, and the rows reach a Preact + htm page as server-sent events; its `/health` answers 200 while subscribed.
Both health checks are healed by a hook that starts the process again.
## Networking (`--network fetch`)
Every request leaves as the visitor's own browser request; there is no proxy server.
- HTTP (port 80): each request becomes a fetch().
- HTTPS (port 443): the machine terminates TLS 1.3 itself (armless's web relay) with a per-build CA
that only the guest trusts, then the request is replayed with fetch("https://...").
- WebSockets (ws://, wss://): the guest's upgrade opens a browser WebSocket; messages pass through.
- Other TCP: only to destinations the site tunnels (`--tunnel`), over a WebSocket.
- In `snowglobe run`, the same requests leave from the host or the container (through
HTTPS_PROXY/HTTP_PROXY if set); other TCP connections are made directly; private addresses are
refused unless `--allow-private`.
- Limits in the browser: CORS applies (servers without it answer 502), no raw TCP or UDP;
loopback, private and link-local addresses are refused (the page's own origin is allowed);
requests carry no cookies or referrer; bodies and WebSocket messages are at most 64 MiB.
## Isolation
The guest is an emulated machine whose only ways out are its terminal, its 9p filesystem (read
from the site, written to memory) and, with a network, the web relay. Around the emulator: in the
browser, the page's sandbox; natively, the process's own sandbox (no new programs or processes,
no files beyond the site, its cache, socket, logs and a job's workspace); in Docker, the container
as well. `SNOWGLOBE_SANDBOX=strict` refuses to run without the whole native sandbox.
The shared memory image is kept from changing under a machine: the cache's `ram/` is 0700 and
its files 0444, written under a temporary name and renamed into place, and checked on the open
descriptor before mapping (a regular file of this user's, no write bits, one link, no symlink);
anything off and the run restores the usual way. A page a machine writes is its own, and every
restore and fork gets fresh randomness (the guest kernel reseeds on it).
## What a built site contains
- `index.html`: the page that restores the snapshot (`?embed` hides the status strip).
- `system/state.bin.zst`: the snapshot; `system/filesystem.json` + blobs: the root filesystem over 9p.
- `system/warm.pack`: the files a restored machine reads (settling, then the exercises), in the order it first reads them, preloaded in one request; `warm-report.json` explains what went in.
- `run.json`: measured facts of the build; `transcript.json`: the exercise commands and their output.