Create an execution environment

An execution environment is the immutable toolchain a runner guarantees for repository work. Each revision pins an image by digest, one platform, and a sorted list of executables. Services bind to one exact revision, and only a runner proving the same revision can claim their work.

Who can do this

Workspace Owners and Administrators, under AI → Environments. Building and publishing the image itself is done by whoever operates your runner hosts.

Before you begin

You need a derived Helmhive runner image that adds the package managers, compilers, SDKs, and command-line tools your repositories need, published to a registry your runner hosts can pull from, and its immutable manifest digest. Build a runner image explains how, including why dependencies must already be in the image. Helmhive does not maintain a universal dependency list and never installs packages during a job.

Create the environment

1. Choose New environment.
2. Enter a Name.
3. Paste the Immutable OCI image reference. It must end in @sha256:…; mutable tags are rejected.
4. Pick the Platform: Linux AMD64 or Linux ARM64.
5. List the Guaranteed tools as comma-separated executable names, for example git, make, pnpm, python3. The runner verifies every declared executable at startup.
6. Choose Create environment.

Every environment always uses an ephemeral filesystem and denies direct network access from commands; repository input and output stay brokered by Helmhive.

Read the card

Each environment shows Runner ready or No matching runner, the current revision, the short image digest, the number of assigned services, and the matching runners. Readiness is recomputed from runner heartbeats and can regress; it is not a flag you set.

Publish a new revision

Choose New revision on the card, enter the new digest and tools, and choose Publish revision. A descriptor identical to the current one is refused. Existing plans keep their previous snapshot.

Idle runners adopt the current published revision automatically, but only once no service is still bound to their old revision and no queued or running job still carries the old fingerprint. A runner with running work is told to retry; a runner advertising an unpublished or older descriptor is rejected. Runner credentials never change service authority.

Environment details (name and description) can be edited without touching descriptors or fingerprints.

Assign a service

Under Service assignment, pick the Service and the Execution environment revision, then Save assignment. Revision options say whether a runner is ready for them. Saving a revision with no matching online runner is allowed for a coordinated rollout, but planning stays unavailable until a runner reports that exact environment. Choosing Unassigned disables planning for the service.

Rollout order for a new revision

1. Publish the new revision.
2. Deploy runners with the matching image and wait for Runner ready.
3. Assign the revision to each intended service.
4. Only then drain or replace runners still on the old revision.

See Execution environments for why the order matters.