Install on AWS

The Terraform module in deploy/terraform/aws runs Hyperbeam on a single EC2 instance. The instance runs k3s, a small Kubernetes distribution, and you install the same Helm chart as on any other cluster.

This is a starting point, not a managed service. It keeps the bill low by using one instance and no managed Kubernetes, database, NAT gateway or load balancer. Read it, change it, and see Limits for when to move on.

What it creates

Cost

On-demand prices in us-east-1, in US dollars for a 730-hour month. Check AWS pricing for your region.

A one-year Compute Savings Plan takes about 30% off the instance. Model usage is billed by your model provider and is not included.

Each sandbox asks for 0.25 CPU and 512 MiB, and can use up to 2 CPUs and 4 GiB. As a rule of thumb the default runs about 6 sessions at once and the small size about 3. Set max_sessions to match; other sessions wait in a queue.

Before you start

• An AWS account, and the AWS CLI signed in to it, with the Session Manager plugin.
• Terraform 1.5 or later, or OpenTofu.
• Docker, kubectl and Helm 3.
• A domain name for Hyperbeam, such as hyperbeam.example.com.

Run every command on this page from the root of the repository.

1. Create the infrastructure

Write your settings to deploy/terraform/aws/terraform.tfvars:

domain     = "hyperbeam.example.com"
acme_email = "[email protected]"

# For the small size:
# instance_type  = "t4g.large"
# root_volume_gb = 60
# max_sessions   = 3

variables.tf lists the other settings. The AWS region comes from your AWS CLI configuration or AWS_REGION.

terraform -chdir=deploy/terraform/aws init
terraform -chdir=deploy/terraform/aws apply

The module keeps its state in a local file, deploy/terraform/aws/terraform.tfstate. Keep that file, or configure a remote backend before you apply.

Save the outputs the next steps use:

tf() { terraform -chdir=deploy/terraform/aws output -raw "$1"; }
export AWS_REGION=$(tf region)

2. Point the domain at the instance

Create an A record for your domain with the address from tf public_ip. If the domain is in Route 53, set route53_zone_id in terraform.tfvars instead and the module creates the record.

Traefik requests the certificate when the chart is installed, so the record must resolve by step 5.

3. Build and push the images

This guide keeps the images in the registry Terraform created, so build them from the repository. (The published images work too, if you would rather not build.) t4g instances are arm64, so images must be built for linux/arm64. tf image_platform prints the platform for your instance type.

aws ecr get-login-password | docker login --username AWS --password-stdin "$(tf registry)"

PREFIX=$(tf image_prefix)
PLATFORM=$(tf image_platform)
docker build --platform $PLATFORM -f deploy/docker/Dockerfile --target server -t $PREFIX/server:0.1.0 .
docker build --platform $PLATFORM -f deploy/docker/Dockerfile --target runner -t $PREFIX/runner:0.1.0 .
docker build --platform $PLATFORM -f deploy/docker/Dockerfile.harness --target claude-code -t $PREFIX/harness-claude-code:0.1.0 .

docker push $PREFIX/server:0.1.0
docker push $PREFIX/runner:0.1.0
docker push $PREFIX/harness-claude-code:0.1.0

To use other agents, add them to harnesses in terraform.tfvars, such as harnesses = ["claude-code", "codex"], apply again, and build those targets too.

4. Connect to the cluster

The instance installs k3s on first boot, which takes a few minutes, then stores its kubeconfig in an SSM parameter. Fetch it:

aws ssm get-parameter --name "$(tf kubeconfig_parameter)" --with-decryption \
  --query Parameter.Value --output text > hyperbeam-kubeconfig
chmod 600 hyperbeam-kubeconfig

If the file contains only pending, k3s is not up yet. Wait a minute and fetch it again.

The Kubernetes API is not open to the internet. In a second terminal, forward it to your machine, and leave this running while you use kubectl or helm:

aws ssm start-session --target "$(tf instance_id)" \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["6443"],"localPortNumber":["6443"]}'

Back in the first terminal:

export KUBECONFIG=$PWD/hyperbeam-kubeconfig
kubectl get nodes

5. Install the chart

The module writes the chart values for you: the image repositories, the KMS key, the public URL and the ingress.

tf helm_values > hyperbeam-values.yaml

helm install hyperbeam deploy/helm/hyperbeam --namespace hyperbeam --create-namespace \
  -f hyperbeam-values.yaml

kubectl -n hyperbeam rollout status deploy/hyperbeam

Do not set masterKey. The values name the KMS key instead.

6. Open the UI

Open https://hyperbeam.example.com. The first request can take up to a minute while Traefik gets the certificate. The first person to sign up creates the team and becomes its owner.

Then open Settings → Harnesses and set each harness profile’s image to the one you pushed, such as PREFIX/harness-claude-code:0.1.0. Continue with Set up a team.

Update to a new build

Build and push the images with a new tag, as in step 3. Then, with the port forward running:

helm upgrade hyperbeam deploy/helm/hyperbeam --namespace hyperbeam --reset-then-reuse-values \
  --set image.tag=NEW_TAG --set agents.runnerImage.tag=NEW_TAG

Running sessions reconnect when the new control plane starts.

To change the instance size, change instance_type and apply. Terraform stops the instance, resizes it and starts it again. Keep the same architecture, or rebuild the images for the new one.

Backups and recovery

Postgres data and the TLS certificate are on the data volume. AWS takes a snapshot of that volume every day and keeps the last 7 (snapshot_retention_days).

Snapshots are taken while Postgres is running, and can be up to a day old. For a backup you can restore anywhere, also dump the database:

kubectl -n hyperbeam exec statefulset/hyperbeam-postgres -- \
  pg_dump -U hyperbeam hyperbeam > hyperbeam-backup.sql

A restored database is readable only with the same KMS key.

Limits

• One instance, one availability zone. If the instance fails, Hyperbeam is down until it comes back. For a database with standby and point-in-time recovery, create an RDS instance and set database.url and postgres.enabled=false in the chart.
• It grows by instance size. For more sessions than one instance holds, install the chart on a multi-node cluster such as EKS. See Install on Kubernetes.
• The instance role is shared by the node. The server pod gets its KMS access from the instance’s IAM role. The chart’s NetworkPolicy keeps sandboxes away from the instance metadata service, so do not remove that policy.

Remove it

helm uninstall hyperbeam --namespace hyperbeam
terraform -chdir=deploy/terraform/aws destroy

Terraform refuses to delete the data volume. To delete it too, remove the prevent_destroy block from aws_ebs_volume.data in main.tf and run destroy again. Snapshots already taken are kept until you delete them, and the KMS key is deleted after 30 days.

Next steps

• Set up a team: invite people and connect GitHub.
• Configuration: every server setting, and the chart values that set them.
• Security model: what the sandbox can and cannot reach.