Skip to content

Get started

The current release is Oarbank 2.11.1, with module SDK 1.8.0. Every file and its checksums are on the release page. First check that your computers meet the Requirements.

Install the coordinator package on the computer that will manage the fleet. Native installers install the software; first-run configuration happens in Oarbank Coordinator (Oarbank Coordinator in Windows Start).

Coordinator computer Installer Checksums
macOS · Apple silicon oarbank-coordinator-2.11.1-macos-arm64.pkg SHA256SUMS-coordinator-2.11.1-darwin-arm64
Windows · x64 oarbank-coordinator-2.11.1-windows-x64.msi SHA256SUMS-coordinator-msi-2.11.1-windows-x64
Windows 11 · ARM64 oarbank-coordinator-2.11.1-windows-arm64.msi SHA256SUMS-coordinator-msi-2.11.1-windows-arm64
Linux · Debian/Ubuntu · x86_64 oarbank-coordinator-2.11.1-linux-amd64.deb SHA256SUMS-coordinator-packages-2.11.1-linux-amd64
Linux · Debian/Ubuntu · arm64 oarbank-coordinator-2.11.1-linux-arm64.deb SHA256SUMS-coordinator-packages-2.11.1-linux-arm64
Linux · Fedora/RHEL · x86_64 oarbank-coordinator-2.11.1-linux-amd64.rpm SHA256SUMS-coordinator-packages-2.11.1-linux-amd64
Linux · Fedora/RHEL · arm64 oarbank-coordinator-2.11.1-linux-arm64.rpm SHA256SUMS-coordinator-packages-2.11.1-linux-arm64

Compare your downloaded file’s SHA-256 with the entry for that exact filename in its checksum file; a checksum file may also list other downloads. Coordinator tar archives remain available on the release page for advanced deployment and signed coordinator moves.

Install the node package on every computer that will execute jobs, including the coordinator computer if it will participate.

Node Package Checksums
Mac node · Apple silicon oarbank-agent-2.11.1-macos-arm64.pkg SHA256SUMS-agent-2.11.1-darwin-arm64
Mac node · Intel oarbank-agent-2.11.1-macos-x86_64.pkg SHA256SUMS-agent-2.11.1-darwin-amd64
Linux node · Debian/Ubuntu · x86_64 oarbank-agent_2.11.1_amd64.deb SHA256SUMS-agent-2.11.1-linux-amd64
Linux node · Debian/Ubuntu · arm64 oarbank-agent_2.11.1_arm64.deb SHA256SUMS-agent-2.11.1-linux-arm64
Linux node · Fedora/RHEL · x86_64 oarbank-agent-2.11.1-1.x86_64.rpm SHA256SUMS-agent-2.11.1-linux-amd64
Linux node · Fedora/RHEL · arm64 oarbank-agent-2.11.1-1.aarch64.rpm SHA256SUMS-agent-2.11.1-linux-arm64
Windows node · x64 oarbank-agent-2.11.1-windows-x64.msi SHA256SUMS-agent-2.11.1-windows-x64
Windows node · ARM64 oarbank-agent-2.11.1-windows-arm64.msi SHA256SUMS-agent-2.11.1-windows-arm64

The one-line installers oarbank-install.sh (macOS and Linux) and oarbank-install.ps1 (Windows) pick the right package for the computer and verify it; the Windows Group Policy template is oarbank-agent-2.11.1-windows-admx.zip.

The macOS packages are signed with Developer ID and notarized by Apple. The Windows installers are not code-signed yet: Windows SmartScreen may ask you to confirm before running one you downloaded with a browser.

