IaC

Write images and environments as YAML, scaffold a starter, export what is on the server, and apply changes with helios code apply.

Images and environments can live in your repository as YAML. The CLI builds and applies them.

helios code iac scaffold
helios code apply

Scaffold a starter

helios code iac scaffold

This writes three files to ~/.helios/iac. Pass a folder to write somewhere else.

helios code iac scaffold ./infra/helios

File	Content
`starter.image.yaml`	An image named `starter` built from `Dockerfile.starter`
`Dockerfile.starter`	Ubuntu 24.04, Node 20, Claude Code, `helios-agent`, `shpool`, `tmux`, `vals`, and the Helios hooks
`starter-env.yaml`	An environment named `starter` on that image with Claude Code enabled

Scaffold never overwrites a file that already exists. It also points your CLI context at the folder, so helios code apply finds the files without arguments. Pass --no-set-glob to skip that.

The template comes from the server, so it can change without a new CLI release.

Export what is on the server

helios code iac export

This writes every image and environment on the server as YAML into ~/.helios/iac, or into the folder you pass. Existing files are left alone. Use it to bring a dashboard-made setup into version control.

File format

Every file has the same envelope.

version: v1
resource: images
spec:
  # ...

resource is images or environments. One resource per file.

Image

version: v1
resource: images
spec:
  id: starter
  dockerfile: ./Dockerfile.starter

Field	Required	Meaning
`id`	Yes	Lowercase name, 2 to 64 characters, letters, digits, `-` and `_`
`dockerfile`	No	Path to the Dockerfile, relative to the YAML file. Default `./Dockerfile`

Environment

version: v1
resource: environments
spec:
  id: starter
  imageId: starter
  enabledAiAgents:
    - id: claude_code
  sessionManager: shpool
  envFile: ./starter.env
  cloudInitFile: ./cloud-init.sh
  integrationIds:
    - <integration-id>
  diffViewer: lumen diff

Field	Required	Meaning
`id`	Yes	Same rules as image ids
`imageId`	Yes	The image to run
`enabledAiAgents`	No	Harnesses to start. `claude_code` is the only id
`secrets`	No	Inline key-value secrets
`envFile`	No	A dotenv file to read secrets from. Inline `secrets` win on conflict
`cloudInitFile`	No	A script that runs at boot
`integrationIds`	No	Integrations the agent can reach
`sessionManager`	No	`shpool` or `tmux`
`diffViewer`	No	Command the files tab runs. Default `lumen diff`

Ids must be unique across all matched files.

Apply

helios code apply

With no arguments, apply uses the globs saved in your context. Pass globs to override.

helios code apply "./infra/helios/*.yaml"

Apply builds every image first, streaming the build log, then creates or updates every environment. An image whose Dockerfile has not changed is reported as unchanged and not rebuilt.

Check what would happen without applying.

helios code apply --dry-run

Rebuild every image even when the Dockerfile is unchanged.

helios code apply --force

When piped, apply prints one JSON object with a result per resource.

helios code apply --json

{
  "ok": true,
  "results": [
    { "type": "image", "id": "starter", "status": "built v3" },
    { "type": "environment", "id": "starter", "status": "unchanged" }
  ]
}

If a build fails, apply stops at that resource and exits with a non-zero code.

Run it in CI

Set HELIOS_API_KEY and HELIOS_PROJECT, then apply.

HELIOS_API_KEY=$KEY HELIOS_PROJECT=$PROJECT helios code apply "./infra/helios/*.yaml" --json

Launch an agent on the result.

helios code launch starter --git-repo https://github.com/acme/api