opavm

A dead-simple version manager for Open Policy Agent (OPA).

opavm lets you install, pin, and switch OPA versions locally and per-project so your policies run against the same OPA version in dev, CI, and production. No Docker. No magic. Just predictable binaries.

Why opavm exists

OPA is "just a single binary" until it isn't. Teams regularly run into:

• different OPA versions in CI vs local
• silent upgrades via package managers
• subtle behavior changes across releases
• ad-hoc scripts and manual downloads

opavm solves this by making OPA versioning explicit, reproducible, and boring.

Features (v0.1)

• Install specific OPA versions (or latest)
• Install Regal (Rego linter/LSP) versions
• Set a global default version per tool (opa / regal)
• Pin per project with .opa-version or .regal-version
• Automatically switch versions by directory
• CI-safe execution without PATH hacks
• Rich progress bar UI for installs
• Show recent OPA/Regal releases in a Rich table (opavm releases)
• Zero runtime services, zero configuration files

Installation

v0.1 supports:

• macOS (amd64, arm64)
• Linux (amd64, arm64)
• Windows (amd64)

Install as a Python package (recommended with pipx):

pipx install opavm

Or with pip:

pip install opavm

Then add the shim directory to your shell.

macOS/Linux:

export PATH="$HOME/.opavm/shims:$PATH"

Windows PowerShell:

$env:Path = "$HOME\.opavm\shims;$env:Path"

GitHub API token

opavm uses fixed upstream repos:

• open-policy-agent/opa for OPA release lookup
• StyraInc/regal for Regal release lookup

If you hit GitHub API rate limits, set OPAVM_GITHUB_TOKEN.

Quick start

Install OPA:

opavm install 0.62.1

Set a global default:

opavm use 0.62.1
opavm use 0.38.1 --tool regal

Now:

opa version

uses OPA 0.62.1.

Per-project pinning

Inside a repo that requires a specific version:

opavm pin 0.61.0
opavm pin 0.38.1 --tool regal

If that version is not installed, opavm prompts to install it.

This creates tool-specific version files:

.opa-version   # OPA
.regal-version # Regal

Anywhere inside that repo:

opa version

automatically resolves to 0.61.0. Outside the repo, your global version is used again.

Common commands

Install versions:

opavm install 0.62.1
opavm install latest
opavm install regal 0.38.1
opavm install regal latest

List installed versions:

opavm list
opavm list --tool regal

Switch global version:

opavm use 0.63.0
opavm use 0.38.1 --tool regal

See what's active (and why):

opavm current
opavm current --tool regal

Get the actual binary path:

opavm which
opavm which --tool regal

opavm which prints the resolved binary as an absolute path.

Show recent OPA releases:

opavm releases --limit 10
opavm releases --tool regal --limit 10

Run OPA without relying on PATH (CI-safe):

opavm exec -- test -v ./policy
opavm exec --tool regal -- lint policy/

Remove a version:

opavm uninstall 0.59.0
opavm uninstall 0.38.1 --tool regal

How version resolution works

When you resolve a tool with current, which, or exec:

1. Look for the tool pin file in the current directory or parents
2. Use .opa-version for OPA, .regal-version for Regal
3. If found, use that version
4. Otherwise, use the global default for that tool
5. If neither exists, error with guidance

This behavior is deterministic and transparent.

File layout

~/.opavm/
|- versions/
|  |- 0.62.1/opa
|  `- 0.63.0/opa
|- tools/
|  `- regal/
|     `- versions/
|        `- 0.38.1/regal
|- shims/
|  `- opa (or opa.cmd on Windows)
`- state.json

.opa-version and .regal-version files live in your project repos and should usually be committed.

CI usage

You don't need shell shims in CI:

opavm install 0.62.1
opavm exec -- test ./policy

This guarantees the correct OPA version regardless of environment.

Integrity and Reliability

• opavm verifies downloaded binaries by executing <tool> version after install.
• For releases that provide *.sha256 assets (for example OPA), opavm validates SHA256 before completing install.
• GitHub error handling includes actionable messages for:
  • proxy misconfiguration (HTTP_PROXY / HTTPS_PROXY)
  • rate limit exhaustion
  • network connectivity failures
  • auth/permission failures

Contributor workflow, testing gates, and CircleCI release details are in contribution.md.

What opavm is not

• Not a container runtime
• Not a policy runner
• Not a plugin manager

It does one thing: manage OPA binaries predictably.

License

Apache 2.0. See LICENSE and license.md.