Factory splits into two halves: the control plane that decides what to work on, and the agents that do the work in a real checkout. The control plane is yours. Where the agents run is a choice.
Agent Relay 11.3.0 and earlier print the active workspace key from node up
and node status. Upgrade to Agent Relay 11.3.1 or later — confirm with
agent-relay --version. Upgrading closes the key print in
agent-relay node up and agent-relay node status. It is not a guarantee
about credential output from every command in an Agent Relay install. Until
upgraded, run these commands only from a trusted, non-transcribed human
terminal; agents must not run them. To share a live view of a workspace, never
put a workspace key in a URL — use agent-relay observer,
available from 11.8.1.
Local agents
factory start --mode live # --backend internal is the defaultThe control plane and every agent run on one machine, against the checkouts in your clonePaths. It reuses a relay broker already running for your workspace and starts one if there isn't. This is the whole loop on one box — the simplest thing that works.
Remote agents on a fleet
factory start --mode live --backend relayThe control plane still runs on your machine, but agents are placed onto fleet nodes through the hosted engine. Placement picks a live node advertising the capability the work needs; the node runs the agent in its own mapped checkout; the orchestrator detects exits by reconciling its tracked agents against the engine roster.
Use this when the work shouldn't run on a laptop — bigger checkouts, longer builds, machines that stay up.
Bringing a node online
Mint an enrollment token from the Fleet page in the dashboard, then, on the machine:
# once per machine — redeem the token for durable node credentials
agent-relay cloud enroll --token ocl_node_enr_…
# each boot
agent-relay node upagent-relay node up auto-discovers an agent-relay.ts in the working directory, which just re-exports the node definition:
export { default } from '@agent-relay/factory/node';The node reads factory.node.json for its workspaceId, capabilities, and the clonePaths map naming the checkouts it services. Each mapped repo is advertised as a repo:<label> tag so repo-scoped work routes to a node that actually has it. Spawns for unadvertised paths are refused.
Nodes can run any of the supported harnesses — claude, codex, gemini, cursor, droid, opencode, grok, aider.
One control plane per workspace
Run one Factory control-plane host per workspace, with as many execution nodes as you like. Multiple Factory processes on that host are fenced through a shared lock.
Active/active control planes on different hosts are intentionally unsupported: separate local state files can't provide a truthful cross-host fence, so two hosts would both believe they own the same work.
What runs in Cloud today
Cloud is where Factory reports, where fleet nodes enroll and get placed, and where you can host the control plane yourself. Observability — instances, runs, and timelines — plus fleet node enrollment and placement. The @agent-relay/factory/hosted entrypoint runs the complete sweep inside a Cloud worker you own — see Running Factory for that runbook.
What Cloud doesn't do yet is run Factory for you: there is no managed hosted Factory where Agent Relay operates the loop on your workspace. The control plane is something you run — on a machine you choose, or in a Cloud worker you own. A managed hosted Factory is coming soon.