Remote engines
Keep the panel on your laptop and run the agents on a machine that never sleeps.
Agents on your laptop stop when your laptop sleeps. Komrad can run them on a remote machine instead. The panel stays on your laptop and looks the same. The engine moves: the server, the database, and every agent’s terminal.
Komrad’s own team works this way. Each person has a remote engine of their own.
Connecting#
An engine is a small config file on your laptop in ~/.config/komrad/engines/, named after the engine. Its [connection] table names the engine’s url, the HTTPS address it answers on, and the panel does everything on the engine through the API there:
[connection]
url = "https://komrad.tail1234.ts.net/you"
Every engine sits behind the same control plane, so each address shares a name and ends in the engine’s path. An engine on a tailnet needs Tailscale running on your laptop with DNS on.
Signing in#
The engine lets in only people an operator granted access. Sign in once per engine, with the email the operator granted:
komrad login --engine dev
A browser opens at the engine’s identity provider. You can also open the panel and press enter at its sign-in screen. The panel stays signed in after that. It asks again after a long time away, or after your access ends. Komrad’s engine covers how the sign-in works and what the engine checks.
Switching engines#
komrad open opens your laptop’s panel. komrad open --engine dev opens the engine named
dev, and --engine local names your laptop.
Every panel shows which engine it is on at the top of the sidebar, with the release its server runs, or its commit when it doesn’t run a release. The dot beside it is green while the engine’s heartbeat arrives, and red once it stops. The message it flashes beside the engine says why, and ctrl+g opens the whole message with what to do.
To move to another engine, close the panel and run komrad open --engine with that engine’s name.
GitHub on your engine#
Your engine’s agents act as you on GitHub, with the same access you have on your laptop. The first time they need GitHub, the panel shows a code and a GitHub address. Enter the code there once.
Attaching to an agent#
An agent’s terminal on the engine is streamed to your panel, and komrad terminal AGENT does the same in any terminal. The agent’s window takes the size of the terminal attached to it, so it fills the stage and follows it when you resize.
The terminal in an agent’s menu works the same way. It opens a shell on the engine, in the agent’s directory there, and streams it to the pane below the stage.
One exception is a window someone fixed at a size on the engine itself, for example by opening a panel there, which runs tmux’s resize-window and sets the window’s window-size to manual. That window keeps its size wherever it attaches, so a smaller terminal crops it and a larger one leaves blank space around it.
Editing files on the engine#
Every agent’s files live on the engine. komrad login writes an SSH host for the engine in ~/.ssh/komrad/, named komrad- and the engine’s name, such as komrad-dev. SSH to that host travels through the engine’s API on your sign-in, so the engine doesn’t need an SSH port.
To reach the engine from another program, such as ssh or your editor’s remote window, add this line to the top of ~/.ssh/config:
Include ~/.ssh/komrad/*.conf
Then ssh komrad-dev opens a shell on your engine. komrad login prints the line when your ~/.ssh/config lacks it.
Agent CLI logins#
Agents on your engine run a CLI that has to be logged in. Do that once in a shell on the engine: start the CLI and log in. The login lives on the engine’s data disk.
Each task also works in a fresh worktree, and the CLI asks whether to trust every directory it has not seen. Turn on trust_launch_dirs for each CLI the engine runs, so komrad answers that question before the agent starts. Without it, every new agent sits waiting at that question.
Dotfiles#
Your engine keeps your home, so clone and install your dotfiles there from a shell, as you would on a new laptop. Git reaches GitHub as you. A .gitconfig in your dotfiles must leave git’s forge proxy and credential helper settings alone, or git stops reaching GitHub. The same .gitconfig must not rewrite GitHub URLs to SSH. Clone repositories with their https URLs.
Project tools#
The engine carries mise but doesn’t carry languages of its own. A repository pins the ones it needs, such as Go and Node, in a mise.toml or .tool-versions, and its workflow names mise install as its setup command. The first task to ask for a version waits while it downloads, which can take a minute or two. Later tasks on your engine reuse the same copy. A repository without either file doesn’t get any languages.
Stopped engines#
An engine costs money every hour, so you can stop it when nobody is using it. You start and stop your engine from the panel, and every engine also stops each night. Your engine is offline while stopped. Stopping keeps the disk, the database and the address. Every agent stops, and you resume the ones you want once it is back. Your schedules don’t run while it is stopped.
This guide covers using an engine. Running komrad remotely covers building one.