Overview
Self-hosted Helmr runs in your AWS account with your own database, dispatch queue, object storage, secrets, OAuth login, control plane, dispatcher, and workers.
Self-hosted deployments use the same organization, project, environment, deployment, worker, runtime, and run model as managed cloud. The self-hosted path is operated as a single organization: initial setup requires a setup token and creates the only organization for that environment. After setup, the control plane, dispatcher, workers, API, and database model follow the same architecture.
The deployment has these runtime components:
| Component | Responsibility |
|---|---|
| Control plane | Serves the web UI and API, stores run state in PostgreSQL, authenticates users, coordinates workers, and records logs/events. |
| Dispatcher | Reconciles runnable work into the Redis/Valkey dispatch path and sweeps expired executions. |
| Workers | Poll the control plane, materialize writable workspaces, build task images, run tasks in Firecracker guests, stream events, and create or restore checkpoints. |
AWS infrastructure provides the shared dependencies:
- Amazon RDS for PostgreSQL stores orgs, auth state, projects, sessions, runs, workers, waits, stream records, tokens, metadata, checkpoints, and events.
- Cluster-mode disabled ElastiCache Valkey/Redis backs the dispatch queue used by
HELMR_REDIS_URL. - S3 stores source bundles, runtime artifacts, and encrypted checkpoint objects.
- AWS Secrets Manager stores database, auth, OAuth, worker, and encryption secrets.
- ECS Fargate runs the control, dispatcher, and migration tasks.
- EC2 Auto Scaling runs worker instances when task execution is enabled.
Use this sequence for a new environment:
- Choose the AWS deployment profile.
- Create the OAuth app and collect the non-secret client ID.
- Configure non-secret values and create the base infrastructure.
- Populate Secrets Manager.
- Run database migrations.
- Start the control and dispatcher services.
- Add workers when you need actual run execution.
- Verify a run from the CLI or UI.
The control plane can run without workers for login, deployments, API keys, and run inspection. Workers are required once runs need to execute code.