shuck 0.1.2

microVM manager built on Firecracker (Linux) and Apple Virtualization.framework (macOS)

Shuck

An open-source microVM manager built on Firecracker (Linux) and Apple Virtualization.framework (macOS).

• Boot lightweight VMs in milliseconds
• Execute commands, transfer files, open interactive shells
• Stream serial console logs
• Port forwarding with nftables NAT (Linux)
• REST API + CLI
• Cloud-init style userdata scripts

Status

Pre-1.0. The core feature set works and has test coverage, but:

• The HTTP API, CLI flags, config schema, and on-disk state layout may change without a deprecation period.
• The Linux/Firecracker backend is more mature than the macOS/Apple VZ backend.
• It has not been run at scale or under production workloads.
• Security features (token auth, rate limiting, encrypted secrets) exist but have had limited review. Don't expose the daemon to an untrusted network.

Useful for experimentation, local development, and CI. Not recommended for production.

Quick Start

# Install
pip install shuck

# Fetch the default kernel + rootfs for this host
shuck images pull

# Start the daemon
shuck daemon &

# Boot a VM
shuck run --name hello --cpus 2 --memory 512

# Interact
shuck exec hello -- uname -a
shuck shell hello
shuck cp local.txt hello:/tmp/local.txt
shuck logs hello -f

# Clean up
shuck destroy hello

shuck images pull fetches the latest signed image set from the images-* GitHub Releases. If no image release is published yet for this arch, the command will fail — use the BYO path below in the meantime.

BYO kernel / rootfs

If you want to use your own images, pass --kernel and the rootfs path:

shuck run /path/to/rootfs.ext4 --kernel /path/to/vmlinux

Configuration

Copy config.example.toml to one of the discovery paths:

1. ~/.config/shuck/config.toml (user)
2. /etc/shuck/config.toml (system)

Or pass --config /path/to/config.toml explicitly. See config.example.toml for all available fields.

Platform Support

Platform	Backend	Networking	Status
Linux x86_64	Firecracker	TAP + nftables NAT, port forwarding	Usable
macOS ARM64	Apple Virtualization.framework	Shared NAT (VZ-managed)	Experimental

Architecture

CLI (shuck) ──> REST API (shuck-api) ──> Core (shuck-core)
                                           ├── VMM (shuck-vmm)      Firecracker / Apple VZ
                                           ├── State (shuck-state)  SQLite persistence
                                           ├── Net (shuck-net)      TAP devices, IP allocation
                                           └── Storage (shuck-storage) Rootfs cloning
                                       Guest Agent (shuck-agent) ←── Proto (shuck-agent-proto)

Host-guest communication uses vsock (port 52). Messages are length-prefixed JSON with base64-encoded binary payloads.

Development

Requires Rust 1.90+ and cargo-nextest.

make build          # Debug build
make build-release  # Release build (LTO, stripped)
make build-agent    # Static musl agent for guest VMs
make test           # Full test suite
make test-unit      # Unit tests only
make lint           # fmt-check + clippy
make check          # Type check
make install        # Install (auto-detects macOS, signs binary)

Running a Development VM

make run-daemon                     # Start daemon
make build-agent-aarch64            # Build ARM64 agent (macOS guests)
make update-rootfs                  # Inject agent into rootfs image

Systemd

A systemd unit file is provided at contrib/shuck.service.

License

See LICENSE.