grain
7b0522d
Install

Linux microVMs · local first

Real Linux sandboxes.
On your machine.

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

Install What’s new Quick start

macOS · Linux · QEMU · Firecracker · Desktop · Recipes · MCP · Go · TypeScript · Python

Install

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

Places the CLI on your PATH and the guest agent under ~/.grain/agent/. QEMU is required for real VMs.

Product surface

More than a CLI. Same control plane for Desktop, recipes, warm pool, and Firecracker.

Desktop

Operator console

Optional Wails GUI — sandboxes, shell, multi-Run, recipes tab, warm pool, activity feed, multi-host. Not Electron; thin client of the daemon API.

install.sh --desktop

Desktop guide → Recipes

YAML library + catalog

Portable create + bootstrap files in ~/.grain/recipes. Official catalog, URL import (preview then add), deploy as a separate step.

grain recipe search && grain new --recipe …

Recipe guide → Speed

Warm pool & fast create

Suspend a golden, clone + loadvm, or claim a pre-filled pool member. Desktop prefers the pool when ready > 0.

grain new --from-pool

Lifecycle → Firecracker

Linux + KVM backend

Supported second hypervisor: vFC-1 agent over vsock, vFC-2 TAP publish/fwd. QEMU stays the default on macOS and Linux.

hypervisor: firecracker

Firecracker →

Pick a path

Same install, four first destinations.

01 · Shell

Open a Linux shell

Pull an image, create a sandbox, drop into a PTY.

grain new && grain sh

First sandbox → 02 · CI

Run GitHub Actions

nektos/act inside an isolated microVM.

grain act -- -j test

act recipe → 03 · k3s

Spin up a k3s lab

Single-node Kubernetes on a host port.

grain new --preset k3s -p

k3s recipe → 04 · MCP

Agent sandboxes

Give coding agents create/exec/delete over MCP.

grain up --mcp

MCP docs →

Try it here

Simulated terminal — switch scenarios, type commands, or click Run step.

Full tutorial →
~ — grain — interactive demo

$

How the docs are organized

Tutorials

Learn

Install, first shell, bootstrap, and recipe library.

Get started →

How-to

Do

Desktop, act/k3s, Firecracker, warm pool, mounts, networking.

Guides →

Agents

MCP

Host config and tools for coding agents.

MCP →

Reference

Look up

CLI, config, HTTP API, OpenAPI explorer, SDKs.

Reference →

Ready when you are

Free and open source. No metering. Laptop or bare metal.

Install GitHub