snowglobe

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

CommandWhat 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 --daemonserve 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
daemonthe 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)
providebuild 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 · rmrestore 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 · rmsave a running machine whole, to start machines and templates from
supervisor add <name> · ls · restart · rma 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 · rma 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
uithe 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 · topthe daemon's events as they happen (replicas up, unhealthy, replaced, …) · the daemon live: memory, templates, services, machines
apply · diff · downget the daemon to what a fleet file says · show the plan · remove the fleet (-f snowglobe.toml)
tools · versionbuild or find the tools image · print the version

Build flags

FlagLabelWhat it sets
--out DIRoutput directory (default dist)
--cmd CMDthe program on the terminal (default: the image's entrypoint and command)
--ready TEXTsnowglobe.readyoutput that means the app is ready (default: 5 s of quiet)
--title TEXTsnowglobe.titlepage title
--memory MBsnowglobe.memoryguest RAM (default 512)
snowglobe.nokernel-memoryguest RAM with --kernel none, when the program needs other than with a kernel (no page cache shares its files' pages between its processes)
--cpus Nsnowglobe.cpusguest CPUs, 1 to 8 (default 1)
--build-cpus Nsnowglobe.build-cpusCPUs to boot on before the snapshot (default: the larger of --cpus and 4)
--exercise CMDsnowglobe.exercisea command whose reads are preloaded; repeatable (label: a JSON array)
--warm REGEXsnowglobe.warmextra guest paths to preload
--network fetchsnowglobe.networkgive the guest a network through the browser (default none)
--tunnel [HOST:]PORT=URLsnowglobe.tunnelscarry TCP to HOST:PORT over a WebSocket; repeatable
--tunnel-token URLsnowglobe.tunnel-tokenwhere a fresh token comes from, for {token} in tunnel URLs
--allow-privatelet the build reach loopback and private addresses
--jit on|offsnowglobe.jitoff keeps the interpreter instead of compiling hot guest code, in the page and natively: slower, smaller (default on)
--kernel nonesnowglobe.kernelno 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 Bdocker (default) or native
--sandboxsnapshot for running natively (run, bundle) rather than in a page
--no-chunksstore every file in one blob, however large
--agentsnowglobe.agentmake 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 ORIGINsnowglobe.agent-exposed-toalso share the page's WebMCP tools with this origin; repeatable (label: a JSON array)

Run flags

FlagWhat it does
--name N · --detachname the instance · run it in the background
--runtime docker|nativein a container (default) or natively
--forkevery sh on a fresh copy of the machine (see --fork)
-p [IP:]HOST:GUESTforward a host port to a guest port (needs --network fetch)
--record-reads FILEwrite every file the guest reads, for warm
--tunnel · --allow-privatereplace the site's tunnels · let the guest reach this machine
--jit on|offthe JIT for this run, over the site's own choice
--max-runtime · --stop-file · --log-dirsee limits, stopping and logs

Environment

VariableWhat it does
SNOWGLOBE_BUILDERdefault for --builder
SNOWGLOBE_RUNTIMEdefault for --runtime
SNOWGLOBE_VMthe snowglobe-vm to use instead of the release's
SNOWGLOBE_BOOTa kernel archive to use instead of the release's
SNOWGLOBE_TOOLS_BUILD=1always compile the tools image locally
SNOWGLOBE_SANDBOXstrict refuses to run without the whole native sandbox; off skips it
SNOWGLOBE_BOOT_STALL_SECShow long a boot may do nothing before it counts as stalled (default 300; 0: no limit)
SNOWGLOBE_CACHEwhere native runs keep what they learn and the snapshots' memory images (default ~/.cache/snowglobe)
SNOWGLOBE_RAM_IMAGE=offrestore into memory of the run's own instead of sharing the snapshot's image
ARMLESS_JIT=offkeep armless's interpreter instead of its native JIT, on this host, over the site's choice (run --jit still wins)
ARMLESS_JIT_PREWARM=offdon't compile what earlier runs recorded at start
HTTPS_PROXY · HTTP_PROXY · NO_PROXY · SSL_CERT_FILEpassed to snowglobe run's container