grain

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

Apache-2.0 · macOS & Linux

grain runs small, disposable Linux VMs locally — for a shell, for GitHub Actions (grain act), or for a throwaway k3s lab. Ephemeral by default; persistent when you want it.

---

Install

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

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.

---

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
Presets	act · k3s · docker
Guest agent	Exec, shell, file copy, and fs ops without living in SSH
API	Unix socket + optional TCP · OpenAPI
SDKs	Go · TypeScript · Python

---

Docs

Page
Install	Platforms and install options
Quick start	Config + first VM
First sandbox	Tutorial + interactive demo
act	GitHub Actions in a microVM
k3s	Single-node cluster preset
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

Contributing · Security · Code of conduct · Releasing

License

Apache-2.0