Architecture
Orbit has one Gateway that owns all fleet state. Clients ask the Gateway for changes, and the Gateway applies them to Nodes. Nodes run applications and report what they observe.Components
Orbit consists of these components. Each one lives in its own project in the repository.Trust
Every Node joins one private WireGuard network. The Gateway identifies each caller by the WireGuard address its request comes from. A directed access grant decides which Nodes that caller may act on. Humans and agents use the same API with the same rules. Node agents report through their own endpoints with a per-Node secret. The Gateway is private and reachable only over WireGuard. Public traffic enters only through Nodes with theingress role, and the Gateway never shares a Node with ingress.
Nodes and roles
A Node is a machine in the WireGuard fleet. Ubuntu 26.04 Nodes run Orbit service roles. macOS Nodes support selected tools through their existing SSH account and package managers, with no service roles. Tools do not require a role. Node provisioning describes macOS enrollment. On Ubuntu, services run natively under systemd. Container Processes and themetrics role’s Prometheus and Grafana run in Docker. macOS tool support does not enable these runtimes.
A role refuses a Node that holds a conflicting role. For example, the
gateway role never shares a Node with app-dev, app-prod, database, analytics, or ingress. Node provisioning lists every conflict.
Paths
Control. A human or agent runs a CLI command or an MCP tool. The request reaches the Gateway over WireGuard. The Gateway checks the caller, records the request, and applies the change to each Node over one shared SSH connection per Node. Traffic. A Route gives an Instance a domain on one Node or one Cluster. Private requests arrive over WireGuard. Public requests enter throughingress. In a Cluster, router sends each request to the Node that runs the Instance. Caddy serves the Instance there. See Routes.
Observation. Node agents publish state to the websocket Node. The Gateway keeps a view of it, and the web app shows it live. Doctor compares the state the Gateway expects with each Node’s actual state and reports every difference without changing anything.
Tasks. With the Tasks extension enabled, the Gateway provisions a task workspace on an app-dev Node. It runs coding agents there one subtask at a time and checks each handoff with the Project’s task check. At the end, it opens a pull request through the GitHub App. See Tasks.