How-to guides assume grain is installed and you have created at least one sandbox. Each page covers one job.
New to grain? Start with the quick start .
Highlights Guide Outcome Grain Desktop (GUI) Optional operator console — sandboxes, shell, recipes tab , warm pool, activity, multi-Run Sandbox recipes Library + official catalog · grain new --recipe · Desktop import/deploy Pause, suspend, restore Fast create / warm pool / latency (--from, --from-pool)Firecracker Supported Linux+KVM backend (vFC-1 agent + vFC-2 TAP publish/fwd)
bash
Copy
curl -fsSL …/install.sh | bash -s -- --desktop # Desktop release assets (v0.8.0+)
grain recipe search && grain new --recipe python-dev
# Linux+KVM: hypervisor: firecracker → see Firecracker guide Popular workloads bash
Copy
grain act -- -j test
grain new --preset k3s -n lab -p --wait userdata Everyday use Security & ops More recipes Coding agent sandbox (mounted repo) — Isolated agent or tool in a microVM with your repo mounted read-write.Docker in the VM (socket forward) — Install Docker via preset; use in-guest or forward the socket to the host.Egress proxy (allowlist + secret inject) — Default-deny HTTP(S) proxy with allow rules and secrets.Ephemeral CI (create → test → rm) — Disposable Linux runner: one VM per job, no leftover state.Firecracker on Linux — Supported Firecracker backend on Linux+KVM: agent (vFC-1) over vsock, catalog pull (amd64/arm64), TAP publish/fwd (vFC-2 partial).GitHub Actions with act (isolated CI) — Run nektos/act inside a grain microVM — isolated GitHub Actions without polluting host Docker.Grain Desktop (optional GUI) — Wails-based operator console — thin client of the grain daemon for macOS and Linux.Guest agent (exec, shell, files, health) — Use grain-agent inside the VM for exec, shell, copy, fs, health, and readiness — without living in SSH.Guest architecture (arm64 / amd64, TCG) — Run arm64 or amd64 Linux guests, including x86_64 on Apple Silicon via QEMU TCG.Images and golden boots (pull, import, bake) — Pull grain-ubuntu goldens, import disks, bake images, and choose ubuntu/alpine bases.k3s lab (single-node Kubernetes) — Spin up a disposable or persistent single-node k3s cluster with grain’s k3s preset.MCP server (guides entry → MCP section) — Connect Claude Code, Codex, OpenCode, Grok Build, and other MCP hosts to grain sandboxes.Mounts and host shares (9p, virtiofs) — virtio-9p and virtiofs directory sharing.Networking and ports (SLIRP, publish, hostfwd) — SLIRP, publish, live forwards, and limits.Overlay network (guest↔guest L2) — Share an L2 segment across grain VMs with network overlay mode.Pause, suspend, and restore (lifecycle) — Free guest CPUs or host RAM without losing a persistent lab.Profiles and presets (reuse create defaults) — Named create defaults in config, plus docker / k3s / act cloud-init presets.Remote lab happy path (host + laptop CLI) — Operator how-to: run grain on a sandbox host, dial it from your laptop with GRAIN_API, create a remote-coding lab, sync code, and tunnel published ports.Remote sandbox host (team box) — Run grain as a service on a shared machine; connect with the CLI over HTTP, SSH tunnels, or SDKs — with firewall and token rules.Secrets (host store + guest inject) — Store secrets on the host and materialize them into a guest VM without baking them into images.Troubleshooting (boot, agent, QEMU) — Diagnose create hangs, agent health, QEMU failures, and platform issues.Virtio GPU (display device, not passthrough) — Attach a virtio-gpu device to grain QEMU guests.