Opal/ documentation source ↗
On this page

#Install

#Install with Cargo

cargo install --path crates/opal

From this workspace, install the CLI crate directly.

The installed executable is still:

opal

#Homebrew on macOS

If you prefer Homebrew, install Opal from the Cloudflavor tap:

brew tap cloudflavor/tap
brew install cloudflavor/tap/opal-cli

Verify the install:

opal --version

#Upgrade

When the tap publishes a newer formula:

brew update
brew upgrade cloudflavor/tap/opal-cli

#Check versions

Use Homebrew's built-in inspection commands:

brew livecheck cloudflavor/tap/opal-cli
brew info cloudflavor/tap/opal-cli

#Remove

To uninstall Opal and remove the tap:

brew uninstall cloudflavor/tap/opal-cli
brew untap cloudflavor/tap

#Install from a local checkout

cargo install --path crates/opal

Use this when you are developing Opal itself from a local repository checkout.

#Download prebuilt binaries

Choose macOS Apple Silicon, Linux ARM64 or Linux x86_64 from Opal GitHub Releases. GitHub repository access permissions apply. Obtain the matching archive and its checksums together from the selected release; use the actual asset names rather than constructing a binary URL.

Verify the archive against that release's checksum inventory before extraction. Use sha256sum -c on Linux or shasum -a 256 -c on macOS with the downloaded checksum file, checking the matching archive entry. Checksums detect corruption, not independent publisher authentication. Extract the verified archive, inspect its provenance and release notes, then place opal in a user-owned directory on your PATH. Do not silently replace an existing installation.

#Runtime requirements

Opal does not ship its own container runtime. It wraps the local engine CLIs listed below, so the engine you want to use must already be installed and available on your PATH.

Supported local engines:

  • macOS:
  • Linux:
    • Docker CLI
    • Podman CLI
    • Nerdctl CLI
    • Anthropic Sandbox Runtime (srt) CLI

nerdctl is Linux-oriented rather than a first-class macOS host engine.

Default engine selection:

  • macOS: auto uses Apple container
  • Linux: auto uses podman

You can override that auto default in config with:

[engine]
default = "docker"

In practice, that means:

  • --engine container expects Apple container
  • --engine docker expects Docker
  • --engine podman expects Podman
  • --engine orbstack expects an OrbStack-backed Docker-compatible CLI
  • --engine nerdctl expects Nerdctl
  • --engine sandbox expects Anthropic Sandbox Runtime (srt)

If you want the Apple engine specifically, install it from:

https://github.com/apple/container

If the selected engine CLI is missing or unavailable, Opal cannot run jobs with that engine.

#Why prefer Apple container on macOS?

On macOS, many Linux-container workflows run all containers inside one shared Linux VM.

Apple container uses a different model:

  • each container runs in its own lightweight VM
  • only the host data you explicitly mount is exposed to that container VM
  • you get stronger isolation properties than a shared-VM container setup
  • Apple documents performance as being comparable to shared-VM container workflows while using lightweight per-container VMs instead of full traditional VMs

For Opal's local-debugging use case, that gives a few practical benefits:

  • better isolation between jobs and ad-hoc troubleshooting containers
  • less accidental host-data exposure, because mounts stay explicit per job
  • resource tuning that maps naturally to each job when you use Opal's [container] config

This does not make Apple container universally better for every workflow, but it is a strong default for local macOS pipeline runs when you want tight per-job isolation without running one large always-on Linux VM for all containers.

#Verify the install

opal --version
opal plan --no-pager

#Shell completions

Opal can print shell completions directly from the installed binary:

opal completions zsh

Common install targets:

# zsh
mkdir -p ~/.zfunc
opal completions zsh > ~/.zfunc/_opal

# fish
mkdir -p ~/.config/fish/completions
opal completions fish > ~/.config/fish/completions/opal.fish

# bash
mkdir -p ~/.local/share/bash-completion/completions
opal completions bash > ~/.local/share/bash-completion/completions/opal