A fleet is one coordinator and any number of nodes. The coordinator runs on macOS, Linux or Windows and can also be a node itself. Every node, whatever its operating system, reaches the coordinator on one address and port; see Requirements.

  1. Install the coordinator package for its operating system and processor. It installs the software without configuring or enrolling the fleet.

  2. Open the setup application: Oarbank Coordinator in Applications on macOS or the application menu on Linux (oarbank-setup also works), or Oarbank Coordinator in Windows Start. Click the menu bar or tray icon and choose Open web app. A Linux desktop without a tray host shows these controls in a small window. Launch the companion as your ordinary user, the one who will own the coordinator. Finishing setup or recovering stopped services asks for an administrator once (the administrator prompt on macOS, polkit on Linux, UAC on Windows); opening the running console requires none.

    Select a LAN or tailnet IP assigned to this computer that the nodes can reach, one that exists before anyone logs in. Enter your administrator name and password (at least 12 characters), confirm the password, and submit. This starts the services (the system asks for an administrator once) and creates the account. Scan the displayed QR code with your authenticator app and verify its six-digit code. The wizard creates and pins primary and backup owner signing keys in your own home; copy the backup key to secure offline storage. When setup finishes, it opens the console.

    The console stays local at http://127.0.0.1:7400 unless you configure remote access. On every OS the coordinator is a system service under an account of its own: it starts with the computer, before anyone logs in, and keeps running when you log out. You join its owners’ group, which lets your oarbank command reach it without a token. See The coordinator service for where it lives and how to add another owner.

    If you close the wizard before verification, choose Open web app again. The saved address and administrator name are shown; enter your original password to continue. Existing accounts and signing keys are preserved. Completed setup opens the normal console login.

    The menu also shows the coordinator’s status. On macOS its one setting, Show Oarbank Coordinator in the menu bar, is on after the first launch (the app opens at login); Hide from Menu Bar (⌘Q) turns it off and quits the app. On Windows and Linux, Preferences has Start automatically at sign-in, and Quit closes the app. Either way the coordinator keeps running.

  3. Add a machine. In the console, open Fleet and choose Add machine…. Give the computer a name (optional), say whether it is one machine or many, and create the code. The console shows the join code once, with a Copy button, and under it the installer to download and the commands to run for each operating system, with the code already filled in. A code names your coordinator’s addresses and pins its identity, so a node checks it is talking to your coordinator before it sends anything. A code for one machine works once, approves the machine at once, and expires after 4 hours unless you chose otherwise.

  4. Install the node package and join. The package installs the node and asks nothing; joining is one step after it, the same on every operating system.

    Open the package for your Mac’s chip. When Installer finishes, Oarbank Node opens in the menu bar at its join window: paste the code and choose Join. The window checks your network and the coordinator, asks for an administrator (“Oarbank Node wants to join this Mac to an Oarbank fleet.”), and shows the machine until it is approved and connected.

    Over SSH or in a script, install the package, then join (the code is read hidden, never typed on the command line):

    Terminal window
    sudo installer -pkg oarbank-agent-2.11.1-macos-arm64.pkg -target / # an Intel Mac: oarbank-agent-2.11.1-macos-x86_64.pkg
    sudo oarbank-node join # prompts for the code

    With sudo, the node runs as a system service under its own _oarbank account and starts at boot; the join window offers the same choice as Run as: System service. Without sudo it runs while you are logged in.

    Or in one line, which downloads this release’s package for the computer, checks its SHA-256 and installs it. The console’s Add machine page gives this command with the code filled in (OARBANK_JOIN_CODE), and then it joins too; without a code, run sudo oarbank-node join afterwards:

    Terminal window
    curl -fsSL https://github.com/roeehrl/oarbank/releases/latest/download/oarbank-install.sh | sudo sh

    On Windows: irm https://github.com/roeehrl/oarbank/releases/latest/download/oarbank-install.ps1 | iex (it asks for the code, hidden).

    The node enrolls with a key it generates and keeps, then installs its release, runs each module’s doctor and golden jobs, and starts taking work. oarbank-node status shows where it is. If joining fails, the window and oarbank-node join say which check failed and why; see Adding machines.

    The coordinator’s download holds only the coordinator: for the coordinator’s computer to run jobs too, install the node package on it as well and join it with a code of its own. For many machines (MDM, Intune, Ansible, images), create a code for many machines and hand it out through managed policy; see Adding machines. The coordinator never connects to nodes itself.

  5. Add modules. Oarbank ships no job module of its own: each job type is a module, delivered as a bundle. You install a bundle, approve what its sandbox may reach, enable it, and sign each platform’s release. The coordinator package puts oarbank on the PATH (open a new terminal after installing; on Windows, an elevated prompt):

    Terminal window
    oarbank module install <bundle>.mfb
    oarbank module approve <name>@<version>
    oarbank module enable <name>@<version>
    oarbank release list # the releases waiting for your signature
    oarbank release sign <release> --promote # once per platform it names

    The module’s page then shows Getting this module running, a checklist of what is still missing; see Running modules.

Updating and removing covers updates, moving the coordinator and uninstalling; coming from 2.9 or 2.8, read Upgrading first. If something does not work, see Troubleshooting. The full install guide, with system scope and building the packages, is docs/install.md in the core’s repository.

To build your own job types, install the module SDK (oarbank-sdk, Apache-2.0). You need Python 3.12 or newer, on macOS, Linux or Windows. It is not on PyPI yet; install it from its repository:

Terminal window
uv pip install "git+https://github.com/roeehrl/oarbank-sdk@v1.8.0" # or: pip install "git+https://github.com/roeehrl/oarbank-sdk@v1.8.0"
oarbank-sdk --help

To work with the reference module and the examples, clone the repository instead and check the toy module with the conformance kit:

Terminal window
git clone https://github.com/roeehrl/oarbank-sdk
cd oarbank-sdk
uv sync --group dev
uv run oarbank-sdk conform examples/toy # must end with "0 failed"

The conformance kit runs your module’s runner as each platform would, so you can test a module before you install it on a fleet. Build a module in a day builds a complete module step by step.

The Oarbank skill lets a coding agent (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and others) install, run, troubleshoot and build modules for Oarbank. It is short on purpose: it tells the agent to read these docs live, check which versions you run, and ask you before it changes anything. Elevated steps, passwords and join codes stay with you. The skill is Apache-2.0, in roeehrl/oarbank-sdk.

With Node.js installed, this asks which of your agents to add it to:

Terminal window
npx skills add roeehrl/oarbank-sdk --skill oarbank -g

-a claude-code -a codex picks the agents instead; without -g it installs into the current project only. Check with npx skills list -g, update with npx skills update -g, remove with npx skills remove oarbank -g. Updates are never automatic.

To pin a version, add the skill’s release tag: /plugin marketplace add roeehrl/oarbank-sdk#skill-v1.0.0 in Claude Code, --ref skill-v1.0.0 for Codex. Read SKILL.md before installing: it is short and has no scripts.

Without the skill, paste this into any agent:

Read https://docs.codonic.dev/oarbank/llms.txt and the pages it lists that fit my question, and use them to help me
with Oarbank. Check which Oarbank version I run first, and ask me before changing anything.

In a module’s repository, add these lines to AGENTS.md or CLAUDE.md so every agent working on it knows where the contracts are:

This is an Oarbank module. Oarbank docs: https://docs.codonic.dev/oarbank/llms.txt (Markdown pages;
build/tutorial.md, reference/manifest.md, spec/sandbox.md). Run `oarbank-sdk check .` and `oarbank-sdk conform .`
before bundling; conform must end with "0 failed".