grain
Install

guides

Profiles and presets (reuse create defaults)

Named create defaults in config, plus docker / k3s / act cloud-init presets.

Named profiles

Define reusable create defaults in ~/.grain/config.yaml. Built-in profiles are available without config; the same name in config overrides the builtin.

Builtin: remote-coding

Durable remote lab defaults (no host mounts — laptop paths are not on the daemon host; use grain sync):

FieldValue
persistenttrue
cpus4
memory_mb8192
disk_gb32
imagegrain-ubuntu
bash 
grain profile ls
grain new --profile remote-coding --wait agent -n alice-dev
grain sync push ~/proj alice-dev:/work/proj

Config examples

yaml 
profiles:
  agent:
    cpus: 4
    memory_mb: 4096
    disk_gb: 20
    image: ubuntu-cloud
    persistent: false
    mounts:
      - {host: ".", guest: "/work"}
    forwards:
      - {guest_port: 3000}   # host port auto-allocated
  k3s-lab:
    cpus: 2
    memory_mb: 4096
    disk_gb: 20
    persistent: true
    preset: k3s
  # optional override of the builtin:
  # remote-coding:
  #   cpus: 8
  #   memory_mb: 16384
  #   persistent: true
bash 
grain profile ls
grain new --profile agent
grain new --profile k3s-lab -n lab
grain new --profile remote-coding -n lab --wait agent

Resolve order: CLI flags (only if explicitly set) → profile fields (config, else builtin) → global config defaults.

Created instances are tagged profile=<name> for inspect via the API / meta.

Presets

Embedded cloud-init fragments applied with grain new --preset NAME or profile.preset:

PresetEffect
dockerInstall Docker (cloud-init packages / install path)
k3sSingle-node k3s; defaults toward 2 CPU / 4096 MiB when unset; auto-publishes guest 6443
actDocker Engine + nektos/act; defaults toward 2 CPU / 4096 MiB when unset

Presets merge into userdata with the structured cloud-init merge (safe with --userdata-file).

For long custom first-boot work that should block create until you say ready, implement the Readiness protocol and use grain new --wait bootstrap.

bash 
grain new --preset docker
grain new --preset k3s -n lab -p
grain new --preset act -v "$PWD:/work" -n act-lab --wait agent
# first boot can take several minutes — use:
grain logs -f lab

For a one-shot GitHub Actions run (create → act → destroy), prefer the dedicated command:

bash 
grain act -- -l
grain act -- -j test

See the act recipe.

Combining

bash 
grain new --profile agent --preset docker   # profile resources/mounts + docker userdata
grain new --profile agent -c 8              # flag overrides profile cpus