Execution environments
Repository work needs a toolchain: package managers, compilers, SDKs, command-line tools. Helmhive does not assume one universal set. Each workspace defines execution environments, and every revision is an immutable descriptor that runners prove and plans pin.
The descriptor
Section titled “The descriptor”A revision pins an OCI image by digest, one platform (Linux AMD64 or ARM64), a sorted list of executable names the image guarantees, an ephemeral filesystem, and no direct network access from commands. The descriptor is hashed into a fingerprint that anyone can recompute.
Binding and matching
Section titled “Binding and matching”- A service binds to exactly one revision. Without a binding, planning is disabled.
- Every plan snapshots the service’s revision and fingerprint at planning time.
- A runner advertises the fingerprint of the image it actually runs, and a job can be claimed only by a runner whose fingerprint equals the plan’s.
- A plan is rejected at execution if the service’s binding changed after approval, if the environment was archived, or if the stored fingerprint no longer matches the descriptor.
Publishing and advancing
Section titled “Publishing and advancing”Publishing a revision is permission for idle runners to adopt that exact descriptor. On heartbeat, a runner advertising the current published revision of its own environment advances in place only when it has no running job, no service is still bound to its old revision, and no queued or running job still carries the old fingerprint. Otherwise it is told to retry. A runner advertising anything other than its tracked revision or the current one is rejected.
This ordering is what makes a zero-interruption rollout possible: publish, deploy runners that match, wait for Runner ready, assign services, then retire the old runners. A single-runner installation can assign the new revision first, accepting a temporary planning interruption that the console shows explicitly.
Isolation
Section titled “Isolation”Each runner runs one pinned image and creates a fresh sandboxed workspace per job. Jobs cannot start nested containers, reach a container socket, or install dependencies. Deploy several runners when services need different images or more capacity.