Projects

A Project groups one product or service inside an Organization. It contains one or more Environments, and each Environment receives Deployments of the Project’s code.

A Project has a permanent, readable ID such as agents, returned as project by the API. Each Environment has its own permanent ID within the Project, returned as environment. The Console, CLI and API use these same values. Display names can change without changing IDs or breaking references. Creation trims and lowercases Project and Environment IDs. Use the resulting ID returned by the API or copied from the Console verbatim; lookups are case-sensitive.

Environments

An Environment is an independent scope within a Project. Each Environment has its own:

Use separate Environments, such as development and production, when the same source needs different promoted versions, credentials, history or access.

An API key belongs to exactly one Environment, so API-key requests need no Project or Environment argument. A CLI user signed in with helmr login selects the Project and Environment on each command with --project and --env. See Authentication.

helmr project create agents --name "Agents"
helmr env create development --project agents

Deployments

A Deployment is an immutable, content-addressed bundle of your Project’s code. The Helmr CLI builds it on your machine or in CI: it installs dependencies, evaluates helmr.config.ts, compiles your Agents and Computers, builds the Computer images and records every Agent, Template definition and trigger. The control plane verifies and registers the finished bundle without rebuilding it.

helmr deploy --project agents --env production

helmr deploy builds, uploads and promotes in one step. helmr build produces a bundle that helmr deploy --bundle can upload later. See Deploy.

Promotion

Promotion makes one Deployment current in an Environment. New starts, trigger fires and definition reads use the current Deployment unless a read names another one explicitly.

helmr deploy promotes by default. With --skip-promotion it finalizes the Deployment without making it current, so you can inspect it first and promote it later:

helmr deploy --project agents --env production --skip-promotion
helmr deployment promote DEPLOYMENT --project agents --env production

Any Deployment registered in the Environment can be promoted, including an earlier one, which is how you roll back.

What promotion changes

Promotion changes what new work runs. It does not change work that already exists:

  • Existing Sessions stay on their Deployment. A Session is pinned to the Deployment that was current when it was created. Later Turns enqueued in that Session use the same Deployment. To run the new code, create a new Session.
  • Existing Computers are not rewritten by promotion.
  • Triggers are replaced. Promotion reconciles the Environment’s active cron triggers with the ones declared in the new Deployment. See Triggers.
  • Computer refresh settings are replaced with the ones declared in the new Deployment’s Template definitions.

The Deployment itself is never modified.

Session history retention

New Projects retain Session history for 30 days. The Project’s current policy applies to all remaining history in every Environment; there are no Environment overrides. Change it in Settings → Project → Session history, or use helmr project settings update PROJECT --history-retention 30d. Use never to disable automatic expiry.

The clock starts once the Session has ended, its process has stopped, and pending save, continuation, answer and delivery obligations have finished. Changing the policy does not reset that clock. Shortening the period can permanently delete older content on the next cleanup pass. Extending it or choosing never preserves remaining content but cannot restore content already deleted.

Expiry removes stored inputs, results, messages, questions, answers and event payloads, including Helmr’s stored Slack copies. It does not delete messages already delivered to Slack. Session identities and statuses remain. Computer disk retention and administrative audit records are separate. Open Sessions keep their history. Very short periods may expire content before a delayed reader fetches it.

Reading or changing the policy requires Manage organization. Policy changes are recorded in the administrative audit trail.