Docs
snowglobe runs a Docker image where Docker isn't. It turns the image into a site, a folder of static files you can host anywhere. Open it in a browser tab, run it from one binary with no Docker installed, or give it to an agent as a sandbox. It starts in about a second, because it restores a snapshot taken once your app was ready.
Which page answers what
New here? Read Getting started below, then Building a site. Come back to this table when you have a question.
| Your question | Read |
|---|---|
| How do I install it and build my first site? | Getting started, below |
| How do I choose when the snapshot is taken, make the first load fast, or give the site more CPUs? | Building a site |
| Can the machine reach the internet, a database, or my own machine? | Networking |
| How do I run a site in a terminal, from a URL, or as one executable? | Running outside a browser |
| How does an agent or a script run commands in a machine, by CLI, MCP or in a page? | For agents and programs |
| How do I run many machines, services that scale to zero, or a whole fleet from one file? | Orchestration and fleets |
| How do I notice a service's machine that hangs or answers with errors, and replace it? | Health checks and healing |
| How do I restart what depends on something that failed, as an Elixir supervisor would? | Supervisors |
| How do machines reach each other? | Links |
| What stops a guest from touching my computer? | Isolation |
| Where does a run in the browser keep my work? | Saving your work |
| What happens inside a build, and why did mine fail? | How it works |
| What does this flag, command or variable do? | CLI reference |
Agents can read all of this as one text file: llms.txt.
Getting started
Build a site from a Dockerfile, preview it, then put the folder on any static host.
What you need
- Docker, or nothing. With Docker, snowglobe builds your Dockerfile and boots it in
a build container. Without Docker,
--builder nativebuilds from an image in a registry or a saved archive.snowglobe run --runtime native, bundles andsnowglobe mcpneed no Docker either. - An arm64 Alpine image. Use
FROM alpine(multi-arch; snowglobe builds it for arm64) orFROM arm64v8/alpine. - On an x86 host, QEMU's binfmt handlers, so Docker can build arm64 images. Docker
Desktop has them. On Linux, run this once:
docker run --privileged --rm tonistiigi/binfmt --install arm64.
Install
One line installs the latest release into ~/.local/bin. It works on Linux (x86-64 or
arm64) and on a Mac with Apple silicon. It checks the download against the release's checksums and
needs no sudo. You can read the script first.
curl -fsSL https://filipecabaco.github.io/snowglobe/install.sh | sh
SNOWGLOBE_VERSION=0.4.0 picks a version. SNOWGLOBE_INSTALL_DIR picks another
directory.
You can also download a binary from the releases, or install with Go 1.27 or later:
go install github.com/filipecabaco/snowglobe/cmd/snowglobe@latest
Your first site
Any directory with a Dockerfile, or any image reference, builds into dist/:
snowglobe build ./my-app # a directory with a Dockerfile, or an image reference snowglobe serve dist # preview at http://localhost:8000
The page shows a terminal running whatever the image runs: its ENTRYPOINT and
CMD, with its ENV and WORKDIR.
dist/ is plain static files. Upload it to GitHub Pages, a CDN or any web server. There is
no snowglobe server.
Everything runs on an emulated 64-bit ARM CPU, translated to WebAssembly as it runs, so expect it to be slower than native. Cold loads take seconds. Commands take tens of milliseconds to a few seconds.
What the first build downloads
- The tools image, the machine that boots and snapshots your image, from
ghcr.io/filipecabaco/snowglobe-tools. A version that hasn't been released compiles it locally instead, once, in a few minutes. snowglobe-vm, the machine that runs sites natively. A release of snowglobe is one file that carries its own and unpacks it into your cache the first time it runs a site natively. Built withgo install, snowglobe downloads the release's instead.- The prebuilt kernel, once, when you build without Docker.
Releases are for Linux on x86-64 and arm64, and macOS on Apple silicon.