The desktop daemon
Install venom-daemon on a desktop or GPU box with no Docker, manage it from the command line, the dashboard or the macOS menu bar, connect it to Venom Cloud, and turn on opt-in auto-update.
venom-daemon runs the orchestrator and the console on 127.0.0.1 with no Docker. One launcher starts both, waits for them, and opens the dashboard in your browser, already signed in. From the dashboard you install Ollama, pull the models that fit your machine, and optionally connect the machine to Venom Cloud with a join token. For servers, make daemon does the same job with Docker.
Install
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-daemon.sh | sh # macOS, Linuxirm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-daemon.ps1 | iex # Windows (beta)No root needed. The installer reads the latest release's SHA256SUMS, downloads the daemon archive for your OS and chip, checks its SHA-256, stops an older running daemon, unpacks into ~/.venom/releases/ (removing older daemon releases), links ~/.venom/bin/venom-daemon, creates the desktop launch entry, turns on start at login (on Linux it also starts the daemon at boot), then starts the daemon and opens the dashboard. On Linux where Docker answers it then turns Venom Computers on; the first time builds the computer image on the machine, which takes a few minutes.
To update, run the same command again. It installs the latest release over the old one; your data, secrets, cloud connection and settings (Computers included) stay.
| Installer variable | What it does |
|---|---|
VENOM_VERSION |
Install this version instead of the latest. |
VENOM_INSTALL_DIR, VENOM_BIN_DIR |
Where releases are unpacked (default ~/.venom) and where the link goes (default $VENOM_INSTALL_DIR/bin). |
VENOM_DAEMON_NO_OPEN=1 |
Start without opening a browser (also the default on Linux without a display). |
VENOM_DAEMON_NO_START=1 |
Install only; don't start. |
VENOM_DAEMON_NO_AUTOSTART=1 |
Don't turn on start at login. |
VENOM_DAEMON_NO_COMPUTERS=1 |
Don't turn on Venom Computers (Linux). |
VENOM_DAEMON_ARCHIVE |
Install this venom-daemon-<version>-<os>-<arch>.tar.gz from disk instead of downloading one. |
On macOS there are also Venom-Daemon-<v>-macos-<arch>.zip (unzip, double-click Venom Daemon.app) and the .pkg installer with a menu bar app (below). Downloads are on the releases page and https://cloud.usevenom.dev/daemon.
Ubuntu and Debian: the .deb
A release built where dpkg-deb exists also carries venom-daemon_<v>_amd64.deb and venom-daemon_<v>_arm64.deb. Double-click one in the software installer, or:
sudo apt install ./venom-daemon_<v>_amd64.debThe package puts the daemon in /opt/venom-daemon/<v>/, a venom-daemon command in /usr/bin and a "Venom Daemon" entry in the app launcher. The entry runs venom-daemon start, which starts the daemon and opens its dashboard, as the macOS app does. Installing does nothing else: no network, no service, nothing started.
The first time a user runs it, it copies the daemon into that user's ~/.venom/releases/ and links ~/.venom/bin/venom-daemon, the same layout install-daemon.sh makes, so auto-update and venom-daemon autostart on work as they do for the one-line install. Later runs go straight to that copy, so a release the daemon updated itself to keeps running; a newer package replaces an older copy. Removing the package removes /opt/venom-daemon and the command; each user's ~/.venom (the copy and the data) stays. Run venom-daemon uninstall first to remove it too.
The package depends on glibc 2.28 or newer, recommends xdg-utils and suggests Docker (for Venom Computers only). The package's Version is Debian's spelling of the release version: a pre-release 0.2.0-rc.1 is 0.2.0~rc.1. The file is not signed by an apt repository: check it against SHA256SUMS as for any download.
What runs
| Part | What it is |
|---|---|
bin/venom-daemon |
The launcher. |
bin/orchestrator |
The orchestrator, on 127.0.0.1:8787, or a free port when that is taken. |
bin/venom-telegram |
The Telegram helper. It runs only after you log in to your own Telegram account (Telegram from your own account). |
console/server.js |
The console (Next.js standalone) on 127.0.0.1:3787, or a free port. |
node/ |
The pinned Node.js runtime the console and the CLI run on. |
bin/venom, cli/ |
The venom CLI, run on node/. The daemon runs it as venom serve on your project folders, and Venom Computers starts it for each seat's agent sessions, so the machine needs no other venom install. The installer does not put it on your PATH. |
config/ |
The default orchestrator.yaml and prices.yaml. |
Both processes bind loopback only. The last run's ports are preferred, so URLs stay stable.
Commands
| Command | What it does |
|---|---|
venom-daemon [start] |
Start, or when it already runs just open the dashboard. --no-open: no browser. Idempotent; a stale run record (crash, reboot) is cleaned up first, and two starts at once are serialized by a lock file. |
venom-daemon stop |
Stop venom serve, the console, then the orchestrator, which drains mesh jobs first. |
venom-daemon status |
What runs where, the Venom Cloud connection and self-heal state. --json; exit code 3 when stopped. |
venom-daemon open |
Open the dashboard signed in (starts the daemon if needed). |
venom-daemon logs |
The last lines of the logs. -n 100, -f to follow. |
venom-daemon join |
Connect to Venom Cloud with a join token read from stdin (or the argument), used once and never printed. --cloud URL, --name N, --region R. Starts the daemon without a browser when it is stopped. |
venom-daemon pause / resume |
Stay connected to Venom Cloud but take no new mesh jobs (running ones finish); kept across restarts. |
venom-daemon telegram login|status|logout |
Your own Telegram account for Outreach, logged in on this computer only (Telegram from your own account). login prints the link code you type in Settings, Comms. |
venom-daemon autostart on|off|status |
Start at login; on Linux at boot. The installers turn it on; also a switch in the dashboard. |
venom-daemon computers on|off|status |
Venom Computers on this daemon (Linux with Docker), as the dashboard's card does. on starts the daemon if needed and follows the first enable while it builds the computer image. |
venom-daemon projects add <dir>|remove <dir>|list |
The folders your coding agents can work in (Projects), next to the workspaces Venom Cloud makes, which list shows too; a change restarts venom serve. |
venom-daemon projects delete <workspace> |
Delete a workspace Venom Cloud made, and everything in it. |
venom-daemon shortcut [--remove] |
Create or remove the desktop launch entry. |
venom-daemon uninstall [--purge] |
Stop, remove the launch entries and the install. --purge also leaves Venom Cloud and deletes the data. |
Use the daemon's /v1 API from the CLI or another app: venom-daemon status prints the URL, and the client key is client_key in secrets.json.
export VENOM_BASE_URL=http://127.0.0.1:8787/v1
export VENOM_API_KEY="$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.venom/daemon/secrets.json")))["client_key"])')"
venom doctorState and secrets
Everything lives in one per-user directory (mode 0700): ~/.venom/daemon on macOS and Linux, %LOCALAPPDATA%\Venom on Windows, or $VENOM_DAEMON_DIR.
| Path | What |
|---|---|
secrets.json |
Generated on first run, mode 0600: the admin token, the /v1 client key, the console password and the venom serve token. The launcher hands them to the processes; you never type one. |
projects.json |
The project folders, mode 0600. |
data/ |
The orchestrator's data directory: SQLite, the mesh credential, mesh-settings.json, daemon-update.json, heal-log.jsonl. |
data/telegram/ |
Only after venom-daemon telegram login: your Telegram session and state, encrypted (What is stored where). |
logs/ |
orchestrator.log, console.log, serve.log (one rotation at 10 MiB), upgrade.log. |
run.json |
PIDs and ports of the running daemon. |
handoff/ |
One-time login tokens (The web console). |
orchestrator.yaml |
Optional: replaces the bundled config. |
Signing in without a password. The launcher writes a random token's SHA-256 to handoff/ with a two-minute expiry and opens http://127.0.0.1:<port>/api/auth/handoff?token=…; the console deletes the file on first use. venom-daemon open mints a new link each time.
Local models
While no Ollama is installed, the dashboard shows an Install Ollama card linking to https://ollama.com/download, which you follow yourself; nothing is downloaded for you. Once Ollama runs, the Local models page pulls and selects the recommended models. llmfit (hardware-fit estimates) is used when it is bundled or on PATH; without it the catalog works without the estimate.
Connect to Venom Cloud
- In Venom Cloud, open Daemons, Connect a daemon, and the Desktop app tab: copy the join token (
vjt_…). - In the daemon's dashboard, choose Connect to Venom Cloud and paste it. The cloud URL is prefilled with
https://cloud.usevenom.dev(editable under Advanced, with the daemon's name and region). Or runvenom-daemon joinin a terminal. - The orchestrator enrolls, saves the connection in
data/mesh-settings.jsonand the credential indata/mesh/, and switches to mesh mode at once.
Disconnect drains running jobs, deregisters, and deletes the credential and the settings. The token is used once and never stored. Nothing contacts the cloud until you connect, the daemon only dials out, and provider keys stay on the machine. A daemon whose mesh mode comes from VENOM_CLOUD_URL shows the connection read-only. A headless rented GPU can be set up the same way with Terraform.
One-click launch and start at login
venom-daemon shortcut (the installers run it) creates:
- macOS:
~/Applications/Venom Daemon.app, ad-hoc signed. A copy of the app downloaded in a browser is quarantined and not notarized, so its first open needs right-click, Open (or System Settings, Privacy & Security, Open Anyway). - Linux:
~/.local/share/applications/venom-daemon.desktop(under$XDG_DATA_HOME). - Windows (beta): a Start Menu shortcut,
Venom Daemon.
Start at login runs venom-daemon start --no-open from a LaunchAgent (~/Library/LaunchAgents/dev.usevenom.daemon.plist), a Startup-folder script on Windows, or on Linux a systemd user service (~/.config/systemd/user/venom-daemon.service).
Linux: start at boot. Turning start at login on also lets your user's services run before anyone logs in (loginctl enable-linger), so the daemon comes back after a reboot or power cut on a machine nobody logs in to. From a desktop or SSH session this needs no password. If the system refuses it, the command prints the one line to run (sudo loginctl enable-linger $USER) and the daemon starts at login until you do. venom-daemon autostart status says Start at boot once both hold. A system without a systemd user manager gets an XDG autostart entry (~/.config/autostart/venom-daemon.desktop), which runs at desktop login only.
macOS installer and menu bar app
Venom-Daemon-<v>-macos-<arch>.pkg installs the daemon with a menu bar app:
/Applications/Venom Daemon.appis the only system-wide file (Installer asks for an admin password). It is the menu bar app with the daemon tree inside.- For the logged-in user, not root, the post-install step copies the tree to
~/.venom/releases/, links~/.venom/bin/venom-daemon(so auto-update works as with the script install), turns on start at login, adds a second LaunchAgent for the menu bar app (dev.usevenom.daemon.menubar.plist), removes the old~/Applicationsshortcut and starts both. Other users of the Mac get the same setup the first time they open the app.
The menu bar app calls only the daemon's own API on 127.0.0.1 (/healthz, GET /admin/v1/mesh), every 3 seconds and when the menu opens. Its dot shows the state, each with its own glyph and name so colour is never the only cue: ○ offline, ◌ idle (running, not connected), ◔ connecting, ● connected, ◉ serving (with tokens per second), ◑ paused. The menu has the running jobs and tokens per second, Pause Taking Jobs / Resume Taking Jobs, Open Dashboard, Usage and Earnings in Venom Cloud (the daemon's page in the cloud), Start Daemon / Stop Daemon, Set Up Models…, and Quit Venom Menu (the daemon keeps running).
First run. While the daemon is not connected, the app opens a setup window once: paste a join token (or skip), then tick models to download from the daemon's recommendations for this Mac. Without Ollama the window links to its download page instead.
Uninstall:
"/Applications/Venom Daemon.app/Contents/Resources/uninstall.sh" # keeps ~/.venom/daemon
"/Applications/Venom Daemon.app/Contents/Resources/uninstall.sh" --purge # also leaves Venom Cloud, deletes the dataRun it as yourself. It stops the menu bar app and the daemon (draining), removes both LaunchAgents, the link and the releases, runs venom-daemon uninstall, then removes the app and the installer receipt (sudo asks for your password). --keep-app stops after your own files, for other users of a shared Mac.
Building it yourself
From a venom checkout:
| Command | Output |
|---|---|
make daemon-bundle |
The daemon tree for this machine in dist/daemon-bundle/; then dist/daemon-bundle/bin/venom-daemon starts it. |
make daemon-install |
Install or update the daemon on this machine from the checkout: the installer's steps (start at login, start, Computers) with an archive built here, nothing downloaded. Stamped one patch above the newest daemon release installed, with -local.<commit>; VERSION= overrides. |
make deb VERSION=x.y.z |
The .deb packages in dist/deb/, from the Linux daemon archives of a built release (make release VERSION=x.y.z first). Needs dpkg-deb; DOCKER=1 builds inside a debian:stable-slim container, for a Mac. |
make daemon-pkg VERSION=x.y.z |
macOS only: the .pkg for this Mac in dist/daemon-pkg/, with the menu bar app built by the Command Line Tools' swiftc (clients/macos-menubar). |
make release VERSION=x.y.z |
Every daemon archive for every platform, among the other release files (Releases and signatures). |
The .pkg is unsigned unless the build machine has Apple Developer ID certificates; then it is signed and notarized:
| Variable | What |
|---|---|
DEVELOPER_ID_APP |
A "Developer ID Application" certificate name in the keychain, e.g. Developer ID Application: Your Name (TEAMID1234). Signs every Mach-O and the app with the hardened runtime. |
DEVELOPER_ID_INSTALLER |
A "Developer ID Installer" certificate name: signs the .pkg. |
NOTARY_KEYCHAIN_PROFILE |
A profile made once with xcrun notarytool store-credentials. The signed .pkg is notarized and stapled. Needs both IDs. |
DAEMON_PKG_KEYCHAIN |
Optional: the keychain file holding the identities (CI). |
Notarization is the only network call of the build, and only when asked for.
Auto-update
Off by default. The This daemon card on the dashboard's Local models page shows the running version, an Automatic updates switch, Check now and, when a newer version is known, Update now. While the switch is off nothing contacts GitHub; Check now and Update now are the only requests, and only when you click them. An orchestrator not started by venom-daemon never checks.
Checking is one request for https://github.com/elishahbiz/venom-releases/releases/latest/download/SHA256SUMS with User-Agent: venom-daemon/<version> and nothing else identifying. The daemon archive for this OS and chip in it gives the latest version (semver; a prerelease ranks below its release). With the switch on, the first check is a random 0 to 10 minutes after start, then every 6 hours ±20%; failures back off exponentially with full jitter, capped at 6 hours. The switch and the last result are in data/daemon-update.json.
Applying (Update now, or automatically with the switch on):
| State | What happens |
|---|---|
downloading |
That version's SHA256SUMS, then the daemon archive, into data/updates/. |
verifying |
The SHA-256 must match, else the file is deleted and nothing is unpacked. The archive unpacks beside the running release, which is never touched, and the new launcher must run and print the version. |
waiting_for_idle |
Until no /v1 request or mesh job has been in flight for 30 seconds, at most 30 minutes; then it goes ahead and the drain finishes what runs. |
draining |
Mesh mode tells Venom Cloud to stop dispatching. |
restarting |
The new launcher stops the old daemon the normal way (30 s drain each for /v1 and mesh jobs), re-points ~/.venom/bin/venom-daemon, starts the new release on the same ports and waits for both health checks, then 10 s more. |
done |
The launch entry and start at login run the new launcher. The previous release is kept for rollback; older ones are removed. |
rolled_back |
The new release did not stay healthy: it is stopped and the previous one starts again. Automatic updates skip that version; Update now can still install it. |
failed |
A step before the restart failed; the running daemon was not touched. |
Your secrets.json, data/ and logs/ are never touched by an update. Supported for macOS and Linux installs made by install-daemon.sh or the .pkg; Windows (beta) and other layouts show "Manual updates": run the installer again.
| Variable | What it does |
|---|---|
VENOM_DAEMON_UPDATE_URL |
Replaces the download base, for a mirror. |
VENOM_DAEMON_UPDATE_IDLE, VENOM_DAEMON_UPDATE_MAX_WAIT |
Shorten the idle window and its cap (Go durations; for tests). |
The checksum proves the download matches the published SHA256SUMS; Releases and signatures covers verifying that list's signature.
Self-heal
In daemon mode the orchestrator checks itself every 15 seconds and repairs what it can, with no setting to turn on:
| Check | Fails when | Repair |
|---|---|---|
upstream:<name> (each local backend) |
its health check fails | Re-probe; then also close idle connections; from the third try, Ollama only, unload every model and re-probe. |
model:stuck |
Ollama holds a model more than 5 minutes past its expiry | Unload it. |
mesh |
the lease ran out, or the job channel stayed closed for 90 s | Close idle sockets to the cloud, open a fresh channel, send a heartbeat. |
disk |
under 64 MiB free next to venom.db, or a write failed with "disk is full" |
Checkpoint the WAL, delete the oldest half of the request log (never the newest 1000 rows), vacuum free pages. |
A failing check is retried with backoff (5 s doubling to 5 minutes) up to 6 times, then marked degraded and tried every 15 minutes. Events are kept in data/heal-log.jsonl and shown by GET /admin/v1/heal, venom-daemon status and the dashboard's Self-heal card. Nothing here restarts a process you run yourself or contacts a new host.
Windows (beta) limits
There is no SIGTERM for a windowless process, so stop ends the processes at once: running mesh jobs are cut and the daemon is not deregistered (its lease expires). The launcher is a console program, so the shortcut and login item flash a console window briefly.
Related
- Projects: the folders the daemon serves to coding agents.
- Orchestrator operations: the daemon's admin endpoints.
- Orchestrator environment variables.
- Local or cloud models: pointing the CLI at the daemon.