Install

1. Install a released binary or build from source.

   GitHub Releases provide archives for Linux, macOS and Windows, plus Debian and RPM packages for Linux. Homebrew and Scoop provide package-manager installation. The exact commands are below. Ensure the chosen install directory is on PATH.

2. Confirm which runner will execute plans.

   ob version

   Releases use vYYYY.M.REVISION, for example v2026.8.0 for the first release in August 2026. The year is four digits, months are unpadded, and each UTC calendar month starts at revision zero. Checkout builds use Git-derived provenance and stay visibly distinct from a release.

3. Check the local safety setup.

   ob doctor

   ob doctor reports whether the runner selected by PATH satisfies the environment’s minimum_onebox_version and minimum_plan_schema, and names every workload and service holding durable data that has no backup.

   Run it from a directory that has an ob.yml. Outside a project it reports project_unreadable and exits non-zero, which is correct — most of what it checks is relative to a project — but it looks alarming if you have not created one yet. Come back to this step after your first deploy.

Both commands take --output json.

Install from a GitHub Release

Releases begin at the first tag

Every download below, including the assets Homebrew and Scoop fetch, comes from a published vYYYY.M.REVISION release. If the releases page is empty, or lists nothing for your platform, build from source instead.

Set version to the release without its leading v. The asset name uses that value, while the download URL uses the full vYYYY.M.REVISION tag.

macOS with Homebrew

brew install labstack/tap/onebox

Homebrew verifies the archive digest. The installed ob binary is signed with LabStack’s Developer ID and accepted by Apple’s notarization service.

macOS

version=2026.8.0
arch=arm64 # use amd64 on Intel Macs
asset="onebox_${version}_darwin_${arch}.tar.gz"
curl -fLO "https://github.com/labstack/onebox/releases/download/v${version}/${asset}"
curl -fLO "https://github.com/labstack/onebox/releases/download/v${version}/onebox_${version}_checksums.txt"
grep "  ${asset}$" "onebox_${version}_checksums.txt" | shasum -a 256 -c -
tar -xzf "$asset"
mkdir -p "$HOME/.local/bin"
install -m 0755 ob "$HOME/.local/bin/ob"

Linux archive

version=2026.8.0
arch=amd64 # use arm64 on 64-bit ARM
asset="onebox_${version}_linux_${arch}.tar.gz"
curl -fLO "https://github.com/labstack/onebox/releases/download/v${version}/${asset}"
curl -fLO "https://github.com/labstack/onebox/releases/download/v${version}/onebox_${version}_checksums.txt"
grep "  ${asset}$" "onebox_${version}_checksums.txt" | sha256sum --check
tar -xzf "$asset"
mkdir -p "$HOME/.local/bin"
install -m 0755 ob "$HOME/.local/bin/ob"

Windows PowerShell

$Version = "2026.8.0"
$Arch = "amd64" # use arm64 on Windows on ARM
$Asset = "onebox_${Version}_windows_${Arch}.zip"
$Base = "https://github.com/labstack/onebox/releases/download/v${Version}"
Invoke-WebRequest "$Base/$Asset" -OutFile $Asset
Invoke-WebRequest "$Base/onebox_${Version}_checksums.txt" -OutFile "checksums.txt"
$Expected = ((Get-Content checksums.txt | Select-String "  $Asset$").Line -split ' ')[0]
$Actual = (Get-FileHash $Asset -Algorithm SHA256).Hash.ToLowerInvariant()
if ($Actual -ne $Expected) { throw "checksum mismatch for $Asset" }
Expand-Archive $Asset -DestinationPath onebox
New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
Copy-Item "onebox\ob.exe" "$HOME\bin\ob.exe"

Windows with Scoop

scoop bucket add labstack https://github.com/labstack/scoop-bucket
scoop install labstack/onebox

Scoop verifies the selected Windows archive against the SHA-256 digest in the bucket manifest. Future releases are available through scoop update onebox.

The checksum manifest covers every archive and Linux package in the release. It detects corruption. macOS binaries additionally carry LabStack’s Developer ID signature and Apple notarization; other platforms do not yet publish an independent signature or provenance attestation.

Debian and RPM packages

Download the package and checksum manifest from the same GitHub Release, verify the package entry as above, then install the local file:

# Debian or Ubuntu (choose amd64 or arm64)
sudo apt install ./onebox_2026.8.0_linux_amd64.deb

# Fedora or RHEL (choose amd64 or arm64)
sudo dnf install ./onebox_2026.8.0_linux_amd64.rpm

These are downloadable package files, not hosted APT or RPM repositories. WinGet is not published yet. Homebrew and Scoop metadata live in the dedicated labstack/homebrew-tap and labstack/scoop-bucket repositories rather than the Onebox source repository.

go install is not a release channel

The application tag v2026.8.0 is intentionally CalVer-shaped, but the Go module path does not declare a /v2026 module major. Use a precompiled release asset or build from source; go install github.com/labstack/onebox/cmd/[email protected] is not a supported installation contract.

Build from source

From a checked-out repository:

just build

just install is an alias for the same target and installs into ~/.local/bin. Set OB_BIN_DIR to another destination. Run just --list to see the available build, test, formatting and check targets.

Why a checkout build can be refused

When an environment sets minimum_onebox_version, commit-derived and dirty checkout builds fail closed — they are not released runners. That is deliberate: an environment that pins a minimum is asking for a runner whose identity can be checked, and a dirty working tree has none.

What the host needs

A Linux server you can reach over SSH, with a container runtime. There is no Onebox agent to install on it — the CLI connects over SSH, and scheduled work runs from host timers rather than a resident process.

ob bootstrap prepares the host. It is the one command that contacts and changes a server before any application exists.

Releasing (maintainers)

just release

Requires a clean, checked, up-to-date main. It atomically publishes a metadata-only fast-forward release commit plus its tag to origin, so the release identity needs permission to fast-forward main. A branch policy that refuses the update aborts the publication without leaving a tag behind.