spawnr

Documentation · early preview

Get running with Spawnr.

Install the portable CLI, fetch its verified runtime, and boot your first isolated development computer.

01

Install

The public installer downloads one static Linux x86_64 binary and verifies its exact size and SHA-256 before replacing the CLI atomically.

shell
curl -fsSL https://spawnr-cli.dev/install.sh | sh
spawnr setup
spawnr doctor
Two-stage by design.

The small installer only installs the CLI. spawnr setup then fetches the larger, versioned runtime locked into that exact release.

02

Host requirements

Spawnr V1 targets Linux on x86_64. The managed runtime supplies Cloud Hypervisor, passt, the guest kernel, initramfs, agent, and OCI tools.

RequiredLinux x86_64

The first release has one portable target.

RequiredAccessible KVM

Your user must be able to read and write /dev/kvm.

For publishFUSE + user namespaces

Used to convert an environment filesystem safely into OCI layers.

Run spawnr doctor for a precise host and runtime report with remediation.

03

Create your first machine

Start without a repository, or create independent machines and clone inside each guest.

scratch machine
spawnr init scratch --environment docker.io/library/ubuntu:24.04
spawnr start scratch
spawnr open scratch
repository machine
spawnr clone \
  ghcr.io/acme/rust-dev:v1 \
  git@github.com:acme/project.git \
  --count 3

An OCI environment used by clone must already contain Git. SSH repository URLs also require an SSH client in the image.

04

Core commands

spawnr ls

List owned machines and their lifecycle state. Add --json for structured output.

spawnr start <name>

Boot the existing environment and workspace disks, then refresh session capabilities.

spawnr open <name>

Open an interactive PTY as the normal dev user in the repository directory.

spawnr stop <name>

Request a bounded guest shutdown and clean both virtualization helpers.

spawnr publish <name> <oci-ref>

Publish only the environment disk as OCI layers.

spawnr rm <name>

Destroy an owned machine after checking workspace cleanliness.

05

Host identity

On every start or open, Spawnr exposes a bounded, sanitized set of host capabilities in session tmpfs:

  • Git identity: selected user.name, user.email, and SSH signing settings.
  • SSH agent: signature requests are proxied over vsock; private key bytes stay on the host.
  • GitHub CLI: a host GH_TOKEN/GITHUB_TOKEN, or the active gh session when available, becomes guest GH_TOKEN.
  • Known hosts: bounded public SSH host-key records are copied with strict checking.
A forwarded agent is authority.

Guest code cannot read your private key, but it can request signatures while the machine is running. Use constrained keys for untrusted code.

06

Publish an environment

Environment, workspace, and session are separate storage domains. Publishing accepts only the environment disk; source and tmpfs credentials are absent from the conversion pipeline.

shell
spawnr publish project-1 ghcr.io/acme/rust-dev:v2

Registry authentication is handled by the daemonless OCI tools in Spawnr's managed runtime. No Docker socket is required.

Go deeper

Full reference on GitHub.

The repository contains the complete CLI reference, architecture, security model, development guide, and reproducible release contract.

CLI referenceEvery command and lifecycle rule → ArchitectureDisks, VMM, networking, and vsock → Security modelTrust boundaries and credentials → Release contractRuntime locks and provenance →