CLI reference
Look things up here: every command, build flag and label, run flag and environment
variable, one line each. The guides explain them. snowglobe help prints all of this.
Commands
| Command | What it does |
|---|---|
| build <dir | image> | build a site from a Dockerfile directory, an image reference or an image archive |
| serve [dir] | preview a built site (--port, default 8000) |
| run [dir | url] | run a site in a terminal, in a container or natively |
| exec <name> <cmd> | type a command into a running instance and print what it printed |
| attach <name> | join a running instance (ctrl-] detaches) |
| ps · stop <name> | list running instances · throw one away |
| sh <name> '<cmd>' | run a command on a native instance's shell (--json, --timeout S) |
| cp <src> <dst> | copy files in or out of a native instance (name:/path on one side) |
| mcp <dir | url> | serve a site to an agent over MCP (--name, --keep, --log-dir) |
| mcp --daemon | serve the daemon to an agent over MCP: templates, machines, commands and files, snapshots, services, builds, fleets, status and events |
| bundle <dir | url> | make a site one executable (-o, --target linux|darwin, --runtime) |
| pack <dir> | pack a site into one tarball (-o site.tar.gz or .tar.zst) |
| pool <dir> | let every site under a directory share one blob store |
| agent-pages <dir> | put every --agent site under a directory on the agent page, <dir>/agent/ (its runtimes.json, scripts and service worker) |
| pwa <dir> | make a site an installable app (--name, --short-name) |
| warm <dir> <reads.json…> | add recorded reads to a site's warm pack |
| daemon | the orchestrator, on a Unix socket (--listen ADDR --token-file F for TCP; --memory 8G, --wait 30s; --detach to run it in the background; --mode provider for a template provider that only builds) |
| provide | build an image, a Dockerfile directory or a Dockerfile on the daemon into a site for the page and download it packed (-o site.tar.zst, --kernel, --network, --cpus, --memory): a static site for any CDN |
| template add <site> · ls · rm | restore a site once for machines to fork from (--name, --snapshot, --idle, --max-machines; the --health-* flags give the check its services and machines take when they have none of their own) |
| up <template> | a machine forked from a template (--name, -p PORT, --ttl, --snapshot, --label K=V; a health check with the --health-* flags, healed by --heal none|hook) |
| snapshot save <machine> · ls · rm | save a running machine whole, to start machines and templates from |
| supervisor add <name> · ls · restart · rm | a supervisor over services, machines and supervisors that restarts what fails, as Elixir's do (--child KIND/NAME[:permanent|transient|temporary], in order; --strategy one_for_one|one_for_all|rest_for_one, --max-restarts, --max-seconds); restart starts a degraded one over |
| health service|machine|template <name> | change a health check in place, restarting nothing (the --health-* flags, or --none) |
| service add <name> · ls · heal · rm | a template's machines behind host ports, started on demand and scaled to zero (--template, -p, --min, --max, --idle, --concurrency, --state); a health check on each replica and what heals it (--health-http PORT[/PATH] or --health-cmd, --health-status, --health-interval, --health-timeout, --health-failures, --health-grace, --heal none|drain|hook|replace, --heal-cmd, --drain, --wait-ready); ls shows each one's health |
| ui | the daemon in a browser, on 127.0.0.1 (--port, --no-open, --start-daemon to start a detached daemon if none runs) |
| submit <template> '<cmd>' | fire and forget: run a command once on a fresh fork; prints the run's id (--timeout, --env, --json) |
| runs [<id>] | the runs submitted, or one's output and exit status (--wait, --json) |
| ports · ports check <port> | host ports and where each leads · whether a host port is free (--ip, --json) |
| events · top | the daemon's events as they happen (replicas up, unhealthy, replaced, …) · the daemon live: memory, templates, services, machines |
| apply · diff · down | get the daemon to what a fleet file says · show the plan · remove the fleet (-f snowglobe.toml) |
| tools · version | build or find the tools image · print the version |
Build flags
| Flag | Label | What it sets |
|---|---|---|
| --out DIR | output directory (default dist) | |
| --cmd CMD | the program on the terminal (default: the image's entrypoint and command) | |
| --ready TEXT | snowglobe.ready | output that means the app is ready (default: 5 s of quiet) |
| --title TEXT | snowglobe.title | page title |
| --memory MB | snowglobe.memory | guest RAM (default 512) |
| snowglobe.nokernel-memory | guest RAM with --kernel none, when the program needs other than with a kernel (no page cache shares its files' pages between its processes) | |
| --cpus N | snowglobe.cpus | guest CPUs, 1 to 8 (default 1) |
| --build-cpus N | snowglobe.build-cpus | CPUs to boot on before the snapshot (default: the larger of --cpus and 4) |
| --exercise CMD | snowglobe.exercise | a command whose reads are preloaded; repeatable (label: a JSON array) |
| --warm REGEX | snowglobe.warm | extra guest paths to preload |
| --network fetch | snowglobe.network | give the guest a network through the browser (default none) |
| --tunnel [HOST:]PORT=URL | snowglobe.tunnels | carry TCP to HOST:PORT over a WebSocket; repeatable |
| --tunnel-token URL | snowglobe.tunnel-token | where a fresh token comes from, for {token} in tunnel URLs |
| --allow-private | let the build reach loopback and private addresses | |
| --jit on|off | snowglobe.jit | off keeps the interpreter instead of compiling hot guest code, in the page and natively: slower, smaller (default on) |
| --kernel none | snowglobe.kernel | no guest kernel: the command, an aarch64 Linux program, runs on its own, in the page and natively; a smaller snapshot (one CPU in the page, the build running it and its exercises on --build-cpus at once). As a container's: the program is pid 1 and reaps the orphans of its processes (a job's leftovers, what a killed job started), and its hostname is the site's title made one (Python + Rich: python-rich). Its clocks go on through the time its state was saved, as after a suspend: a restore of the build's snapshot is that much later on the monotonic clock than the build, a machine saved with snapshot save than its save |
| --builder B | docker (default) or native | |
| --sandbox | snapshot for running natively (run, bundle) rather than in a page | |
| --no-chunks | store every file in one blob, however large | |
| --agent | snowglobe.agent | make the machine one of the agent page's (in the page); on several CPUs the page is made cross-origin isolated for it |
| --agent-exposed-to ORIGIN | snowglobe.agent-exposed-to | also share the page's WebMCP tools with this origin; repeatable (label: a JSON array) |
Run flags
| Flag | What it does |
|---|---|
| --name N · --detach | name the instance · run it in the background |
| --runtime docker|native | in a container (default) or natively |
| --fork | every sh on a fresh copy of the machine (see --fork) |
| -p [IP:]HOST:GUEST | forward a host port to a guest port (needs --network fetch) |
| --record-reads FILE | write every file the guest reads, for warm |
| --tunnel · --allow-private | replace the site's tunnels · let the guest reach this machine |
| --jit on|off | the JIT for this run, over the site's own choice |
| --max-runtime · --stop-file · --log-dir | see limits, stopping and logs |
Environment
| Variable | What it does |
|---|---|
| SNOWGLOBE_BUILDER | default for --builder |
| SNOWGLOBE_RUNTIME | default for --runtime |
| SNOWGLOBE_VM | the snowglobe-vm to use instead of the release's |
| SNOWGLOBE_BOOT | a kernel archive to use instead of the release's |
| SNOWGLOBE_TOOLS_BUILD=1 | always compile the tools image locally |
| SNOWGLOBE_SANDBOX | strict refuses to run without the whole native sandbox; off skips it |
| SNOWGLOBE_BOOT_STALL_SECS | how long a boot may do nothing before it counts as stalled (default 300; 0: no limit) |
| SNOWGLOBE_CACHE | where native runs keep what they learn and the snapshots' memory images (default ~/.cache/snowglobe) |
| SNOWGLOBE_RAM_IMAGE=off | restore into memory of the run's own instead of sharing the snapshot's image |
| ARMLESS_JIT=off | keep armless's interpreter instead of its native JIT, on this host, over the site's choice (run --jit still wins) |
| ARMLESS_JIT_PREWARM=off | don't compile what earlier runs recorded at start |
| HTTPS_PROXY · HTTP_PROXY · NO_PROXY · SSL_CERT_FILE | passed to snowglobe run's container |