Runners overview

CommandChain splits into two halves. The control plane coordinates: it holds your tasks, meetings, agents, and history, and it decides what should happen next. A runner executes: it is the process that checks out a repository, launches a coding agent against it, and reports back what happened.

Everything that touches a real system happens on a runner. That is deliberate. Your code, your git credentials, and your build toolchain never have to leave the machine you already trust with them.

What a runner does during a run

1. Claims a run the control plane has dispatched to it.
2. Prepares a workspace: clones or updates the repository, checks out the task branch.
3. Builds a boundary for the attempt and starts the coding agent inside it.
4. Streams progress, logs, and cost back to the control plane while the agent works.
5. Commits and pushes the result, and reports the commit back.

The agent never runs outside that boundary. If a machine cannot enforce one, the runner refuses to run an agent there at all. See the security model.

Managed or self-hosted

	Managed runner	Self-hosted runner
Where it runs	Infrastructure we operate	A machine you own
Setup	Create it from the app	One command, no administrator rights
Boundary	Container, applied before the process starts	Landlock (Linux) or Seatbelt (macOS), applied per attempt
Reaches private networks	No	Yes, whatever the machine can reach
Uses your local toolchain	No	Yes, including your git credentials
Coding-agent login	Uploaded once with creds push	Uploaded the same way, and reused locally

Pick a self-hosted runner when the work needs something only your machine has: a private repository over your SSH agent, a VPN-only service, a specific toolchain version, or a large checkout you do not want to re-clone.

Pick a managed runner when you want nothing to install, when the machine that would host it is a Windows box, or when you want work to keep moving while your laptop is closed.

Both kinds can coexist in one workspace. A run is dispatched to whichever runner suits it.

Platform support

Platform	Self-hosted	Boundary	Requirement
Linux (x86-64 and AArch64)	Supported	Landlock	Kernel 5.13 or newer, with Landlock in the active security-module stack
macOS (Intel and Apple Silicon)	Supported	Seatbelt	/usr/bin/sandbox-exec, which ships with macOS. The install command must be run in a graphical login session
Windows	Not available		Use a managed runner

Windows hosts a managed runner, never a self-hosted one

There is no unprivileged Windows sandbox this project has proven, and a runner that cannot contain a coding agent is not one we will install on your machine. The installer stops with that message rather than installing a weaker runner.

What is on your machine afterwards

Everything lands inside your home directory, and nothing needs a package manager, a language runtime, or a privileged install.

What	Where
The program	~/.local/bin/commandchain-runner
Pairing credential and workspaces	~/.commandchain (mode 0700)
The service	~/.config/systemd/user/ on Linux, ~/Library/LaunchAgents/ on macOS
Logs	~/.local/state/commandchain-runner/ on Linux, ~/Library/Logs/commandchain-runner/ on macOS

Next steps

• Install a runner: the one-liner, and what it does.
• Pairing: approving a runner in the browser.
• The security model: the boundary, in detail.
• Coding agents: which tool actually does the work.