---
title: Connect a daemon
description: Put a machine on your org's Venom Cloud mesh with a join token, from the desktop daemon's dashboard, make daemon, or the orchestrator binary, and set its endpoints, location and limits.
section: mesh
order: 20
audience: [operator, user]
sources: [docs/cloud-mesh.md, services/go-orchestrator/internal/mesh/config.go, services/go-orchestrator/cmd/orchestrator/mesh.go, services/go-orchestrator/internal/meshctl/meshctl.go, scripts/daemon.sh, scripts/cloud-daemon.sh, services/nodejs-cloud/README.md]
features: []
---

A daemon needs two things: a join token from the cloud, and an orchestrator that can dial out to the cloud over HTTPS. No inbound port, public IP or firewall change is needed.

## 1. Mint a join token {#token}

In the Venom Cloud console, open Daemons and choose **Connect a daemon** (`/daemons/new`). Pick the key group the daemon will belong to (a key group holds API keys, daemons, policies and GPU grants, not people; the API calls it `team`); the page creates a `vjt_…` token (one use, valid for one hour by default), shows the command for each way of running the daemon with your cloud's URL filled in, and waits for the daemon's first heartbeat. The token is shown once; Join tokens in the console lists unused ones and revokes them.

An admin can also mint one with the admin API: `POST /api/admin/v1/join-tokens` with `{"team_id": "…"}`. A token can live at most 7 days.

## 2. Join and run {#run}

Pick one of these.

### The desktop daemon {#desktop}

