Connect a daemon
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.
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
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
Pick one of these.
The desktop daemon
On a desktop or a GPU box without Docker, install the desktop daemon (see Local or cloud models). 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.
make daemon
From a source checkout with Docker:
make daemon CLOUD_URL=https://cloud.usevenom.dev JOIN=vjt_… NAME=gpu-sg-1make daemon (scripts/daemon.sh):
- creates
.envfrom.env.exampleif it is missing; - writes
VENOM_CLOUD_URLandVENOM_MESH_NAMEto.env, so every latermake upcomes back in mesh mode.CLOUD_URLmust behttps://; for a cloud on this machine usemake cloud-daemon(below); - passes the join token only to the first start, as
VENOM_MESH_JOIN_TOKEN. It is never written to.envand never echoed; the orchestrator keeps the resulting credential in its data volume; - runs the orchestrator and console in Docker, plus Ollama unless one already answers, with the NVIDIA GPU when Docker has the runtime, and
llmfit servefor the hardware-fit catalog; - pulls and selects the recommended default and fast models for this hardware, then prints the
/v1URL, 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
With the orchestrator binary from a release, or services/go-orchestrator built from source:
# 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" \
orchestratororchestrator 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
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
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 |
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.
3. Check it
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:
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/nullThe 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
- 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/pauseon 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_revokedand 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
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
| 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: paths, tickets, liveness.
- The public mesh: enrolling into the public pool instead.
- Daemon API reference: what the daemon sends after joining.