grain
Install

get-started

Sandbox recipes (YAML create + bootstrap)

Portable recipe files for create options and bootstrap steps that stamp readiness before grain says ready.

Goal: check in a YAML file that creates a sandbox, runs install steps, and only reports ready when those steps finish with zero failures.

Deep contract: Readiness protocol. Manual cloud-init path: Bootstrap until ready.

1. Minimal recipe

Save as git-lab.recipe.yaml:

yaml 
apiVersion: grain/v1
kind: Sandbox
metadata:
  name: git-lab
spec:
  image: grain-ubuntu
  cpus: 2
  memory_mb: 2048
  ready_timeout: 10m
  bootstrap:
    steps:
      - name: packages
        message: installing git
        run: |
          export DEBIAN_FRONTEND=noninteractive
          apt-get update -qq
          apt-get install -y -qq git
bash 
grain up
grain image pull grain-ubuntu
grain recipe validate ./git-lab.recipe.yaml
grain new --recipe ./git-lab.recipe.yaml
grain status git-lab
grain sh git-lab

When bootstrap.steps is set, create defaults to --wait bootstrap. Ready means: VM up, agent healthy, all steps succeeded (state=ready).

2. What a recipe can set

FieldRole
metadata.nameDefault VM name (-n overrides) and default ready_name
spec.image / cpus / memory_mb / disk_gb / persistentCreate resources
spec.presetMerge docker / k3s / act cloud-init
spec.mountsHost shares (. = your current directory)
spec.forwardsPort publish (guest_port, optional host_port)
spec.userdata / userdata_fileExtra cloud-init or shell (merged before bootstrap steps)
spec.bootstrap.stepsOrdered guest scripts; each becomes a readiness phase
spec.wait / ready_timeoutWait mode and create timeout

CLI flags still win over recipe fields (same idea as profiles).

Examples in-repo: examples/recipes/.

3. Inspect without creating

bash 
grain recipe validate ./git-lab.recipe.yaml
grain recipe show ./git-lab.recipe.yaml
grain recipe show ./git-lab.recipe.yaml --userdata   # compiled cloud-init

4. vs profiles and presets

MechanismPortable file?Bootstrap readiness?
Profile (~/.grain/config.yaml)No (host config)Only if you attach userdata yourself
Preset (docker / k3s / act)Built into grainPreset install scripts (not recipe steps)
Recipe (--recipe)Yes (repo-friendly)Yes — steps stamp readiness automatically

Next