Get started
Download
Section titled “Download”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.
Coordinator installers
Section titled “Coordinator installers”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.
Node installers
Section titled “Node installers”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.
Set up a fleet
Section titled “Set up a fleet”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.
-
Install the coordinator package for its operating system and processor. It installs the software without configuring or enrolling the fleet.
-
Open the setup application: Oarbank Coordinator in Applications on macOS or the application menu on Linux (
oarbank-setupalso 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:7400unless 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 youroarbankcommand 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.
-
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.
-
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.pkgsudo oarbank-node join # prompts for the codeWith
sudo, the node runs as a system service under its own_oarbankaccount and starts at boot; the join window offers the same choice as Run as: System service. Withoutsudoit runs while you are logged in.Install the package, then join. Pass the code to the package, or join afterwards:
Terminal window sudo OARBANK_JOIN_CODE='OB2-…' apt install ./oarbank-agent_2.11.1_amd64.deb# or: sudo apt install ./oarbank-agent_2.11.1_amd64.deb && sudo oarbank-node joinUse
dnf install ./oarbank-agent-2.11.1-1.x86_64.rpmon Fedora and RHEL. On a desktop, open Oarbank Node from your applications to paste the code instead. The package creates anoarbankaccount and a systemd service whose jobs run in their own cgroups.Open the MSI. Its join page takes the code; leave it empty to join later from Oarbank Node in Start. Use the
arm64MSI on ARM64 PCs. Tick Run container jobs for modules that run containers (WSL containers; see Requirements).Silently, from an elevated prompt:
Terminal window msiexec /i oarbank-agent-2.11.1-windows-x64.msi /qn JOINCODE=OB2-…The MSI installs the agent as a Windows service, a helper service that enforces each job’s network allowlist, and
oarbank-nodeon the PATH.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, runsudo oarbank-node joinafterwards:Terminal window curl -fsSL https://github.com/roeehrl/oarbank/releases/latest/download/oarbank-install.sh | sudo shOn 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 statusshows where it is. If joining fails, the window andoarbank-node joinsay 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.
-
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
oarbankon the PATH (open a new terminal after installing; on Windows, an elevated prompt):Terminal window oarbank module install <bundle>.mfboarbank module approve <name>@<version>oarbank module enable <name>@<version>oarbank release list # the releases waiting for your signatureoarbank release sign <release> --promote # once per platform it namesThe 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.
Install the module SDK
Section titled “Install the module SDK”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:
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 --helpTo work with the reference module and the examples, clone the repository instead and check the toy module with the conformance kit:
git clone https://github.com/roeehrl/oarbank-sdkcd oarbank-sdkuv sync --group devuv 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.
Use Oarbank with an AI agent
Section titled “Use Oarbank with an AI agent”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:
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.
In a Claude Code session:
/plugin marketplace add roeehrl/oarbank-sdk/plugin install oarbank@codonicFrom a terminal: claude plugin marketplace add roeehrl/oarbank-sdk, then claude plugin install oarbank@codonic.
Check with claude plugin list. Update with claude plugin update oarbank@codonic, or turn on automatic updates
under /plugin, Marketplaces, codonic (they are off by default for marketplaces outside Anthropic’s).
Remove with claude plugin uninstall oarbank@codonic.
codex plugin marketplace add roeehrl/oarbank-sdkcodex plugin add oarbank@codonicRestart Codex, then check with codex plugin list. Update with codex plugin marketplace upgrade codonic and a
restart. Remove with codex plugin remove oarbank@codonic.
Download oarbank-skill.zip from the latest
skill release, then in Claude open
Customize, Skills, +, Upload a skill, and choose the file. Code execution must be on. Upload a
newer zip to update.
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 mewith 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".- How Oarbank works: the coordinator, nodes, join codes, modules, certification, sandboxing, host protection, signing and coordinator moves.
- Requirements: what each computer and the network need.
- Settings and Running modules: tune nodes and groups, and take a module from bundle to running work.
- Command-line reference and Troubleshooting: run and fix a fleet.
- Use Oarbank with an AI agent: let Claude Code, Codex or another coding agent help.
- Build a module in a day: write your own job type.
- The specification and the JSON Schemas: everything a module can rely on.