Core concepts

A short glossary of daemon, images, sandboxes, the guest agent, and how they fit together.

Daemon

grain up starts a local control plane that owns VM metadata, disks, and the API (unix socket and optional TCP). CLI commands talk to this process — not directly to QEMU.

Images vs VMs

Pull or import a base image once. Each grain new clones it (qcow2 overlay or CoW) so creates stay relatively cheap.

Ephemeral vs persistent

• Ephemeral (default): stop or daemon restart removes the VM
• Persistent (-p): disk kept; use stop / start or suspend / restore

Guest agent

A small HTTP service inside the Linux guest (grain-agent). The host reaches it via SLIRP hostfwd (and optionally vsock). It powers:

• grain x (exec)
• grain sh (PTY shell)
• grain cp / grain fs
• health, stats, secret materialize

SSH still works as a fallback and for bootstrap when the agent is not baked into the image.

Control plane API

Automation can use:

• Unix socket: ~/.grain/grain.sock
• TCP: http://127.0.0.1:7474 (default config)
• OpenAPI: GET /openapi.yaml
• SDKs: Go · TypeScript · Python

Optional Bearer auth: set api_token in config and GRAIN_TOKEN in the environment.

For a shared remote machine (daemon as a service, teammates over SSH or SDKs), see Remote sandbox host. The CLI uses the local unix socket on the machine where it runs; remote automation uses the TCP API or an SSH session on the host.

Hypervisors

Where data lives

~/.grain/
  config.yaml
  grain.sock
  ssh/           # host identity for guests
  images/        # base disks
  vms/           # per-VM disks, serial logs, QMP
  agent/         # grain-agent-linux-* for deploy
  secrets/       # host secret store
  proxy/         # egress proxy state