On a desktop or a GPU box without Docker, install the desktop daemon (see [Local or cloud models](/docs/getting-started/local-or-cloud.md#daemon)). In its dashboard, paste the token into **Connect to Venom Cloud**. The cloud URL defaults to `https://cloud.usevenom.dev`; change it under Advanced for your own deployment. The daemon enrolls and switches to mesh mode without a restart. Behind the dashboard is the orchestrator's `POST /admin/v1/mesh/connect`, documented in [Orchestrator operations](/docs/orchestrator/operations.md#mesh).

### make daemon {#make-daemon}

From a source checkout with Docker:

```bash
make daemon CLOUD_URL=https://cloud.usevenom.dev JOIN=vjt_… NAME=gpu-sg-1
```

`make daemon` (`scripts/daemon.sh`):

1. creates `.env` from `.env.example` if it is missing;
2. writes `VENOM_CLOUD_URL` and `VENOM_MESH_NAME` to `.env`, so every later `make up` comes back in mesh mode. `CLOUD_URL` must be `https://`; for a cloud on this machine use `make cloud-daemon` (below);
3. passes the join token only to the first start, as `VENOM_MESH_JOIN_TOKEN`. It is never written to `.env` and never echoed; the orchestrator keeps the resulting credential in its data volume;
4. runs the orchestrator and console in Docker, plus Ollama unless one already answers, with the NVIDIA GPU when Docker has the runtime, and `llmfit serve` for the hardware-fit catalog;
5. pulls and selects the recommended default and fast models for this hardware, then prints the `/v1` URL, the mesh state and the console's Local models page.

Without `JOIN`, it assumes the daemon already enrolled. `NAME` defaults to the host name.

### The orchestrator binary {#binary}

With the `orchestrator` binary from a release, or `services/go-orchestrator` built from source:

```bash
# once: enroll; "-" reads the token from stdin, keeping it out of shell history and the process list
orchestrator mesh join https://cloud.usevenom.dev -

# then run in mesh mode
VENOM_CLOUD_URL=https://cloud.usevenom.dev \
VENOM_MESH_NAME=gpu-sg-1 \
VENOM_MESH_GEO=ap-southeast-1 \
VENOM_MESH_ENDPOINTS="tailnet=http://100.101.102.103:8787/v1,acme.ts.net" \
orchestrator
```

`orchestrator mesh join` writes the key pair and `daemon.json` to `$VENOM_DATA_DIR/mesh/` (default `./data/mesh/`, mode 0600) and prints the daemon id and key group. It reads `VENOM_MESH_NAME`, `VENOM_MESH_GEO` and `VENOM_MESH_ENDPOINTS` from the environment for the enrollment.

| Command | What it does |
|---|---|
| `orchestrator mesh join <cloud-url> <vjt_…\|->` | enroll with a join token |
| `orchestrator mesh status` | print the credential as JSON (cloud URL, daemon, tenant and key group (`team`) ids, name, public key, `revoked`, whether `VENOM_CLOUD_URL` is set); no network |
| `orchestrator mesh rotate` | make a new key pair and register it with `POST /api/mesh/v1/rotate`, signed with the old key; a running orchestrator picks it up on its next request |
| `orchestrator mesh leave` | deregister (`POST /api/mesh/v1/deregister`) and delete the credential |

### In a container {#container}

Set `VENOM_MESH_JOIN_TOKEN` next to `VENOM_CLOUD_URL`. When the orchestrator finds no credential in its data directory, it enrolls at start and logs `mesh: joined with VENOM_MESH_JOIN_TOKEN`. Keep the data directory on a volume, and remove the token from the environment afterwards: it is spent.

## Settings {#settings}

None of these is read unless `VENOM_CLOUD_URL` is set or the dashboard connected. A malformed value stops the start with the variable's name; a missing or revoked credential leaves mesh mode off and the local `/v1` serving.

| Variable | Default | What it does |
|---|---|---|
| `VENOM_CLOUD_URL` | unset (mesh off) | the cloud to dial; mesh mode needs this and a credential |
| `VENOM_MESH_JOIN_TOKEN` | none | enroll at start when there is no credential yet |
| `VENOM_MESH_NAME` | the host name | the daemon's name; unique per tenant (`409 daemon_name_taken`) |
| `VENOM_MESH_ENDPOINTS` | none (relay only) | `kind=url[,network]` entries separated by `;`; kinds `public`, `tunnel`, `tailnet`, `lan`. Each URL ends in `/v1`. Plain `http://` only for `lan`, and for `tailnet` on a `100.64.0.0/10` address or a `*.ts.net` name; `tailnet` and `lan` need a network |
| `VENOM_MESH_GEO` | the region of the machine's time zone (`TZ`, else `/etc/localtime`) | `lat,lon` or an AWS-style region code such as `ap-southeast-1`; `none` reports no location |
| `VENOM_MESH_ACCEPT_TEAMS` | empty (any key group the cloud sends) | comma-separated key group ids; tickets and jobs from other key groups are refused locally |
| `VENOM_MESH_MAX_JOBS` | the sum of the upstreams' `max_inflight`, else 16 | concurrent cloud jobs; a positive integer |
| `VENOM_MESH_GPUS` | none (GPUs are not detected for enrollment) | GPUs to advertise, `name:vram_gb` entries separated by `,`, for example `RTX 4090:24,RTX 4090:24` |
| `VENOM_MESH_SERVE_URL` | none | a local `venom serve` (`http://host:port`) that remote agent sessions are forwarded to; turns on `serve` in the daemon's capabilities. Needs `VENOM_SERVER_TOKEN`, which never leaves the machine |
| `VENOM_MESH_SERVE_FILE` | none | instead of `VENOM_MESH_SERVE_URL`: a JSON file whose `serve_url` names the local `venom serve`, re-read while the daemon runs (`serve` is advertised only while it names one). The desktop daemon sets it to its `run.json` once you add a [project folder](/docs/deploy/projects.md) |
| `VENOM_DATA_DIR` | `./data` | where `mesh/daemon.key`, `mesh/daemon.json` and `mesh/cache-salt.key` live |

The same table, with the orchestrator's other variables, is in [Orchestrator environment variables](/docs/orchestrator/environment.md#mesh).

## 3. Check it {#check}

Within one heartbeat (10 s) the daemon shows in the console's Daemons page as `active`, with its region, load and models. A client key of the key group now sees its models in `GET /v1/models`:

```bash
curl -s https://cloud.usevenom.dev/v1/models -H "Authorization: Bearer $VENOM_API_KEY"
curl -s https://cloud.usevenom.dev/v1/chat/completions -H "Authorization: Bearer $VENOM_API_KEY" \
  -H 'content-type: application/json' -H 'x-venom-daemon: gpu-sg-1' \
  -d '{"model":"venom-default","messages":[{"role":"user","content":"hi"}]}' -D - -o /dev/null
```

The response headers `x-venom-daemon`, `x-venom-mesh-mode` and `x-venom-route-reason` show which daemon served and how. On the daemon, `GET /admin/v1/mesh` reports the state (`off`, `connecting`, `connected`, `revoked`, `error`) and running jobs.

## Share, pause, drain, revoke {#manage}

- **Share** with another key group of the tenant: console, Daemons, the daemon, Shares (optionally some models only, with a weight).
- **Pause** without disconnecting: `POST /admin/v1/mesh/pause` on the daemon (and `/resume`). It stays connected and takes no new jobs, across restarts.
- **Drain**: SIGTERM to the orchestrator, or Drain in the console. The daemon stops taking jobs, gives running ones up to 30 s, then deregisters.
- **Revoke** in the console stops it for good: its next call gets `401 daemon_revoked` and it exits mesh mode. To bring the machine back, enroll it again with a new token under a new name: a name stays taken in the tenant, by revoked daemons too.

## Try it on one machine {#local}

`make cloud-dev DAEMON=1` runs a local cloud (Postgres on 127.0.0.1:5433, `next dev` on :3100, a seeded key group and join token) and a real orchestrator in mesh mode on 127.0.0.1:8788. Next to a running `make cloud-dev`, `make cloud-daemon JOIN=vjt_… [NAME=local-1] [PORT=8788]` adds one: it enrolls into `data/cloud-daemon/<name>/` and advertises `lan=http://127.0.0.1:8788/v1,local`, so a client sending `x-venom-networks: lan:local` gets the direct path.

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| Log: `VENOM_CLOUD_URL is set but this daemon has not joined` | no credential in `$VENOM_DATA_DIR/mesh/`: run `orchestrator mesh join`, or set `VENOM_MESH_JOIN_TOKEN` |
| `join failed: … join_token_invalid` | the token is mistyped, used up or revoked: mint a new one |
| `join_token_expired` | past its expiry (default one hour) |
| `daemon_name_taken` | another daemon of the tenant, revoked ones included, has that name: set `VENOM_MESH_NAME` |
| `plan_limit_reached` (403) | the org's plan allows no more daemons |
| `daemon_upgrade_required` | the daemon speaks a protocol major the cloud does not; upgrade the orchestrator |
| Daemon `active` but requests never reach it | the key's key group is not the daemon's or a shared one, the model is not in its list, or `VENOM_MESH_ACCEPT_TEAMS` excludes the key group. The client's `503 no_daemon_available` lists the reasons |
| Every request is relayed | no endpoint, or the client cannot reach it: check `VENOM_MESH_ENDPOINTS` and send `x-venom-networks` for `tailnet` and `lan` endpoints |
| `make daemon` says `CLOUD_URL … is on this machine` | the container cannot reach the host's loopback: use `make cloud-daemon` for a local cloud |

## Related

- [How the private mesh works](/docs/mesh/cloud-mesh.md): paths, tickets, liveness.
- [The public mesh](/docs/mesh/public-mesh.md): enrolling into the public pool instead.
- [Daemon API reference](/docs/mesh/daemon-api.md): what the daemon sends after joining.
