Checkpoints

Noid's checkpoint and restore features enable instant VM snapshots and cloning.

Overview

Checkpoints capture the complete state of a running VM:

• Memory: All RAM contents
• Disk: Filesystem state
• CPU: Registers and process states
• Network: Connection states

Creating Checkpoints

Basic Checkpoint

noid checkpoint <vm-name> <checkpoint-name>

Example:

noid checkpoint my-vm stable-v1

With Description Label

noid checkpoint my-vm release-v2 --label "Production ready build"

Restoring Checkpoints

In-Place Restore

Restore the VM to a previous state ("rewind"):

noid restore <vm-name> <checkpoint-id>

Example:

noid restore my-vm stable-v1

This reverts the VM to the exact state when the checkpoint was created.

Clone to New VM

Create a new VM from a checkpoint:

noid restore <vm-name> <checkpoint-id> --as <new-vm-name>

Example:

noid restore base-vm golden --as test-instance-1
noid restore base-vm golden --as test-instance-2

This leaves the original VM untouched and creates independent clones.

Performance

Storage optimization:

• On btrfs: Zero-copy (instant) disk cloning via reflinking
• On ext4: Regular file copy for disk

Golden Snapshots

Golden snapshots are pre-booted VM images that dramatically accelerate VM creation.

Understanding the Benefit

Without golden snapshot (cold boot):

• Time: 30-60 seconds
• Process: Full kernel boot, init system startup

With golden snapshot:

• Time: 5-10 seconds
• Process: Restore from pre-booted state

Golden Snapshot Structure

Located in ~/.noid/golden/, contains four files:

1. rootfs.ext4: Filesystem with pre-installed tools
2. memory.snap: RAM state captured at snapshot time
3. vmstate.snap: CPU and device state
4. config.json: Template metadata (CPU count, memory allocation)

Creating Golden Snapshots

Method 1: Automatic Provisioning

sudo bash scripts/provision-golden.sh

This script:

1. Spins up temporary VM named _provision
2. Waits for complete boot
3. Installs applications (customize the script)
4. Creates checkpoint
5. Promotes to golden status
6. Cleans up temporary VM

Method 2: From Existing Checkpoint

sudo bash scripts/provision-golden.sh --from-checkpoint <checkpoint-id>

Customizing Golden Snapshots

Edit scripts/provision-golden.sh to pre-install tools:

# Example installations
apt-get install -y python3 python3-pip
apt-get install -y nodejs npm
apt-get install -y golang

pip3 install requests numpy pandas
npm install -g typescript webpack

All pre-installed tools become instantly available in new VMs.

Configuration Matching

The golden snapshot activates only when a new VM's specs match the stored configuration:

• CPU count must match
• Memory allocation must match

Default configuration: 1 vCPU with 2048 MiB RAM

Create VMs with different specs:

# Uses golden snapshot (matches defaults)
noid create vm1

# Custom specs (won't use golden snapshot)
noid create vm2 --vcpus 2 --memory 4096

Clock and Network Synchronization

The system automatically handles:

1. Clock sync: Updates guest system clock using sudo date -s @<epoch>
2. Network: Reconfigures interfaces with fresh IP addresses

When to Rebuild Golden Snapshot

Rebuild the golden snapshot when:

• Kernel version changes (e.g., upgrading from 6.12.71)
• Base filesystem updates
• Firecracker version changes
• New tools need pre-installation
• CPU or memory defaults change

sudo bash scripts/provision-golden.sh

Use Cases

Development Environment

# Setup environment
noid create dev-env --vcpus 2 --memory 4096
noid exec dev-env -- apt-get update
noid exec dev-env -- apt-get install -y build-essential git

# Save clean state
noid checkpoint dev-env clean

# Work on code...
noid exec dev-env -- git clone https://github.com/user/repo
noid exec dev-env -- make build

# Reset to clean state
noid restore dev-env clean

Testing Isolation

# Create test base
noid create test-vm
noid checkpoint test-vm before-test

# Run test
noid exec test-vm -- pytest tests/

# Always restore between tests
noid restore test-vm before-test

# Next test on clean slate
noid exec test-vm -- pytest tests/integration/

AI Agent Sandboxing

# Golden snapshot pattern
noid create sandbox
noid exec sandbox -- apt-get install -y python3
noid checkpoint sandbox golden

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

# Always restore after execution
noid restore sandbox golden

Parallel Testing

# Create base with tools
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

# Clone for parallel execution
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

Prepared Environments

# Create multiple environment types
noid create python-env
noid exec python-env -- apt-get install -y python3 python3-pip
noid checkpoint python-env python-ready

noid create node-env
noid exec node-env -- apt-get install -y nodejs npm
noid checkpoint node-env node-ready

# Clone as needed
noid restore python-env python-ready --as task-1
noid restore node-env node-ready --as task-2

Secret Injection

# Create VM without secrets
noid create app-vm
noid checkpoint app-vm base

# Inject secrets via environment (not persisted)
noid exec app-vm -e API_KEY=secret123 -- ./run-app.sh

# Restore removes secrets from VM
noid restore app-vm base

Best Practices

1. Descriptive names: Use names like configured-v1.2 instead of timestamps
2. Golden snapshots: Create after initial setup for fast cloning
3. Regular cleanup: Remove old checkpoints to save space
4. Test restoration: Periodically verify checkpoints restore correctly
5. Label your checkpoints: Add --label to describe the state
6. Match specs: Ensure VM specs match golden snapshot config for speed

Troubleshooting

Checkpoint Fails

# Check disk space
df -h ~/.noid

# Check VM status
noid list

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

Restore Doesn't Work

TLS connection hangs:

• Issue: CRNG not initialized in kernel
• Solution: Use kernel 6.12.71+ or rebuild with entropy sources

VM fails to boot:

• Issue: Kernel/Firecracker version mismatch
• Solution: Rebuild golden snapshot

IP Address Changes

After restore, VMs get new IP addresses. Use DNS or service discovery instead of hardcoded IPs:

# Bad: Hardcoded IP
curl http://172.16.0.5:8080

# Good: DNS or hostname
curl http://my-service.local:8080

Verification

After creating golden snapshot:

# Check files exist
ls -lh ~/.noid/golden/

# Verify config
cat ~/.noid/golden/config.json

# Test VM creation speed
time noid create test-vm

Expected: 5-10 seconds with golden snapshot, 30-60 seconds without.

Next Steps

• Quick Start - Checkpoint examples
• Server Setup - Golden snapshot provisioning
• CLI Reference - All checkpoint commands