snowglobe

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 questionRead
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 native builds from an image in a registry or a saved archive. snowglobe run --runtime native, bundles and snowglobe mcp need no Docker either.
  • An arm64 Alpine image. Use FROM alpine (multi-arch; snowglobe builds it for arm64) or FROM 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 with go 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.