Skip to main content

​
images ls

​
images get

​
images new

Create an image. Aliases: images save, images create. Snapshot mode — snapshot a VM into a reusable image (the VM is stopped automatically before snapshotting):

​
Building from a nix flake

With --flake, images new builds a NixOS image server-side from a nix flake — same reference syntax as nixos-rebuild switch --flake. The build is always asynchronous: the command returns immediately and you watch progress with machine0 images versions get <image> <version>.
The #attr fragment is required — it names the nixosConfigurations attribute to build (nixos-rebuild defaults to the hostname; there is no hostname here). Supported references (v1): github:owner/repo (with optional /ref path segment or ?ref= branch, ?rev= 40-hex commit pin, ?dir= subdirectory) and local folder paths (absolute, relative, ~/, or path:). Other schemes (git+https, gitlab:, …) aren’t supported yet. A ?rev= pin needs its branch named alongside it (?rev=<sha>&ref=<branch>) — ?rev= alone is rejected, because GitHub-built images track their branch. GitHub builds track their branch: pushes to it automatically build a new version and promote it on success, as long as the machine0 GitHub App is installed on the repo (the CLI warns when it isn’t; rebuild admission enforces it). The tracked source shows as the Git Repo and Git Branch rows in machine0 images get; turn it off with machine0 images update <image> --no-track. See branch tracking for the full semantics (what turns tracking off, promotion rules, blocked pushes). Private GitHub repos work once you’ve connected GitHub to your account (dashboard → Account → GitHub) and the GitHub App installation includes the repo — no new flags, the same github:owner/repo#attr reference just resolves. Without a connection, only public repos resolve (the error message tells you where to connect). The builder fetches private sources with your connection’s credentials, and those credentials are removed before the image is snapshotted. Publicly reachable repos always build without your credentials — so a public flake whose lock file pins private inputs won’t resolve them; the build fails with the nix fetch error (fully visible, see below). Make the top-level repo private, or vendor the inputs, to build with credentials. How it works: a temporary builder VM named m0-build-* boots from the NixOS base image, applies nixos-rebuild switch --flake pinned to your source, is snapshotted, and destroyed. The builder is visible in machine0 ls and bills like a normal machine for the duration of the build (typically 10–40 minutes). The builder belongs to the build pipeline: stop, start, reboot, suspend, rename, and images new snapshots of it are rejected — only machine0 rm works, which cancels the build. If your balance hits the suspension threshold mid-build, the builder is destroyed without a suspend snapshot and the build fails; top up and re-run the same command. A brand-new image name is published on success; building onto an existing image creates a draft version to test and promote, same as a snapshot save. Local folders: inside a git repository the WHOLE repo is the flake source (exactly like nix) and only git-tracked files are uploaded — commit or git add your flake first. Plain folders are packed whole, minus .git (the CLI warns, since untracked files like .env travel too). The packed source is uploaded over your authenticated session (no public URL), capped at 32MB gzipped, and deleted server-side once the build finishes. Submodule contents are not packed. The builder garbage-collects its nix store before snapshotting so your uploaded sources are not baked into the published image — with one nix-inherent exception: a flake whose system closure references its own source (self, ${./.}) keeps that source alive in /nix/store, and it ships inside the image. This applies to private GitHub sources too: a self-referencing private flake ships its own source inside the image it builds. If the build fails, the error (including the tail of the nixos-rebuild log) is recorded on the image version and kept for 7 days — machine0 images versions get <image> <version> prints the full log tail (for nix errors, the actual cause is at the END of the log, after the warnings), the dashboard’s image panel shows it, and the events feed carries an excerpt. Re-running the same command retries (re-resolving branches / re-uploading local sources), and any new build or snapshot onto the image supersedes the failed draft — an upload does too, but only once the image is ready (a brand-new image whose first build failed isn’t, so retry, push, or snapshot it instead). Limitations (v1): GitHub.com repositories only (private ones via the account GitHub connection); no git submodules or LFS; the profile must import the machine0-nixos base modules (keep the nix user and SSH enabled), or the build fails verification. A ?rev= pin is taken as given — the server verifies the repo exists but not that the commit belongs to it (exactly like nix), so recorded rev provenance on pinned builds is user-asserted and a bad rev fails on the builder with a nix fetch error.

​
images update

​
images rm

Deleting the auto-saved snapshot of a suspended machine (named suspended-<machine>-<date>-<time>) also destroys that machine — the snapshot is its only copy of its disk. Check machine0 ls for suspended machines before removing suspended-* images.