Skip to content
Docs menu

Install venom

Install, update and remove the venom CLI on macOS, Linux and Windows, from the release installer, by hand, or from source.

View .md

The venom CLI ships as one archive per platform. Each archive carries its own Node.js runtime, so it needs nothing else installed, and the installers never ask for root or administrator rights. Every download comes from the public releases repository and is checked against the release's SHA256SUMS before anything is unpacked.

Supported platforms

OS Chips Archive Notes
macOS Apple silicon (arm64), Intel (x64) venom-<version>-darwin-<arch>.tar.gz An x64 shell under Rosetta still gets the native arm64 build. OS sandbox: Seatbelt (sandbox-exec).
Linux (glibc) x64, arm64 venom-<version>-linux-<arch>.tar.gz musl systems such as Alpine are not supported yet. OS sandbox: bubblewrap (bwrap), which you install from your distribution.
Windows (beta) x64; ARM64 runs the x64 build under emulation venom-<version>-windows-x64.zip No OS sandbox. For the full sandbox, run the Linux build in WSL.

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh

The script:

  1. picks the build for your OS and chip (uname -s, uname -m);
  2. downloads the release's SHA256SUMS, finds the archive for your platform in it, downloads that archive from its version's own URL and compares the SHA-256. On a mismatch it stops and installs nothing;
  3. unpacks it into ~/.venom/releases/venom-<version>-<os>-<arch>/, removes the macOS quarantine attribute, and links ~/.venom/bin/venom to it;
  4. runs the installed venom --version, and prints the line to add to your shell profile if ~/.venom/bin is not on your PATH.

It needs curl, tar, uname, mktemp and sha256sum or shasum.

Installer variables

Variable Default What it does
VENOM_VERSION the latest release Install this version instead, for example VENOM_VERSION=0.4.2. A leading v is accepted.
VENOM_INSTALL_DIR ~/.venom Where releases are unpacked (in releases/ under it).
VENOM_BIN_DIR $VENOM_INSTALL_DIR/bin Where the venom link goes, for example /usr/local/bin if you can write there.
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh \
  | VENOM_VERSION=0.4.2 VENOM_BIN_DIR="$HOME/.local/bin" sh

Put venom on your PATH

If the installer said ~/.venom/bin is not on your PATH, add it to your shell's startup file:

echo 'export PATH="$HOME/.venom/bin:$PATH"' >> ~/.zshrc && exec zsh     # zsh (macOS default)
echo 'export PATH="$HOME/.venom/bin:$PATH"' >> ~/.bashrc && exec bash   # bash
fish_add_path ~/.venom/bin                                              # fish

The Linux sandbox

On Linux, venom's OS sandbox is bubblewrap. Without it, yolo mode asks before shell commands the way accept-edits does, and venom doctor warns. Install it once:

sudo apt-get install -y bubblewrap     # Debian, Ubuntu
sudo dnf install -y bubblewrap         # Fedora, RHEL

macOS has its sandbox (sandbox-exec) built in.

Windows (beta)

In PowerShell (no administrator rights needed):

irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.ps1 | iex

It does the same checks as the shell installer, unpacks the zip into %USERPROFILE%\.venom\releases\, writes a small venom.cmd shim into %USERPROFILE%\.venom\bin and adds that directory to your user PATH. New terminals pick up the PATH change; the current one is updated too. $env:VENOM_VERSION and $env:VENOM_INSTALL_DIR work as on macOS and Linux.

Windows has no OS sandbox, and venom says so at start: in yolo mode, shell commands your rules don't allow still ask, and auto mode is unavailable. Everything else works. For the sandbox, install the Linux build inside WSL with the shell installer.

Set the endpoint for the current PowerShell session like this (see Local or cloud for which one):

$env:VENOM_BASE_URL = "https://cloud.usevenom.dev/v1"
$env:VENOM_API_KEY = "vck_…"
venom doctor

To keep them, use setx VENOM_BASE_URL "…" (new terminals only), or set them in your PowerShell profile.

By hand

Download the archive for your platform and SHA256SUMS from the latest release, then:

shasum -a 256 -c SHA256SUMS --ignore-missing     # or: sha256sum -c SHA256SUMS --ignore-missing
tar -xzf venom-*-darwin-arm64.tar.gz
./venom-*-darwin-arm64/bin/venom --version

The unpacked directory runs from anywhere; link or copy bin/venom onto your PATH.

Check the install

venom --version
venom doctor

venom doctor FAILs on the endpoint until you give venom a model. That is the next step: Local or cloud.

Update

Run the install line again. It installs the newest release next to the old one in ~/.venom/releases/ and moves the link, so a running session keeps working. venom doctor --check-update compares your version with the latest release (one small request to GitHub; venom never checks on its own).

To go back to an older version, install it with VENOM_VERSION, or point the link at a directory that is still in ~/.venom/releases/.

Uninstall

rm -f ~/.venom/bin/venom
rm -rf ~/.venom/releases

~/.venom/ also holds your settings and history: config.yaml, permissions.json, sessions under agent/, checkpoints, and cloud.json after venom cloud login. Delete the whole directory to remove those too. On Windows, delete %USERPROFILE%\.venom and remove its bin entry from your user PATH.

Other ways to run venom

Want Use
Local models on this machine without Docker, with a dashboard The desktop daemon: curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-daemon.sh | sh (Windows: install-daemon.ps1). It runs the orchestrator and console on 127.0.0.1. See Local or cloud.
A machine with no internet The air-gapped bundle, built from a source checkout with make release then make airgap on a connected machine, carried over and installed with its own install.sh (no network).
To change venom itself A source checkout (below).

From source

You need Node.js 22.19 or newer for the CLI, Docker plus Go 1.24 or newer for the orchestrator, and bun 1.4.2, which installs the JavaScript packages and runs their scripts (make opens a devbox shell with Go, Node and bun).

git clone <your venom remote> venom && cd venom
make env          # creates .env (mode 600) from .env.example
make up           # orchestrator on 127.0.0.1:8787, console on http://localhost:3000
make link-cli     # builds the CLI and puts `venom` on your PATH (a link in npm's global bin dir)
export VENOM_API_KEY=$(grep '^VENOM_API_KEY=' .env | cut -d= -f2-)
venom doctor

The CLI does not read .env: export the same VENOM_API_KEY the orchestrator got from it, or every request gets a 401. If make link-cli fails with EACCES (inside devbox or a Nix shell), venom doctor --fix links venom into a writable directory on your PATH instead. make release VERSION=x.y.z builds the same archives the public releases ship, into dist/release/<version>/.