Administering the engine

This guide is for whoever runs the remote engine. Using one that exists is covered in running komrad remotely. Everything here runs from a komrad checkout as a mise task, with AWS credentials in your environment.

What gets built

The engine is one machine on AWS with a separate data disk and a managed Postgres. The machine is disposable. Everything that matters lives on the disk or in the database: conversations, worktrees, komrad’s config, and the agent CLIs’ logins. So the machine can be switched off or rebuilt without losing work.

The engine pushes code as a GitHub App rather than as you. The App’s key is kept in AWS Secrets Manager and copied into memory at boot, so it never touches the disk.

Standing one up

Do these in order.

Get an AWS account with a named profile, an S3 bucket for Terraform’s state, and an SSH key used for nothing else.

Build the machine image with mise run packer:build. It prints an image id at the end.

Register a GitHub App with no webhook, installed only on the repositories the engine should work in, with read and write on contents, pull requests, issues and workflows. Store its private key in Secrets Manager as komrad/github-app before the next step, so the first boot finds it.

Copy the two example files in infra/engine and fill them in: your account, region, the image id, your SSH key, and the addresses allowed in over SSH. Fill in the github_* values too, which let GitHub Actions deploy.

Run mise run infra:engine:init and mise run infra:engine:apply. It prints the engine’s address.

Get a shell with mise run remote:connect and add the [github_app] table to komrad’s config with your App’s id, its installation id and the key’s path. komrad github token should print a token. Then connect the engine’s forge through the App.

Finally, clone the repositories agents will work in onto the data disk, point your panel at the engine, and sign the agent CLI in.

Keeping it up to date

Publishing a release deploys it to the engine. A deploy restarts the service but leaves the agents running. You can also deploy by hand with mise run remote:deploy.

The machine image changes rarely. Building one from the Actions tab records it without applying it. mise run remote:reimage applies it, which replaces the machine and stops every agent. It names them and asks first.

Keeping the bill down

mise run remote:stop switches the machine off and mise run remote:start switches it on. Every agent stops with it, but nothing else is lost. A GitHub Actions schedule does this every night, New York time. The disks and database are still billed while stopped, but the machine is most of the bill.

Tearing it down

mise run infra:engine:destroy removes everything. The database is protected from deletion by default, so turn that off first. A final snapshot is kept.

That is everything a user or an operator needs. How it works starts the guides for anyone curious what is underneath.