How does BranchRunner run in a self-hosted environment?
This reference architecture describes the published self-hosted operating model for BranchRunner’s coding-agent orchestration: what runs where, the ports and protocols involved, how work is scheduled, and what happens when a component fails. It is a reference, not a release-ready installation guide.
Three planes, one boundary that matters
The control plane decides and records. Runtime workers execute. External providers are reached deliberately, per run, under credentials you supply. Code and prompt context only cross that last boundary when a session sends them.
What does the reference architecture describe?
It describes the intended self-hosted control plane, runtime worker, workspace and external-provider boundaries. It is a reference model, not a production installation guide.
Where do coding agents execute?
The published model places execution in isolated workspaces on runtime workers rather than on the control plane.
What data boundaries should we evaluate?
Evaluate repository access, credentials, provider context, workspace egress, evidence retention and operator responsibilities for your environment.
Can we deploy it today?
No released artifact, supported-host matrix, or tested quickstart is published here. Do not treat the reference architecture as a deployment instruction.
What happens when a run fails?
The intended model retains task context and evidence for review; exact retention and recovery scope must be confirmed for a proposed deployment.
Ports, protocols and directions
Workers need no inbound ports. Every worker-to-control-plane connection is outbound, which is what makes on-premise and private-network workers straightforward.
Scheduling and reservation
A run is matched to a worker once and holds that slot for its whole life, including while it waits for a person. This keeps the workspace warm and the reproduction available, at the cost of occupied capacity.
Workspace lifecycle
Data model and retention
Four objects, one audit stream. Everything the platform shows hangs off one of these, and each has its own retention rule.
Objective, requirements ledger, conversation, owner, source reference.
Plan, steps, approvals, budget consumption, outcome, audit events.
Worktree, containers, volumes, preview URL, egress rules.
Role, provider, permissions, steps, tool calls, tokens and spend.
Diffs, check output, preview results, exported logs, approval records.
Approvals, tool calls, secret reveals, policy decisions, config changes.
What happens when something fails
The run is marked failed with everything exported so far. The task is intact and the next attempt can start on another worker.
Workers reconnect and resume reporting. Running sessions continue; nothing is lost because state lives in the database.
The run stops before implementation, keeps the container logs, and names the service and port that failed.
The session retries with backoff, then raises an attention request rather than silently degrading to a worse model.
The run ends, the diff and evidence so far are retained, and the owner is notified with the remaining requirements.
The run returns to implementation with the finding attached, keeping its plan, workspace and history.
Scaling and sizing
Concurrency is the unit you buy hardware for. A run occupies one slot from provisioning to approval, so review latency shows up as capacity cost.
High availability
Run several application instances behind your load balancer, with a managed or replicated database. Losing an instance does not stop a run.
Capacity is redundant by count. Runs on a lost worker fail with their evidence and are retried on another.
The database and evidence store are what you back up. Workspaces are disposable by design and are not part of recovery.
Share future architecture requirements
Register interest in future organizational deployment options and tell us which worker, network and retention constraints matter.