---
title: The desktop daemon
description: 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.
section: deploy
order: 50
audience: [user, operator]
sources: [docs/daemon.md, scripts/release/deb.sh, docs/adr/0031-daemon-auto-update.md, services/go-orchestrator/cmd/venom-daemon, services/go-orchestrator/internal/daemon, clients/macos-menubar, scripts/daemon-bundle.sh, scripts/release/daemon-pkg.sh]
features: [deploy.desktop-daemon]
---

`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`](/docs/deploy/compose.md#daemon) does the same job with Docker.

## Install {#install}

```bash
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-daemon.sh | sh   # macOS, Linux
```

```powershell
irm 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](#launch) (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](/docs/computers/enable.md) 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](#macos)). Downloads are on the [releases page](https://github.com/elishahbiz/venom-releases/releases) and https://cloud.usevenom.dev/daemon.

## Ubuntu and Debian: the .deb {#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:

```bash
sudo apt install ./venom-daemon_<v>_amd64.deb
```

The 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](#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](/docs/deploy/releases.md#verify).

## What runs {#layout}

| 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](/docs/comms/telegram-personal.md#helper)). |
| `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](/docs/deploy/projects.md), and [Venom Computers](/docs/computers/enable.md) 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 {#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](/docs/comms/telegram-personal.md)). `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](/docs/deploy/projects.md)), next to the workspaces Venom Cloud makes, which `list` shows too; a change restarts `venom serve`. |
| `venom-daemon projects delete <workspace>` | Delete a [workspace](/docs/deploy/projects.md#workspaces) 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`.

```bash
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 doctor
```

## State and secrets {#state}

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](/docs/deploy/projects.md), 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](/docs/comms/telegram-personal.md#storage)). |
| `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](/docs/deploy/console.md#handoff)). |
| `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 {#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 {#cloud}

1. In Venom Cloud, open Daemons, Connect a daemon, and the **Desktop app** tab: copy the join token (`vjt_…`).
2. 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 run `venom-daemon join` in a terminal.
3. The orchestrator enrolls, saves the connection in `data/mesh-settings.json` and the credential in `data/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](/docs/deploy/byod-gpu.md).

## One-click launch and start at login {#launch}

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

`Venom-Daemon-<v>-macos-<arch>.pkg` installs the daemon with a menu bar app:

- `/Applications/Venom Daemon.app` is 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 `~/Applications` shortcut 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:**

```bash
"/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 data
```

Run 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 {#build}

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](/docs/deploy/releases.md)). |

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 {#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](/docs/deploy/releases.md#verify) covers verifying that list's signature.

## Self-heal {#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 {#windows}

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](/docs/deploy/projects.md): the folders the daemon serves to coding agents.
- [Orchestrator operations](/docs/orchestrator/operations.md#daemon): the daemon's admin endpoints.
- [Orchestrator environment variables](/docs/orchestrator/environment.md#daemon).
- [Local or cloud models](/docs/getting-started/local-or-cloud.md#daemon): pointing the CLI at the daemon.
