---
title: Releases and signatures
description: Verify a venom download against SHA256SUMS and its minisign signature, and build your own release, library packages, SBOM and other artifacts from a checkout with make release, make libs and related targets.
section: deploy
order: 80
audience: [operator, builder]
sources: [docs/release.md, Makefile, scripts/release.sh, scripts/pack-libs.sh, scripts/install.sh, scripts/release/sign.sh, scripts/release/keygen.sh, scripts/release/sbom.py, scripts/release/next-version.sh, scripts/publish-release.sh, scripts/release/public-sums.sh]
features: [deploy.release, deploy.make-release]
---

venom's releases are published at [github.com/elishahbiz/venom-releases](https://github.com/elishahbiz/venom-releases/releases): the CLI and desktop daemon archives for each platform plus one `SHA256SUMS`. The source is not published there. This page covers checking what you downloaded, what a release contains, and building one yourself.

## Verify a download {#verify}

Every release has a `SHA256SUMS` listing each archive. The installers check it for you before they unpack anything; to check by hand:

```bash
V=0.4.2
curl -fsSLO https://github.com/elishahbiz/venom-releases/releases/download/v$V/SHA256SUMS
curl -fsSLO https://github.com/elishahbiz/venom-releases/releases/download/v$V/venom-$V-linux-x64.tar.gz
sha256sum -c --ignore-missing SHA256SUMS        # macOS: shasum -a 256 -c --ignore-missing SHA256SUMS
```

