Quickstart

Install the CLI first:

curl -fsSL https://helmr.dev/install | bash

Nix users can install the CLI from the project flake:

nix profile install github:helmrdotdev/helmr#helmr

Use Nix when possible so Go, Bun, Buf, PostgreSQL, and infrastructure tooling match CI.

nix develop
nix run .#doctor

Start Local Services

make dev

The dev stack starts a disposable PostgreSQL database when HELMR_DATABASE_URL is not set, runs the control plane, and serves the local web UI at:

http://127.0.0.1:3000/dev/login

Use that URL to create a local owner session and inspect seeded runs.

Create A Task Project

helmr init

This creates package.json, helmr.config.ts, and tasks/hello.ts. A task project must have a default-exported defineConfig({ project, dirs: [...] }); files in those directories are indexed for exported task(...) definitions.

Deploy Tasks

helmr deploy .

Deployment indexes the configured task files, uploads a content-hashed deployment-source archive, and records the current deployment for the configured project and selected environment.

Start A Task

helmr session start hello \
  --payload name=Ada

Remote session starts require a configured control plane and a worker capable of executing the task. If no workspace is supplied, Helmr creates a durable workspace using the deployed task’s sandbox and attaches the new session to it.

Inspect The Run

helmr run list
helmr run get RUN_ID
helmr run logs RUN_ID
helmr run events RUN_ID

If a task is waiting on a token, complete it from an authenticated app or bridge with client.tokens.complete(token, data), or call /api/v1/tokens/{tokenId}/complete with the token’s publicAccessToken bearer. Server-to-server providers can use the callbackUrl returned at token creation time.