Deploy

A Deployment is one immutable build of your project in one Environment. This guide builds and promotes one, separates build from deploy, and promotes or rolls back an existing Deployment. For how Deployments, Environments and promotion relate, see Projects.

You need the CLI configured (see Quickstart), Docker with Buildx, and Node.js 22 or newer.

Deploy a project

From a directory containing helmr.config.ts, package.json and your Agent source, run:

helmr deploy . --project demo --env production

With a saved login, --project and --env are required. With an Environment API key, omit them; the key already selects the Environment.

The CLI:

  1. evaluates helmr.config.ts on your machine, so install the packages it imports first;
  2. builds the project in Helmr’s digest-pinned Linux builder through Docker: installs dependencies, compiles your definitions and builds each Computer image;
  3. uploads the content-addressed result, skipping objects the control plane already has;
  4. asks the control plane to verify and finalize the Deployment;
  5. promotes it, making it the Environment’s current Deployment.

Progress goes to stderr and the result to stdout; --json writes progress as JSON lines. Dependency installation and lifecycle scripts run only inside the builder, never on the control plane or a worker. The control plane verifies the uploaded build; it does not rebuild it.

Dependencies and the build environment

Helmr follows the project’s packageManager field and lockfile. npm, pnpm, Bun and Yarn all work, and build.installCommand replaces the inferred install command. A frozen lockfile gives reproducible builds.

The builder is a Debian environment with a native toolchain, so ordinary lifecycle scripts and native modules work. When dependencies need more operating-system packages, add them with build.builder. To give the install step a private registry token, list the name of an environment variable in build.secrets; it is mounted at /run/secrets/NAME during installation only. See Configuration.

Do not copy credentials into source or build outputs. Credentials that Agents and Computers use at runtime belong in Secrets.

Build and deploy separately

helmr build . --output .helmr/deployment-bundle
helmr deploy --bundle .helmr/deployment-bundle --project demo --env staging

helmr build writes the verified bundle locally (default .helmr/deployment-bundle). helmr deploy --bundle uploads that bundle through the same verification path. This lets CI build once and deploy the same bundle to several Environments.

Deploy without promoting

helmr deploy . --project demo --env production --skip-promotion

The Deployment is finalized but does not become current. Inspect it, then promote it when ready:

helmr deployment list --project demo --env production
helmr deployment get DEPLOYMENT_ID --project demo --env production --json
helmr deployment promote DEPLOYMENT_ID --project demo --env production

deployment promote also rolls back: promote an earlier Deployment from the list to make it current again.

What promotion changes

  • New Sessions and new Computers use the current Deployment.
  • Existing Sessions stay on the Deployment they started with, including when you add Turns to them or start the Agent again with the same session key.
  • Existing Computers keep their disk; see Prepare a Computer.
  • Cron triggers declared in the new Deployment replace the previous ones; see Triggers.

If a deploy finalization fails with an uncertain result, rerun it with the same --idempotency-key. Without one, the CLI generates a new key for each run.