How Helmr works

Helmr runs JavaScript and TypeScript Agents in Linux Computers. You choose the harness, model, tools and work procedure inside the Agent. Helmr admits work, runs it one Turn at a time, keeps the Computer’s state across Turns and retains each outcome.

Resource	What it is
Agent	A deployed definition: a Computer recipe, optional `init` and a `turn` handler.
Computer	A Linux working environment with a retained disk and running processes.
Session	One continuing conversation with an Agent, pinned to a Deployment and a Computer.
Turn	One admitted input and its terminal outcome. Turns in a Session run one at a time.
Project and Deployment	A Project holds Environments; a Deployment is an immutable build promoted to be current in one Environment.

From code to a running Session

You define Agents and Computers in TypeScript, build them into a Deployment with the CLI and promote that Deployment in an Environment. Starting an Agent creates a Session and its first Turn. The Session gets a Computer, runs the Agent’s init once and then calls turn for each admitted input in order. Later inputs join the same Session. See Agents and Sessions.

A Turn can write output, ask a person a question and return a JSON result. A Turn is completed only after the Computer’s disk is saved durably. Between Turns, an idle Session can hibernate and resume without rerunning init. See Turns and Durability.

Work can also start from a cron trigger, from Slack or from another Agent through delegation.

Identity and retries

Operations address resources by ID. A Session key lets you find an existing conversation within an Agent; enqueue input using its Session ID to continue it. Creating another Session with an occupied key conflicts. An idempotency key identifies one request so an uncertain retry does not admit the work twice.

Data and credentials

Keep credentials in Secrets. Inputs, results, output, questions, answers and event history are retained application data and must not contain credentials. See Security.