# 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