Install venom
Install, update and remove the venom CLI on macOS, Linux and Windows, from the release installer, by hand, or from source.
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 | shThe script:
- picks the build for your OS and chip (
uname -s,uname -m); - 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; - unpacks it into
~/.venom/releases/venom-<version>-<os>-<arch>/, removes the macOS quarantine attribute, and links~/.venom/bin/venomto it; - runs the installed
venom --version, and prints the line to add to your shell profile if~/.venom/binis 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" shPut 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 # fishThe 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, RHELmacOS 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 | iexIt 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 doctorTo 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 --versionThe unpacked directory runs from anywhere; link or copy bin/venom onto your PATH.
Check the install
venom --version
venom doctorvenom 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 doctorThe 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>/.
Related
- Local or cloud: give venom a model.
- venom CLI quickstart: the shortest path to a first session.
- Troubleshooting:
venom doctorand the common failures.