Guides (how-tos by job)

How-to guides assume you already installed grain and created at least one sandbox. Each page solves a specific job.

If you are brand new, start with the quick start.

Popular workloads

Guide	Outcome
GitHub Actions (act)	Run nektos/act in an isolated microVM — host Docker stays clean
k3s lab	Single-node Kubernetes with `--preset k3s`, API port + kubeconfig

bash

grain act -- -j test
grain new --preset k3s -n lab -p --wait userdata

Everyday use

Guide	When you need it
Images & golden boots	Pull, import, bake, choose ubuntu/alpine/golden
Guest agent	Exec, shell, cp, fs without living in SSH
Networking & ports	Publish ports, live forwards, SLIRP limits
Overlay network	Guest↔guest L2 on one host (`network: overlay`)
Guest architecture	arm64 / amd64 guests (TCG cross-arch)
Virtio GPU	`virtio-gpu-pci` for guests
Mounts & shares	Share host directories into the guest
Profiles & presets	Named defaults and docker / k3s / act presets
Pause, suspend, restore	Free CPU or RAM while keeping work

Security & ops

Guide	Audience
Egress proxy	Admins locking down outbound HTTP(S)
Remote sandbox host	Team box: systemd, API token, SSH tunnels, SDKs
MCP server	Claude Code / Codex / OpenCode / Grok Build tool host
Secrets	Host secrets and inject into VMs
Firecracker	Linux experimental backend
Troubleshooting	When boot, agent, or QEMU misbehaves

More recipes

Recipe	Outcome
Coding agent	Isolated agent with a mounted repo
Docker socket	Docker in the VM, socket on the host
CI ephemeral	Create → test → destroy

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 (experimental) — Experimental Firecracker hypervisor backend.
GitHub Actions with act (isolated CI) — Run nektos/act inside a grain microVM — isolated GitHub Actions without polluting host Docker.
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 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.