A CLI for managing microVMs with instant checkpointing and restore.

Create VMs in one command. Checkpoint them instantly. Clone and restore from any checkpoint.

noid runs as a client-server system: noid-server manages micro VMs on a Linux host, and noid is a CLI client that talks to the server over HTTP and WebSocket. The client can run from anywhere — Linux x86_64, macOS Intel, and macOS Apple Silicon.

⚠️ EXPERIMENTAL SOFTWARE - This project is in active development. Expect breaking changes on each commit. No backwards compatibility will be supported yet.

curl -fsSL https://raw.githubusercontent.com/noid-one/noid-cli/master/install.sh | bash

This installs noid to ~/.local/bin/. On Linux it also installs noid-server. Or download manually:

mkdir -p ~/.local/bin

# Client — auto-detect platform (macOS reports arm64, but releases use aarch64)
NOID_OS=$(uname -s | tr '[:upper:]' '[:lower:]')
NOID_ARCH=$(uname -m | sed 's/arm64/aarch64/')  # normalize macOS arm64 → aarch64
curl -fsSL -o ~/.local/bin/noid \
  "https://github.com/noid-one/noid-cli/releases/latest/download/noid-${NOID_OS}-${NOID_ARCH}"
chmod +x ~/.local/bin/noid

# Server (Linux only — run on the VM host)
curl -fsSL -o ~/.local/bin/noid-server \
  https://github.com/noid-one/noid-cli/releases/latest/download/noid-server
chmod +x ~/.local/bin/noid-server

Make sure ~/.local/bin is in your PATH. Both binaries can update themselves:

noid update
noid-server update

macOS users: Downloaded binaries are not notarized. On first run, macOS Gatekeeper may block execution with: "noid cannot be opened because it is from an unidentified developer."

Fix by removing the quarantine flag:

xattr -d com.apple.quarantine ~/.local/bin/noid

Or right-click the binary in Finder, select "Open", then confirm.

Or build from source:

git clone https://github.com/noid-one/noid-cli.git && cd noid-cli
cargo build --release --workspace
cp target/release/noid target/release/noid-server ~/.local/bin/

The server needs a Linux host with KVM support (/dev/kvm), Firecracker installed at /usr/local/bin/firecracker, and a kernel + rootfs image.

The install script handles everything (kernel build, rootfs build, networking, Firecracker):

sudo bash scripts/install-server.sh

This builds kernel 6.12.71 from source and creates an Ubuntu 25.04 rootfs. Re-running the installer is safe — it validates the existing kernel version and only rebuilds if the version doesn't match. If you previously had an older kernel (e.g. 4.14 or 6.1), it will be replaced automatically.

Edit server.toml to point to your images:

kernel = "/home/youruser/vmlinux.bin"
rootfs = "/home/youruser/rootfs.ext4"

# listen = "0.0.0.0:7654"       # default: binds all interfaces on port 7654

See server.toml.example for all options.

The default port is 7654, which does not require root.

noid-server serve --config server.toml

noid-server add-user alice

This prints an API token (noid_tok_...). Save it — it can't be retrieved later.

From any machine (local or remote), configure the client to point at the server:

noid auth setup --url http://your-server --token noid_tok_...

Verify the connection:

noid whoami
# User: alice
# ID:   a1b2c3d4-...

noid create my-vm
# VM 'my-vm' created (state: running)

noid create beefy-vm --cpus 4 --mem 512

noid exec my-vm -- uname -a
# Linux noid 6.12.71 ...

Set an active VM to skip the name:

noid use my-vm
noid exec -- cat /etc/os-release

noid console my-vm

Type exit to detach (the VM keeps running).

# Snapshot a running VM
noid checkpoint my-vm --label before-deploy

# List checkpoints
noid checkpoints my-vm

# Clone from a checkpoint into a new VM
noid restore my-vm a1b2c3d4 --as my-vm-copy

# Or restore in-place (replaces the current VM)
noid restore my-vm a1b2c3d4

On btrfs, checkpoints and clones are instant (zero-copy). On ext4, they fall back to regular file copies.

noid list
noid info my-vm
noid destroy my-vm

noid (client)  ──HTTP/WS──>  noid-server  ──unix socket──>  firecracker
   any machine                 VM host       │                microVM
                                             │
                               noid-netd  <──┘  (TAP/IP/NAT, runs as root)

• REST API for lifecycle operations (create, destroy, list, checkpoint, restore)
• WebSocket for interactive sessions (console, exec)
• Token auth with SHA-256 hashed tokens and constant-time verification
• Multi-tenant: users are isolated at the DB and filesystem level
• No async runtime — fully synchronous (tiny_http + tungstenite + ureq)

See docs/server-guide.md and docs/client-guide.md for detailed guides.