Get started

Not released yet

Oarbank has no public release yet: there are no downloads, and its repositories are not public. Installers for the coordinator and for nodes arrive with the first public release. Until then, the installation steps below are a preview of how setup works, and file names and details may change.

What you can do today

• Learn how it works. How Oarbank works explains the coordinator, nodes, join codes, modules, certification, sandboxing, host protection, signing and coordinator moves.
• Check your computers. Requirements lists what the coordinator and each node need on macOS, Linux and Windows, and what the network needs.
• Read the tutorial for module authors. Build a module in a day builds a complete module step by step. The module SDK (oarbank-sdk) is not installable yet: its repository is private and it is not on PyPI. Once the repository is public, you can install it from source and follow the tutorial on your own computer.
• Read the contracts. The specification describes everything a module can rely on, and the JSON Schemas are published as files you can validate against.

What installation will look like

A fleet is one coordinator and any number of nodes. The coordinator runs on macOS or Linux 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 on a Mac or a Linux machine that stays on, and tell it the address nodes will use to reach it. It runs as a background service: LaunchAgents on macOS, systemd user units on Linux.

2. Create your console account on the coordinator. You sign in to the console with a password and a TOTP code from your authenticator app:

   oarbank account create alice --role admin --password

   The console answers only on the coordinator itself (http://127.0.0.1:7400) until you put it behind a TLS proxy for a name you control.

3. Make a join code for each node. A join code names the coordinator’s addresses, pins its certificate authority and approves the node when it is used. It works once.

   oarbank join-code --label build-box

4. Install the node package with its join code.

   macOS

   Put the join code where the installer looks, then install the package (by hand or through MDM):

   sudo mkdir -p /Library/Oarbank/etc
   echo 'OB1-…' | sudo tee /Library/Oarbank/etc/join-code >/dev/null
   sudo installer -pkg oarbank-agent-<version>-macos.pkg -target /

   The node runs for the user who is logged in. To run it as a system service that starts at boot, under its own _oarbank account, create an empty /Library/Oarbank/etc/system file before installing.

   Linux

   Put the join code where the package looks, then install the .deb (or the .rpm with dnf):

   sudo install -d /etc/oarbank
   echo 'OB1-…' | sudo tee /etc/oarbank/join-code >/dev/null
   sudo apt install ./oarbank-agent_<version>_amd64.deb

   The package creates an oarbank account and a systemd service whose jobs run in their own cgroups.

   Windows

   Install the MSI with the join code, from an elevated prompt:

   msiexec /i oarbank-agent-<version>-windows-x64.msi /qn JOINCODE=OB1-…

   The MSI installs the agent as a Windows service and a helper service that enforces each job’s network allowlist. Use the arm64 MSI on ARM64 PCs.

   The installer reads the join code and deletes it. 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.

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, and enable it:

   oarbank module install <bundle>.mfb
   oarbank module approve <name>@<version>
   oarbank module enable <name>@<version>

Next

• How Oarbank works: the ideas behind the steps above.
• Requirements: what each computer and the network need.
• Build a module in a day: write your own job type.