Quick Start

This guide will help you create and manage your first microVM with Noid.

Prerequisites

Before starting, make sure you have:

  • Noid client installed (Installation Guide)
  • Access to a Noid server (running on Linux with KVM)
  • Server URL and API token

Step 1: Configure Authentication

Connect your Noid client to the server:

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

This saves your credentials to ~/.noid/config.toml and verifies connectivity.

Note: The default server port is 7654, not 8080.

Step 2: Create Your First VM

Create a new microVM:

noid create my-first-vm

This command:

  • Creates a new Firecracker microVM named "my-first-vm"
  • Uses the server's base rootfs image
  • Allocates default resources (1 vCPU, 2048 MiB RAM)
  • Starts the VM automatically

With custom resources:

noid create my-vm --vcpus 2 --memory 4096

Step 3: List Your VMs

View all VMs:

noid list

You'll see output showing your VM's status, resources, and IP address.

Step 4: Execute Commands

Run commands inside your VM:

# Simple command
noid exec my-first-vm -- uname -a

# Check OS version
noid exec my-first-vm -- cat /etc/os-release

# List processes
noid exec my-first-vm -- ps aux

The exec command runs programs inside the VM and returns the output.

Environment variables:

noid exec my-first-vm -e NODE_ENV=production -- node app.js

Environment variables passed with -e exist only for that command's duration.

Step 5: Interactive Console

Access the VM's interactive console:

noid console my-first-vm

This provides a direct serial console connection. Press Ctrl+] to exit.

Note: Only one console session per VM is supported.

Step 6: Create a Checkpoint

Create an instant snapshot of your VM:

noid checkpoint my-first-vm golden-state

This captures:

  • Complete VM memory state
  • Disk state
  • CPU registers and process state

Checkpoint creation typically takes < 100ms!

With a label:

noid checkpoint my-first-vm stable-v1 --label "Configured development environment"

Step 7: Restore from Checkpoint

Restore the VM to the checkpoint state:

noid restore my-first-vm golden-state

Restoration is nearly instant (< 50ms), perfect for:

  • Resetting test environments
  • Rolling back failed operations
  • Creating clean development environments
  • AI agent sandboxing

Clone to a new VM:

noid restore my-first-vm golden-state --as my-clone-vm

This creates a new VM from the checkpoint without affecting the original.

Step 8: Set Active VM Context

To avoid typing the VM name repeatedly:

noid use my-first-vm

This creates a .noid file in your current directory storing the active VM name. Now you can run commands without specifying the VM:

# Without 'use'
noid exec my-first-vm -- ls

# With 'use'
noid exec -- ls

Step 9: Destroy the VM

When you're done:

noid destroy my-first-vm

This will:

  • Stop the VM
  • Release resources
  • Delete the VM and its data

Common Workflows

Development Environment

# Create VM with more resources
noid create dev-env --vcpus 2 --memory 4096

# Install dependencies
noid exec dev-env -- apt-get update
noid exec dev-env -- apt-get install -y nodejs npm git

# Create checkpoint after setup
noid checkpoint dev-env clean-state

# Do your work...
noid exec dev-env -- npm install
noid exec dev-env -- npm test

# Restore to clean state when needed
noid restore dev-env clean-state

AI Agent Sandboxing

# Create VM and checkpoint
noid create ai-sandbox
noid exec ai-sandbox -- apt-get update
noid exec ai-sandbox -- apt-get install -y python3
noid checkpoint ai-sandbox golden

# Run untrusted code
noid exec ai-sandbox -- python3 /tmp/agent-code.py

# Always restore to golden state after each run
noid restore ai-sandbox golden

Testing with Parallel VMs

# Create base VM and checkpoint
noid create test-base
noid exec test-base -- apt-get update
noid exec test-base -- apt-get install -y pytest
noid checkpoint test-base configured

# Create clones from checkpoint
noid restore test-base configured --as test-1
noid restore test-base configured --as test-2
noid restore test-base configured --as test-3

# Run tests in parallel
noid exec test-1 -- pytest tests/suite1 &
noid exec test-2 -- pytest tests/suite2 &
noid exec test-3 -- pytest tests/suite3 &
wait

Understanding VM Creation Speed

Without golden snapshot (cold boot): 30-60 seconds

  • VM must boot from scratch
  • Kernel initialization
  • Init system startup

With golden snapshot: 5-10 seconds

  • Restores from pre-booted state
  • Skips boot process
  • Nearly instant

See the Checkpoints Guide for information on creating golden snapshots.

Next Steps

Now that you've created your first VM, explore:

Troubleshooting

Connection Refused

# Verify server URL and port
noid auth setup --url http://your-server:7654 --token <token>

# Check if server is running (on the server host)
ps aux | grep noid-server

VM Won't Create

# Check server has available resources
# On server host, verify disk space and memory

# Check server logs (on server host)
journalctl -u noid-server -f

Command Execution Fails

# Verify VM is running
noid list

# Check VM console for errors
noid console my-vm

Authentication Errors

# Verify token is correct
noid auth setup --url http://your-server:7654 --token <new-token>

# Check saved config
cat ~/.noid/config.toml

For more help, see Common Issues.