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:
- Apple
containerCLI — https://github.com/apple/container - Docker CLI
- Podman CLI
- OrbStack/Docker-compatible CLI
- Anthropic Sandbox Runtime (
srt) CLI
- Apple
- 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:
autouses Applecontainer - Linux:
autousespodman
You can override that auto default in config with:
[engine]
default = "docker"
In practice, that means:
--engine containerexpects Applecontainer--engine dockerexpects Docker--engine podmanexpects Podman--engine orbstackexpects an OrbStack-backed Docker-compatible CLI--engine nerdctlexpects Nerdctl--engine sandboxexpects 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