Installation

Noid is a CLI tool for managing Firecracker microVMs with instant checkpointing and restore.

Quick Install (Recommended)

The easiest way to install Noid is using our installation script:

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

This script will:

• Download the latest Noid binary
• Install it to ~/.local/bin/
• Set up necessary permissions

Make sure ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add this to your ~/.bashrc or ~/.zshrc to make it permanent.

Verify Installation

noid --version

Server Installation

Noid uses a client-server architecture. The server (noid-server) must run on a Linux host with KVM support.

Recommended hosting: A Hetzner dedicated server (EX-line or AX-line) provides excellent performance and value for running noid servers. These servers come with KVM support and sufficient resources for managing multiple VMs.

System Requirements

• Operating System: Linux (Ubuntu 24.04+, Debian 12+, or similar)
• CPU: x86_64 with KVM virtualization support
• Root access: Required for installation

Automated Installation (Recommended)

The install-server.sh script automates the complete server setup:

# Clone the repository
git clone https://github.com/noid-one/noid-cli.git
cd noid-cli

# Run the installation script (takes 5-15 minutes)
sudo bash scripts/install-server.sh

This script will automatically:

1. Install system dependencies (build tools, debootstrap, iptables)
2. Install Rust toolchain
3. Install Firecracker v1.14.1 to /usr/local/bin/firecracker
4. Build Linux kernel 6.12.71 from source
5. Build noid binaries (noid, noid-server, noid-netd) and install to ~/.local/bin/
6. Configure host networking (IP forwarding, NAT rules, noid-netd systemd service)
7. Create Ubuntu 25.04 rootfs (2GB ext4 filesystem)
8. Initialize database
9. Create golden snapshot for fast VM creation
10. Generate server.toml configuration

Note: The script validates and replaces outdated kernels automatically on subsequent runs.

Server Status

The install script automatically starts the server as a systemd service. The server is now running and:

• Initialized SQLite database at ~/.noid/noid.db
• Listening on 0.0.0.0:7654 (default port)
• Network daemon (noid-netd) is running for VM networking

Managing the server:

# Check server status
sudo systemctl status noid-server

# Restart server
sudo systemctl restart noid-server

# View server logs
sudo journalctl -u noid-server -f

Server Configuration

The install script creates server.toml with:

[server]
listen = "0.0.0.0:7654"
exec_timeout_secs = 30
console_timeout_secs = 3600

[paths]
kernel = "/path/to/vmlinux.bin"
rootfs = "/path/to/rootfs.ext4"

You can customize settings like listen address and timeout values.

User Management

Before clients can connect, create a user to get an API token:

# Create a user (required before client configuration)
noid-server add-user user@email.com

This generates a unique 64-character hexadecimal API token. Save this token - you'll need it for client configuration.

Other user management commands:

# List all users
noid-server list-users

# Rotate a user's token
noid-server rotate-token user@email.com

# Remove a user
noid-server remove-user user@email.com

Building from Source

If you want to build only the client binaries without the full server setup:

Prerequisites

• Rust 1.70 or later
• Cargo
• Git

Build Steps

# Clone the repository
git clone https://github.com/noid-one/noid-cli.git
cd noid-cli

# Build all binaries
cargo build --release

# Install binaries
cp target/release/noid ~/.local/bin/
cp target/release/noid-server ~/.local/bin/
cp target/release/noid-netd /usr/local/bin/

Note: For a complete server installation with kernel, rootfs, and golden snapshot, use the install-server.sh script instead (see Server Installation).

Client Configuration

After creating a user on the server (see User Management), configure the client to connect:

noid auth setup --url http://your-server:7654 --token <your-token>

Replace <your-token> with the 64-character hexadecimal token you received from noid-server add-user.

This saves credentials to ~/.noid/config.toml.

Verifying KVM Support

Check if your CPU supports hardware virtualization:

egrep -c '(vmx|svm)' /proc/cpuinfo

If the output is greater than 0, your CPU supports virtualization. Verify KVM is available:

ls -l /dev/kvm

If /dev/kvm doesn't exist, load KVM modules:

sudo modprobe kvm
sudo modprobe kvm_intel  # For Intel CPUs
# OR
sudo modprobe kvm_amd    # For AMD CPUs

macOS and Windows

macOS

Noid requires KVM, which is Linux-specific. For macOS users:

1. Install the client (noid) on macOS
2. Run the server (noid-server) on a Linux machine (VM, remote server, or cloud instance)
3. Connect from macOS to the remote server

The macOS client can control VMs on the remote Linux server.

Windows (WSL2)

WSL2 doesn't support KVM by default. Options:

1. Install the client on WSL2
2. Run the server on a Linux VM or remote server
3. Connect from WSL2 to the remote server

Next Steps

• Quick Start Guide - Create your first VM
• Server Setup - Advanced server configuration
• CLI Reference - Learn all commands

Troubleshooting

Permission Denied

If you get permission errors:

chmod +x ~/.local/bin/noid

Command Not Found

Ensure ~/.local/bin is in your PATH:

echo $PATH

Add to PATH if needed:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

KVM Not Available

Ensure KVM modules are loaded:

sudo modprobe kvm
sudo modprobe kvm_intel  # or kvm_amd

Server Won't Start

Check logs and ensure Firecracker is installed at /usr/local/bin/firecracker:

which firecracker
firecracker --version

For more help, see Common Issues.