CLI reference
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 |
| 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) |
| template add <site> · ls · rm | restore a site once for machines to fork from (--name, --snapshot, --idle, --max-machines) |
| up <template> | a machine forked from a template (--name, -p PORT, --ttl, --snapshot, --label K=V) |
| snapshot save <machine> · ls · rm | save a running machine whole, to start machines and templates from |
| service add <name> · ls · rm | a template's machines behind host ports, started on demand and scaled to zero (--template, -p, --min, --max, --idle, --concurrency, --state) |
| 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 · 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) |
| --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 | |
| --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 |
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 |
| --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 |
| 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 |