---
title: Install venom
description: Install, update and remove the venom CLI on macOS, Linux and Windows, from the release installer, by hand, or from source.
section: getting-started
order: 30
audience: [user, operator]
sources: [scripts/release/public/install.sh, scripts/release/public/install.ps1, scripts/release/public/install-daemon.sh, docs/getting-started.md, docs/daemon.md, docs/release.md]
features: []
---

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](https://github.com/elishahbiz/venom-releases/releases) and is checked against the release's `SHA256SUMS` before anything is unpacked.

## Supported platforms {#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 {#unix}

```bash
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 {#installer-env}

| 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. |

```bash
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 {#path}

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

```bash
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 {#bubblewrap}

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:

```bash
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) {#windows}

In PowerShell (no administrator rights needed):

```powershell
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](/docs/getting-started/local-or-cloud.md) for which one):

```powershell
$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 {#manual}

Download the archive for your platform and `SHA256SUMS` from the [latest release](https://github.com/elishahbiz/venom-releases/releases/latest), then:

```bash
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 {#check}

```bash
venom --version
venom doctor
```

`venom doctor` FAILs on the endpoint until you give venom a model. That is the next step: [Local or cloud](/docs/getting-started/local-or-cloud.md).

## Update {#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 {#uninstall}

```bash
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 {#other}

| 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](/docs/getting-started/local-or-cloud.md#daemon). |
| 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 {#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).

```bash
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>/`.

## Related

- [Local or cloud](/docs/getting-started/local-or-cloud.md): give venom a model.
- [venom CLI quickstart](/docs/getting-started/cli-quickstart.md): the shortest path to a first session.
- [Troubleshooting](/docs/getting-started/troubleshooting.md): `venom doctor` and the common failures.
