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
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.
macOS (Homebrew):
brew install rvben/tap/shuckLinux & macOS (installer script):
curl -sSfL https://raw.githubusercontent.com/rvben/shuck/main/install.sh | shCross-platform (PyPI):
pip install shuckPinning a version: curl -sSfL https://raw.githubusercontent.com/rvben/shuck/main/install.sh | SHUCK_VERSION=v0.1.2 sh or pip install shuck==0.1.2.
# 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 helloOn Linux, shuck run needs firecracker on PATH. If it's missing, shuck prompts to download a pinned release into the data directory. For non-interactive use (CI, scripts), set SHUCK_AUTO_INSTALL_FIRECRACKER=1 to skip the prompt.
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.
If you want to use your own images, pass --kernel and the rootfs path:
shuck run /path/to/rootfs.ext4 --kernel /path/to/vmlinuxCopy config.example.toml to one of the discovery paths:
~/.config/shuck/config.toml(user)/etc/shuck/config.toml(system)
Or pass --config /path/to/config.toml explicitly. See config.example.toml for all available fields.
| Platform | Backend | Networking | Status |
|---|---|---|---|
| Linux x86_64 | Firecracker | TAP + nftables NAT, port forwarding | Usable |
| macOS ARM64 | Apple Virtualization.framework | Shared NAT (VZ-managed) | Experimental |
shuck is one of several ways to run microVMs. Rough positioning:
| Tool | Backend | Focus | Notes |
|---|---|---|---|
| shuck | Firecracker (Linux) + Apple VZ (macOS) | Single-host VM manager with a REST API and CLI | SQLite-backed state, port forwarding, guest agent over vsock. |
| Ignite | Firecracker | Docker-image-style workflow on Firecracker | Archived by Weaveworks; Linux only. |
| firecracker-containerd | Firecracker | containerd runtime backed by microVMs | Kubernetes-friendly; Linux only. |
| krunvm | libkrun | OCI-image microVMs on macOS | No daemon; ephemeral per-command VMs. |
| Lima | QEMU (+ VZ on macOS) | Full Linux VMs as a dev environment | Heavier than Firecracker; broader guest support. |
Pick shuck if you want Firecracker on Linux with a matching Apple VZ path on macOS, driven by a single CLI + daemon.
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.
- Threat model — STRIDE analysis and residual risks.
- Hardening guide — deployment posture and config recommendations.
- Report vulnerabilities privately via GitHub Security Advisories. See SECURITY.md.
The daemon defaults to loopback-only. Don't bind it on a public interface without a bearer token and a terminating reverse proxy.
shuck run can't find firecracker (Linux)
On a TTY, shuck prompts to download a pinned release. For scripted/CI use, set SHUCK_AUTO_INSTALL_FIRECRACKER=1 to skip the prompt, or install Firecracker yourself from the releases page.
shuck run reports kvm_init: permission denied (Linux)
Add your user to the kvm group: sudo usermod -aG kvm $USER and re-login.
shuck run fails on macOS with a virtualization entitlement error
The binary needs the com.apple.security.virtualization entitlement. pip, brew, and the installer script all ship a codesigned binary. If you built from source, run make install — it ad-hoc signs via shuck.entitlements.
macOS: VM boots but exits immediately
Apple VZ needs an initramfs to mount the rootfs. If you're using custom images, make sure --initrd points at a matching initramfs (see guest/build-initramfs.sh).
shuck daemon binds but the CLI can't connect
The CLI defaults to http://127.0.0.1:7777. If the daemon listens elsewhere, pass --api-url http://host:port (and --api-token if auth is enabled).
Rootfs edits don't take effect on macOS
Use make update-rootfs to inject changes via debugfs (works in LXC and macOS). Loop-mounting doesn't work on macOS.
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)make run-daemon # Start daemon
make build-agent-aarch64 # Build ARM64 agent (macOS guests)
make update-rootfs # Inject agent into rootfs imageA systemd unit file is provided at contrib/shuck.service.
Issues and pull requests welcome. See CONTRIBUTING.md for the dev workflow and commit conventions.
See LICENSE.