A signed release also carries `SHA256SUMS.minisig`, a [minisign](https://jedisct1.github.io/minisign/) (Ed25519) signature over `SHA256SUMS` with the trusted comment `venom <v> SHA256SUMS`. With the release's public key:

```bash
minisign -Vm SHA256SUMS -P <public key>      # or -p minisign.pub
```

The checksum proves a file matches the list; the signature proves who published the list. The release `install.sh` checks the signature before the checksums, with the key written into it at build time, or `VENOM_RELEASE_PUBKEY=<key>` for a key you got another way. A signature that does not verify stops the install before anything is written. With no key, no `.minisig` or no `minisign` installed, it says why it skipped the check and goes on with `SHA256SUMS` alone; `VENOM_REQUIRE_SIGNATURE=1` makes any of those an error.

## What a release contains {#contents}

`make release VERSION=x.y.z` writes these into `dist/release/<v>/`:

| File | What |
|---|---|
| `venom-orchestrator-<v>-{darwin,linux}-{arm64,amd64}` | The orchestrator: a static Go binary (pure-Go SQLite), about 12 MB. `--version` prints `<v>`. |
| `venom-cli-<v>.tar.gz` | The CLI, self-contained apart from Node.js (22.19 or newer). About 7 MB. |
| `venom-<v>-{darwin,linux}-{arm64,x64}.tar.gz`, `venom-<v>-windows-x64.zip` | The CLI with a pinned official Node.js inside: what the public installers download. |
| `venom-daemon-<v>-{darwin,linux}-{arm64,x64}.tar.gz`, `venom-daemon-<v>-windows-x64.zip` | [The desktop daemon](/docs/deploy/desktop-daemon.md): launcher, orchestrator, standalone console, pinned Node.js, default config. |
| `Venom-Daemon-<v>-macos-{arm64,x64}.zip` (and `.dmg`) | The daemon as an ad-hoc signed macOS app; the `.dmg` only where `hdiutil` works. |
| `Venom-Daemon-<v>-macos-{arm64,x64}.pkg` | Built on macOS only: the installer with the menu bar app. Unsigned unless Developer ID certificates are configured. |
| `venom-daemon_<v>_{amd64,arm64}.deb` | Built where `dpkg-deb` exists (Debian, Ubuntu): the daemon for Ubuntu and Debian, `sudo apt install ./venom-daemon_<v>_amd64.deb` ([the .deb](/docs/deploy/desktop-daemon.md#deb)). |
| `venom-cloud_<v>_all.deb` | Built the same way: the self-host installer of this release, then `sudo venom-cloud-setup` ([Self-host Venom Cloud](/docs/deploy/self-host-cloud.md#deb)). |
| `Venom-Cloud-<v>-macos.{pkg,zip,dmg}` | Built on macOS only: [Venom Cloud on a Mac](/docs/deploy/install-mac.md#one-click) as an installer and as an app to drag to Applications (the same app; the `.dmg` only where `hdiutil` works). No architecture in the name. The `.pkg` is unsigned unless Developer ID certificates are configured. |
| `venom-harness-<v>.tgz`, `venom-harness-server-<v>.tgz` | `@venom/harness` and `@venom/harness-server` for your own apps. Install both tarballs in one `npm install`. |
| `venom_client-<pv>-py3-none-any.whl`, `venom_client-<pv>.tar.gz` | The Python client; `<pv>` is `<v>` as a PEP 440 version (`0.2.0-rc.1` becomes `0.2.0rc1`). |
| `orchestrator.yaml`, `prices.yaml` | The default config and the offline price table the orchestrator computes `cost_usd` from. |
| `install.sh` | The offline installer, with the release's public signing key written in. |
| `IMAGES` | The tags and IDs of the locally built images `venom/orchestrator:<v>` and `venom/console:<v>`. |
| `venom-<v>.cdx.json` | The SBOM ([below](#sbom)). |
| `SHA256SUMS`, `SHA256SUMS.minisig` | Checksums of every file above, and their signature when signed. |

The public releases repository carries the archives (CLI, daemon, macOS app) and a `SHA256SUMS` with only their lines. Library tarballs, wheels and images are built by `make release` and `make libs` for your own distribution.

Every archive goes through a content check before it ships: no `.env*`, `.npmrc`, `.git`, source maps, keys, certificates, credential-shaped strings, private repository links, or paths from the build machine.

## Build a release {#build}

```bash
make release VERSION=0.1.0       # → dist/release/0.1.0/
```

It needs Go, Node.js 22.19 or newer with npm, bun (the version pinned in `devbox.json`), `python3`, a running Docker daemon, and the npm registry (or a warm bun cache). Nothing is pushed, tagged or uploaded; `dist/` is gitignored.

| Variable | What it limits |
|---|---|
| `RELEASE_TARGETS` | Orchestrator builds, e.g. `"linux/amd64 darwin/arm64"`. |
| `CLI_TARGETS` | Self-contained CLI archives, e.g. `"darwin/arm64 windows/x64"`. |
| `DAEMON_TARGETS` | Daemon archives; `""` skips them. |
| `RELEASE_IMAGES` | `0` skips the Docker images and `IMAGES`. |
| `VENOM_RELEASE_MINISIGN_KEY` | Path to the minisign secret key; signs `SHA256SUMS` ([below](#signing)). |

The pinned Node.js for the self-contained archives comes from `scripts/release/node-runtime.txt`, which names one LTS version and the SHA-256 of each platform's archive from nodejs.org. The build downloads each once into `~/.cache/venom-release/node` (`VENOM_RELEASE_CACHE`) and refuses any file whose hash differs.

**Install a release you built**, on this or another machine (copy the directory, or just `install.sh`, `SHA256SUMS`, the CLI tarball, `orchestrator.yaml`, `prices.yaml` and the one orchestrator binary you need):

```bash
dist/release/0.1.0/install.sh                                 # into ~/.local
scripts/install.sh --from dist/release/0.1.0 --prefix /opt/venom
```

The installer makes no network calls. It checks everything against `SHA256SUMS` before writing, installs `PREFIX/lib/venom/<v>/` and points `PREFIX/bin/venom` at it (older versions stay), writes `PREFIX/bin/venom-orchestrator` (a wrapper with this install's `VENOM_CONFIG`, `VENOM_DATA_DIR` and key), generates `PREFIX/share/venom/client-key` (mode 600, never printed) when no key is configured, keeps an existing `orchestrator.yaml` (the new default lands beside it as `orchestrator.yaml.<v>.default`), and prints the next steps.

**Run the image you built:**

```bash
docker run -e VENOM_API_KEY=<key> -p 127.0.0.1:8787:8787 \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 --add-host host.docker.internal:host-gateway \
  venom/orchestrator:0.1.0
```

It ships the default config at `/app/config`; mount your own directory there to replace it. Without a client key it refuses to start on its `0.0.0.0` listen address. Push the images to your registry yourself, for example for [Kubernetes](/docs/deploy/kubernetes.md).

## Library packages only {#libs}

```bash
make libs                  # version from packages/harness/package.json
make libs VERSION=0.1.0    # → dist/libs/
```

Builds `venom-harness-<v>.tgz`, `venom-harness-server-<v>.tgz` and the `venom_client` wheel without Go or Docker, for apps built on the harness ([Embedding the harness](/docs/harness/embedding.md)).

## Signing {#signing}

```bash
make release-keygen                                              # once; needs minisign
VENOM_RELEASE_MINISIGN_KEY=~/.minisign/venom-release.key make release VERSION=x.y.z
```

`make release-keygen` writes the secret key to `~/.minisign/venom-release.key` (or the path in `VENOM_RELEASE_MINISIGN_KEY`; it never overwrites one; minisign asks for a password, `NO_PASSWORD=1` for none), writes the public key into `scripts/release/minisign.pub`, and prints both paths. Commit the public key; keep the secret one off the repository and backed up. Until the public key is committed, a release built with a key refuses to sign rather than produce a signature nothing can check. Each signature is checked against the committed public key before it is kept. Without the variable the release is unsigned and says so.

## SBOM {#sbom}

`venom-<v>.cdx.json` is a CycloneDX 1.5 JSON SBOM, written with no network from what the release built: the Go modules compiled into the orchestrator (read from the binaries' build info, so test-only modules are left out) and every non-dev npm package in the shipped lockfiles (CLI, harness, harness server, ACP, console), with each lockfile's sha512 integrity and declared license. The timestamp is the release commit's and the serial number derives from the contents, so rebuilding the same commit gives the same file. `SHA256SUMS` covers it.

## Automatic releases {#automatic}

venom's own pipeline publishes a patch release on every merge to main that touches shipped code (the CLI, packages, plugins, orchestrator, console, config, release scripts, menu bar app). Releases run one at a time; merges that land during one queue behind it.

- **Version**: the highest `vX.Y.Z` tag of the releases repository plus one patch. A manual run takes `patch`, `minor`, `major` or an exact version. A tag that exists already stops the run successfully.
- **Build**: Linux builds the orchestrator binaries, the five CLI archives, the Linux and Windows daemon archives and the libraries, without images; a macOS runner builds the two macOS app zips and `.dmg`s.
- **Publish**: one `SHA256SUMS` over both builds, then the archives and `SHA256SUMS` go up as a GitHub release, and every asset is downloaded again anonymously and compared.
- **Tag**: the same `v<v>` tag on the released commit.

The download buttons on the site (`https://cloud.usevenom.dev/download/<platform>` and `/download/daemon/<platform>`) redirect to the newest release within five minutes. Automatic releases don't cut the changelog; a release with its own changelog section is run by hand with that version.

To publish your own build to a releases repository of yours, `scripts/publish-release.sh <v> --dry-run` shows what would go up, and without `--dry-run` it pushes, creates the GitHub release and verifies anonymous downloads (it needs `gh` signed in with push access). A signed build publishes its own `SHA256SUMS` and `SHA256SUMS.minisig` unchanged, after checking the signature against `scripts/release/minisign.pub` (so `minisign` must be installed); an unsigned one publishes the archives' checksums with a warning. Once `minisign.pub` holds a real key, an unsigned release is refused. In the release workflow, the repository secret `RELEASE_MINISIGN_KEY` (a passwordless key from `NO_PASSWORD=1 make release-keygen`) turns signing on.

## Building other artifacts {#other-artifacts}

| Command | Output |
|---|---|
| `make airgap VERSION=x.y.z` | An offline bundle in `dist/airgap/<v>/` ([Air-gapped install](/docs/deploy/airgap.md)). |
| `make daemon-bundle` | The desktop daemon tree for this machine in `dist/daemon-bundle/` ([The desktop daemon](/docs/deploy/desktop-daemon.md#build)). |
| `make daemon-pkg VERSION=x.y.z` | The macOS `.pkg` for this Mac in `dist/daemon-pkg/`. |
| `make deb VERSION=x.y.z [DOCKER=1]` | The Ubuntu/Debian `.deb` packages in `dist/deb/`, from a built release; `DOCKER=1` builds in a container on a Mac. |
| `make cloud-pkg VERSION=x.y.z` | The Venom Cloud `.pkg`, `.zip` and `.dmg` for a Mac in `dist/cloud-pkg/`, around the checkout's `install-cloud.sh`. |
| `make daemon` | Not an artifact: brings up the Docker stack with Ollama and the recommended models ([Docker Compose](/docs/deploy/compose.md#daemon)). |
| `make vsix` | The VS Code extension, `clients/vscode/dist/venom-vscode.vsix`, for local install (never published). |
| `make chrome-extension` | The browser extension in `dist/chrome-extension/<slug>/` plus its store zip. `NAME="…"` renames it, `TARGET=edge` makes the Edge Add-ons zip, `TARGET=firefox` an unsigned `.xpi` (`GECKO_ID=…` sets its add-on id). |
| `make chrome-page-scripts` | Regenerates the Firefox driver's copy of the harness's page scripts after a change to them. |
| `make docs-site`, `make docs-site-check` | The offline API and SDK docs site in `dist/docs-site/`, and its parity check ([The offline docs site](/docs/reference/docs-site.md)). |
| `make public-mesh-e2e` | Not an artifact: the public mesh end to end on loopback (a cloud, toy daemons, the auditor; about 2 minutes). |

The VS Code extension, browser extension and public mesh have their own sections in these docs (integrations and mesh).

## Troubleshooting {#troubleshooting}

| Message | Cause and fix |
|---|---|
| `usage: make release VERSION=x.y.z` | `VERSION` is required for `release`, `airgap`, `daemon-pkg`, `cloud-pkg` and `deb`. |
| A release built with a key refuses to sign | `scripts/release/minisign.pub` is still the placeholder. Run `make release-keygen` and commit the public key. |
| `publish-release: this release is not signed, but … holds the release signing key` | The public key is committed but the build had no secret key. Rebuild with `VENOM_RELEASE_MINISIGN_KEY`, or add the `RELEASE_MINISIGN_KEY` secret for the release workflow. |
| `publish-release: SHA256SUMS.minisig does not verify` | `SHA256SUMS` changed after it was signed, or it was signed with another key. Sign it again with the committed key. |
| `sha256sum: WARNING: 1 computed checksum did NOT match` | The download is damaged or altered. Download again; do not install it. |
| The installer says the signature was not checked | No `minisign` on the machine, or the release is unsigned. Install `minisign`, or set `VENOM_REQUIRE_SIGNATURE=1` to refuse. |
| A daemon `.app` or `.pkg` is blocked by Gatekeeper | It is not notarized. Right-click, Open, or System Settings, Privacy & Security, Open Anyway. |

## Related

- [Installing the CLI](/docs/getting-started/install.md): the public installers.
- [Air-gapped install](/docs/deploy/airgap.md)
- [Make targets](/docs/reference/make-targets.md)
