Skip to content

Requirements

A fleet is one coordinator and any number of nodes. The coordinator can also be a node.

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 _oarbank account 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 colima and docker with Homebrew, and Rosetta 2 on Apple silicon; krunkit adds GPU containers (Containers on nodes).

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.

  • 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-setup from 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 _oarbankd on macOS, systemd system units run by oarbankd on 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.app on macOS, /opt/oarbank/coordinator on Linux, and C:\Program Files\Oarbank\Coordinator\package on Windows, with oarbank on the PATH. Python and uv are bundled.
  • State and keys: the coordinator’s state is in /Library/Application Support/Oarbank/coordinator on macOS, /var/lib/oarbank/coordinator on Linux and C:\ProgramData\Oarbank\coordinator on Windows, readable only by the service. Your owner signing keys stay in your home: ~/Library/Application Support/Oarbank/keys on macOS, ${XDG_CONFIG_HOME:-~/.config}/oarbank/keys on 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.

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.