Skip to content
Onebox

Install

Choose the package manager for your machine, download a released binary, or build from source. Then verify which ob your shell will run.

Choose an install method

Section titled “Choose an install method”

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.

Terminal window
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.

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

Section titled “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:

Terminal window
# 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.

Build from source

Section titled “Build from source”

From a checked-out repository:

Terminal window
just build

just install builds the CLI and then installs it into ~/.local/bin. Set ONEBOX_INSTALL_DIR to another installation directory, or ONEBOX_BIN_DIR to change where the intermediate build is written. Run just --list to see the available build, test, formatting and check targets.

Verify the installation

Section titled “Verify the installation”

  1. Confirm which runner will execute plans.

    Terminal window
    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.

  2. Check the local safety setup from a project.

    Terminal window
    ob doctor

    ob doctor reports whether the runner selected by PATH satisfies the environment’s min_onebox_version and min_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 because most checks are relative to a project. If you have not created one yet, continue to your first deploy and return after ob init.

Both commands support --output json.

What the host needs

Section titled “What the host needs”

A Linux server you can reach over SSH, with Docker Engine, Docker Compose, and the Docker Buildx plugin available to the configured SSH account. Onebox uses docker buildx imagetools inspect to bind tagged workload images to immutable registry digests. There is no Onebox agent to install on the host — the CLI connects over SSH, and scheduled work runs from host timers rather than a resident process.

All three are asserted as one set, by ob bootstrap, by ob preflight, and by every deploy, so a host that passes one of them passes the others. Each reports the version it observed alongside the result. This includes a project whose workload images are all digest-pinned: such a project never needs Buildx to resolve anything, and is still refused on a host without it, because gates that disagree about which host is deployable is the failure this set exists to prevent.

Distribution packages are a common source of a partial install. Ubuntu’s docker.io gives a working daemon and no Buildx at all, and its docker-buildx 0.30.1 accepts imagetools inspect --format, ignores it, and exits 0. Neither is caught by a version comparison, so the guard is in two parts: the preflight probe requires the client to advertise --format, and planning validates the digest it actually returns, which is what catches a client that advertises the option and ignores it.

Onebox does not download or run a Docker installer implicitly. Install Docker through your normal operator-managed provisioning before ob bootstrap. If you deliberately want Onebox to invoke a pinned or configuration-managed installer, declare it as a remote bootstrap hook:

hooks:
  bootstrap:
    run: /usr/local/sbin/install-pinned-docker

The remote hook runs after Onebox has acquired the application lock, written the mutation fence, and started the bootstrap journal. Docker is checked after the hook returns; if it is still unavailable, bootstrap stops with an actionable error before registry login, proxy setup, services, or evidence publication. A local bootstrap hook runs on the CLI machine and therefore cannot provision the remote host.

Run ob preflight after host provisioning and before the first plan. Its Buildx probe reads only docker buildx imagetools inspect --help; it neither resolves an image nor uses registry quota. It fails with an image-resolver remedy when Buildx is missing or does not advertise the required --format capability. Planning also validates the formatted output, so a client that accepts but ignores the option cannot produce a misleading registry error.

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