grain

Linux microVM sandboxes on your own hardware.
Documentation · Quick start · Desktop · Recipes · Releases

Apache-2.0 · macOS & Linux · QEMU · Firecracker · Desktop · MCP

grain runs small, disposable Linux VMs locally — for a shell, for GitHub Actions (grain act), or for a throwaway k3s lab. CLI, optional Desktop GUI, recipe library, and MCP all talk to the same daemon. Ephemeral by default; persistent when you want it.

Install

curl -fsSL https://raw.githubusercontent.com/cxdy/grain/main/scripts/install.sh | bash

# Optional: also install Grain Desktop
curl -fsSL https://raw.githubusercontent.com/cxdy/grain/main/scripts/install.sh | bash -s -- --desktop

Install QEMU, then check dependencies:

# macOS
brew install qemu

# Debian / Ubuntu
sudo apt-get install -y qemu-system qemu-utils

grain doctor

---

First sandbox

grain up
grain image pull grain-ubuntu
grain new
grain sh

When you’re done:

grain rm
grain down

Optional starter config and more flags: quick start.

---

Desktop (optional GUI)

Operator console for the same daemon as the CLI — not Electron, not a second engine.

Area	Notes
Sandboxes	List, search, bulk start/stop/rm, multi-host Run… (re-run failed / copy all)
Create	Cold · from template · warm pool (prefer claim when ready)
Recipes / Images	Library + official catalog · deploy preflight · image pull
Ops	Activity feed (CLI/MCP/API too) · warm pool Settings · doctor · multi-host switcher

# Prefers GitHub Release Desktop assets (v0.8.0+); else build from a checkout
curl -fsSL https://raw.githubusercontent.com/cxdy/grain/main/scripts/install.sh | bash -s -- --desktop
# or: just desktop-build && ./bin/grain-desktop

Release assets: macOS Grain_darwin_<arch>.app.tar.gz → ~/Applications/Grain.app;
Linux grain-desktop_linux_<arch>.tar.gz → grain-desktop on your PATH.

→ Desktop guide · desktop/README.md

---

Recipes library

Portable YAML sandboxes (grain/v1) live under ~/.grain/recipes. Import never creates a VM — deploy is a separate step.

grain recipe search              # official catalog (git index)
grain recipe add python-dev      # pull one official body into the library
grain recipe add ./my-lab.yaml   # or a local file / https URL
grain new --recipe python-dev    # create from a library name

Official pack includes act/k3s/docker labs, python-dev, go-dev, remote-coding, and more. Desktop has a full Recipes tab (catalog, form builder, deploy preflight).

→ Sandbox recipes

---

Faster creates (template / warm pool)

Cold boots are guest-bound (~seconds). After a golden is agent-ready:

grain new -i grain-ubuntu -n golden -p --wait agent
grain suspend golden
grain new --from golden -n work1                 # clone + loadvm when snapshotted
# config warm_pool.template/size, then:
# grain pool fill && grain new --from-pool -n work2

→ Lifecycle: create path & warm pool

---

Firecracker (Linux + KVM)

Default hypervisor is still QEMU (macOS and Linux). On Linux with /dev/kvm, Firecracker is a supported second backend:

Tier	What works
vFC-1 agent	Pull fc-kernel + grain-ubuntu-fc; grain new --wait agent; exec/shell/cp/sync over vsock UDS + CONNECT
vFC-2 partial net	TAP + create-time -P / grain fwd (host TCP proxy; needs CAP_NET_ADMIN). Overlay, mounts, UDP stay QEMU-only

# ~/.grain/config.yaml → hypervisor: firecracker
grain image pull fc-kernel
grain image pull grain-ubuntu-fc
grain doctor
grain new -i grain-ubuntu-fc --wait agent
# optional: ./scripts/smoke-fc.sh · ./scripts/smoke-fc-net.sh

→ Firecracker on Linux · Hypervisor matrix

---

MCP (coding agents)

MCP is built into grain (not a separate binary):

grain up --mcp                 # daemon + MCP at http://127.0.0.1:7476/mcp
# IDE stdio host:
#   command: grain, args: ["mcp"]

→ MCP server guide

---

Workloads

GitHub Actions

Run nektos/act inside an isolated microVM so host Docker stays clean.

cd /path/to/your/repo
grain act -- -l          # list workflows
grain act -- -j test     # run a job

→ act guide

k3s lab

Single-node Kubernetes with the API published to the host.

grain new --preset k3s -n lab -p --wait userdata
grain fwd ls lab         # host port → guest 6443

→ k3s guide

---

Features

Area	What you get
CLI	up · new · sh · x · rm · mounts · port forwards · profiles · warm pool
Desktop	Optional Wails operator console · sandboxes, recipes, warm pool, activity · guide
Recipes	Library + official catalog · grain new --recipe · bootstrap readiness · guide
Presets	act · k3s · docker
Guest agent	Exec, shell, file copy, and fs ops without living in SSH
Hypervisors	QEMU default (macOS/Linux); Firecracker supported on Linux+KVM (vFC-1 agent + vFC-2 partial net)
API	Unix socket + optional TCP · OpenAPI
SDKs	Go · TypeScript · Python

---

Docs

Page
Install	Platforms and install options (incl. Desktop)
Quick start	Config + first VM
First sandbox	Tutorial + interactive demo
Recipes	Library, official catalog, bootstrap readiness
Desktop	Optional operator GUI
Warm pool	Fast create / suspend / pool
act	GitHub Actions in a microVM
k3s	Single-node cluster preset
Remote lab	Host + laptop CLI happy path
Firecracker	Linux+KVM backend (agent + TAP publish/fwd)
Hypervisor matrix	QEMU vs Firecracker capabilities
Guides	Images, agent, networking, mounts, proxy
Reference	CLI, config, API, SDKs

The site is built from this repo’s docs/ directory.

---

Develop

just test           # unit tests (mock hypervisor)
just smoke-api      # CLI + daemon e2e without QEMU
just build
just desktop-test   # Desktop backend unit tests
just desktop-build  # optional Grain Desktop (Wails; needs CGO + wails CLI)

Contributing · Security · Code of conduct · Releasing

License

Apache-2.0