Landscapes
harthelm.yml describes a landscape; Sync changes it, Run starts it, and the stages prepare, test and run.
A workspace's landscape is the app around its code: the steps that prepare and test the code, and the services
that run it. You describe it in harthelm.yml in /data/app; Harthelm builds it from that file.
schema: harthelm/v1
prepare:
- name: Install dependencies
run: npm ci
test:
- run: npm test
services:
web:
type: steps
steps:
- name: Serve
run: npm start
ports:
- port: 3000
routes:
- path: /Every key is in the harthelm.yml reference.
Sync, Run, Stop and Teardown
Four actions change a landscape. They are buttons at the top of the Run panel and hart commands.
| Action | What it does | hart |
|---|---|---|
| Sync | Reads harthelm.yml, shows what changes, and then creates, changes and removes services. Starts nothing | hart sync |
| Run | Starts the run stage: every steps service runs its steps. Sleeping services wake | hart run |
| Stop | Stops the steps; the pods stay | hart stop |
| Teardown | Removes every service's pods and routes and pauses managed services. Code, env vars and secrets stay; the next Sync builds it again |
A Sync always shows a review first: the services to add, change and remove, their plan and size, the team's quota after the Sync, warnings, and anything that blocks it. It also asks for secret values the file references but the vault does not have yet.
A changed harthelm.yml, env var or secret reaches the services only at the next Sync. The Run panel says so:
"harthelm.yml changed since the last Sync".
The three stages
| Stage | Runs | Sees | Start it |
|---|---|---|---|
prepare | in the workspace, steps one after the other; the first failing step fails the stage | the workspace env vars, no secrets | Run all in the Run panel, hart prepare |
test | like prepare | like prepare | More stages → Run test stage, hart test |
run | in every replica of every steps service, the services in parallel | the workspace env vars, the service's env and its secrets | Run, hart run |
Each step runs as bash -lc '<run>' in /data/app, with mise and Nix on the path. Prepare and test read the file as
it is when they start, not as last synced.
In the run stage, all steps of a service but the last run once; the last step is the server. When it exits, Harthelm starts it again after a growing pause (1 s up to 60 s), and marks the service Failed after 5 exits within 2 minutes. A last step that exits with 0 counts as finished. The steps run again on every pod start while the landscape is started, also after a wake.
Profiles
A profile is a variant of the whole file in harthelm.<profile>.yml, for example harthelm.prod.yml. Sync,
prepare and test take a profile; Run uses the profile of the last Sync. See Profiles.
Where you edit it
- In the IDE: the editor knows the schema, completes keys and underlines mistakes.
- In Landscape config on the rail: the same file as a form, as YAML, or both side by side. The YAML stays the source; the form edits it.
- From anywhere:
hart validatechecks a file with the same rules as the platform.