Requirements
A fleet is one coordinator and any number of nodes. The coordinator can also be a node.
At a glance
Section titled “At a glance”| Versions | Architectures | |
|---|---|---|
| macOS node | macOS 15 or later | Apple silicon, Intel |
| Linux node | systemd, glibc 2.39+, Linux 6.2 or later | x86_64, arm64 |
| Windows node | Windows 10 version 1809 or later, Windows 11 | x64, ARM64 |
| Coordinator on macOS | macOS 15 or later | Apple silicon |
| Coordinator on Linux | systemd, glibc 2.39+, Linux 6.2 or later | x86_64, arm64 |
| Coordinator on Windows · x64 | Windows 10 version 1809 or later, Windows 11, Windows Server 2019 or later | x64 |
| Coordinator on Windows · ARM64 | Windows 11 (bundled x64 Python under emulation) | ARM64 |
- macOS 15 or later on Apple silicon or Intel. There is one package per architecture.
- Installer: a
.pkg, signed with Developer ID and notarized by Apple, installed by hand or through MDM. Administrator rights are needed to install it. It adds Oarbank Node to the menu bar for joining, and a small helper that asks for an administrator when the node joins or leaves as the system service. - Service: joined as the system service (
sudo oarbank-node join, or System service in the join window), the agent runs under its own_oarbankaccount and starts at boot, before anyone logs in. Joined for the user, it runs as a LaunchAgent while that user is logged in. - Sandbox: Seatbelt. Each job runs in its own process group.
- Host protection: the memory guard and caps (settings), plus the owner’s rules (named apps and processes, someone using the computer) and back-off for heat and battery.
- Containers, for modules that use them, run in a Colima profile that the agent creates and starts itself.
Install
colimaanddockerwith Homebrew, and Rosetta 2 on Apple silicon; krunkit adds GPU containers (Containers on nodes).
-
x86_64 or arm64, with glibc 2.39 or newer and systemd. Published 2.11.1 Linux binaries are built and checked on Ubuntu 24.04.
-
Linux 6.2 or later for the module sandbox (Landlock and seccomp). Newer kernels enforce more:
Kernel What the sandbox enforces 6.2 or later files, no network, the GPU, no execution of writable files 6.7 or later also the network allowlist, and no loopback or link-local access 6.12 or later also local IPC (full parity with the other platforms) A node reports what its kernel cannot enforce, and work that needs it is not placed there. Unrestricted network access (
egress-any) is not available on Linux nodes. -
Installer: a
.debor an.rpm. Root is needed to install it. The package creates anoarbankaccount and a systemd service with a delegated cgroup, so each job runs in its own cgroup v2 leaf. -
Host protection: the memory guard and caps (settings), plus the owner’s rules (named apps and processes, someone using the computer: a desktop session, or a terminal session with recent input) and back-off for heat and battery. On a Wayland desktop the app in front cannot be read.
-
Containers, for modules that use them, run in rootless Podman when it is installed (the
oarbankaccount then needs subordinate user and group ids), otherwise in Docker Engine.
- Windows 10 version 1809 or later, or Windows 11, on x64 or ARM64. There is one MSI per architecture.
- Installer: an
.msi. Administrator rights are needed to install it. The MSI is not code-signed yet, so Windows SmartScreen may ask you to confirm when you run one you downloaded with a browser. - Services: the agent runs as a Windows service under its own virtual account. The MSI also installs a helper
service,
OarbankHelper, that runs elevated and limits each job’s network access to its own allowlist proxy. - Sandbox: an AppContainer per module. Each job runs in its own Job Object.
- Host protection: the memory guard and caps (settings), plus the owner’s rules (named apps and processes, someone using the computer) and back-off on battery.
- Containers, for modules that use them, run in a WSL containers session that the agent owns (a VM of its
own). They need Windows 10 version 2004 or later, WSL 2.9.3 or later and the Virtual Machine Platform: install the MSI with
CONTAINERS=1, or runoarbank-agent containers installas an administrator, then restart.oarbank-agent containers doctorsays what is missing. A Windows node runs container images of its own architecture.
Modules can need more than the operating system: a JDK, a tool, a GPU. A module asks for host tools by name and version, and each node reports which installations it has (Host tools); each module’s doctor checks the rest. A node that lacks something a module needs is reported as unable to run that module’s jobs that need it, rather than given them. The machines GPU detection and GPU containers have been checked on are listed in Hardware compatibility.
The coordinator
Section titled “The coordinator”- A computer that stays on: a Mac with Apple silicon and macOS 15 or later, a Linux machine (x86_64 or arm64) with systemd, glibc 2.39 or newer and Linux 6.2 or later, or Windows x64 with Windows 10 version 1809 / Server 2019 or later. A Windows ARM64 coordinator needs Windows 11, because only Windows 11 provides x64 emulation for its bundled Python. Intel Macs can run a source checkout; the native Mac coordinator package is Apple silicon only.
- First-run setup: install the native coordinator package, then open Oarbank Coordinator (Applications on macOS, the application menu on Linux, Start on Windows) and choose Open web app from its menu bar or tray icon (or the Linux fallback window). Package installation needs administrator privileges and installs software only. The wizard configures the reachable IP, administrator, authenticator by QR scan and primary/backup owner signing keys; starting the services asks for an administrator once. On macOS and Linux, open it as the ordinary user who will own the coordinator. Linux desktop packages include GTK 3 and Python GObject bindings for the companion; headless computers can run
oarbank-setupfrom a terminal. - Background services: a system service on every OS, under an account of its own, starting at boot before anyone logs in: launchd daemons run by
_oarbankdon macOS, systemd system units run byoarbankdon Linux (no lingering needed), and two Windows services under separate virtual accounts, with delayed automatic start and recovery after a crash. The agent address must exist before anyone logs in. See The coordinator service. - Installed software:
/Applications/Oarbank Coordinator.appon macOS,/opt/oarbank/coordinatoron Linux, andC:\Program Files\Oarbank\Coordinator\packageon Windows, withoarbankon the PATH. Python and uv are bundled. - State and keys: the coordinator’s state is in
/Library/Application Support/Oarbank/coordinatoron macOS,/var/lib/oarbank/coordinatoron Linux andC:\ProgramData\Oarbank\coordinatoron Windows, readable only by the service. Your owner signing keys stay in your home:~/Library/Application Support/Oarbank/keyson macOS,${XDG_CONFIG_HOME:-~/.config}/oarbank/keyson Linux. Native uninstall retains this data (Updating and removing). - Its module processes are sandboxed too, with the same backend as on a node of that operating system. A coordinator on an operating system without a sandbox backend refuses to start module processes.
- It can also be a node: install the node package on the same computer.
Network
Section titled “Network”Oarbank needs no particular network. A fleet works the same on one LAN, over Tailscale or ZeroTier, or over any other VPN, and nodes on different networks can share one coordinator as long as they can reach it.
- Nodes reach the coordinator on one address and one port:
7443/tcp. This is the only port a node needs, and the only one the coordinator needs to accept from other computers. The connection is TLS with a client certificate on both sides. - The coordinator never connects to nodes. Nodes open every connection, so they need no open inbound ports, and nodes behind NAT work.
- Addresses can change. The coordinator is authenticated by the certificate authority its join codes pin, not by its host name, so a node can use any address that reaches it: a LAN address, a VPN address or a local network name.
- Discovery is optional. On a local network, the coordinator announces itself and a node can find its address that way, but join codes already carry the coordinator’s addresses.
By default, everything else on the coordinator listens on loopback only:
| Port | What | Reachable from |
|---|---|---|
7443/tcp |
the agent API that nodes use | the network |
7400/tcp |
the console | the coordinator only |
7401/tcp |
the admin API that the console and the CLI use | the coordinator only |
7402/tcp |
the origin that serves module console frames | the coordinator only |
To use the console from another device, put it behind a reverse proxy that terminates TLS for a name you control,
and add that name to the console’s allowed host names (the console_hosts setting). Passkeys need such a name;
password and TOTP sign-in work either way.
Jobs themselves have no network access unless you grant it to their module. A granted module reaches only the hosts on its allowlist, through the agent’s proxy on the node.