Guides

Problem-oriented how-tos for everyday use and operating grain in production-like setups.

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

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

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
Menu bar tray	`grain tray` status helper
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

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

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