---
title: "Install"
summary: "Install ob from GitHub Releases, Homebrew, Scoop, or source, verify it, then confirm the runner."
description: "Install a released ob binary or package, verify it, and confirm the local safety setup."
status: shipped
read_when:
  - "Setting up Onebox on a new machine"
  - "Diagnosing a version or runner-compatibility refusal"
---

Onebox is in alpha. Choose the package manager for your machine, download an
alpha binary, or build from source. Then verify which `ob` your shell will run.

## Choose an install method

Every download below, including the assets Homebrew and Scoop fetch, comes from
a published alpha on [the releases page](https://github.com/labstack/onebox/releases).
Homebrew and Scoop install the current alpha release.

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-alpha` tag.

  
**macOS with Homebrew**

  ```sh
  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**

  ```sh
  version=2026.10.0-alpha
  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**

  ```sh
  version=2026.10.0-alpha
  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**

  ```powershell
  $Version = "2026.10.0-alpha"
  $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**

  ```powershell
  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:

```sh
# Debian or Ubuntu (choose amd64 or arm64)
sudo apt install ./onebox_2026.10.0-alpha_linux_amd64.deb

# Fedora or RHEL (choose amd64 or arm64)
sudo dnf install ./onebox_2026.10.0-alpha_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, outside the
Onebox source repository.

> **`go install` is not a release channel**
>
> The application tag `v2026.10.0-alpha` 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/ob@v2026.10.0-alpha` is not
> a supported installation contract.

## Build from source

From a checked-out repository:

```sh
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

1. **Confirm which runner will execute plans.**

   ```sh
   ob version
   ```

   Releases use `vYYYY.M.REVISION-alpha`, for example `v2026.10.0-alpha` for the
   first release in October 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.**

   ```sh
   ob doctor
   ```

   `ob doctor` reports whether the runner selected by `PATH` satisfies the
   environment's `minOneboxVersion` and `minPlanSchema`, 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](/docs/get-started/first-deploy) and return after `ob init`.

Both commands support `--output json`.

> **Why a checkout build can be refused**
>
> See [runner and plan-schema policy](/docs/reference/policies#runner-and-plan-schema-policy)
> for how `minOneboxVersion` applies to checkout builds.

## 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 without 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, so the gates agree about which host is deployable.

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
reads only `docker buildx imagetools inspect --help` and requires the client to
advertise `--format`. It resolves no image and uses no registry quota. Missing
Buildx or missing support produces an image-resolver remedy. Planning validates
the returned digest, catching clients that advertise the option but ignore it
before they can produce a misleading registry error.

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

```yaml
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.

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