Releases and signatures
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.
venom's releases are published at github.com/elishahbiz/venom-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
Every release has a SHA256SUMS listing each archive. The installers check it for you before they unpack anything; to check by hand:
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 SHA256SUMSA signed release also carries SHA256SUMS.minisig, a minisign (Ed25519) signature over SHA256SUMS with the trusted comment venom <v> SHA256SUMS. With the release's public key:
minisign -Vm SHA256SUMS -P <public key> # or -p minisign.pubThe 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
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: 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). |
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). |
Venom-Cloud-<v>-macos.{pkg,zip,dmg} |
Built on macOS only: Venom Cloud on a Mac 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). |
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
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). |
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):
dist/release/0.1.0/install.sh # into ~/.local
scripts/install.sh --from dist/release/0.1.0 --prefix /opt/venomThe 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:
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.0It 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.
Library packages only
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).
Signing
make release-keygen # once; needs minisign
VENOM_RELEASE_MINISIGN_KEY=~/.minisign/venom-release.key make release VERSION=x.y.zmake 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
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
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.Ztag of the releases repository plus one patch. A manual run takespatch,minor,majoror 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
.dmgs. - Publish: one
SHA256SUMSover both builds, then the archives andSHA256SUMSgo 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
| Command | Output |
|---|---|
make airgap VERSION=x.y.z |
An offline bundle in dist/airgap/<v>/ (Air-gapped install). |
make daemon-bundle |
The desktop daemon tree for this machine in dist/daemon-bundle/ (The desktop daemon). |
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). |
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). |
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
| 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: the public installers.
- Air-gapped install
- Make targets