---
title: Put venom behind Venom Cloud for a team
description: Give a team one Venom Cloud endpoint, a key and budget per person, provider keys or your own GPU box as a daemon, and the shared policy, then point everyone's venom at it.
section: cookbook
order: 40
audience: [operator, user]
sources: [cli/src/cloud-command.ts, cli/src/cloud-backup.ts, cli/src/mcp-command.ts, services/nodejs-cloud/README.md, services/nodejs-cloud/lib/budget/guards.ts, services/go-orchestrator/internal/mesh, docs/cloud-mesh.md, docs/daemon.md]
features: []
---

Venom Cloud is one OpenAI-compatible endpoint for a team. Behind it, requests go to the providers your organisation
connected, to your own machines running the orchestrator in mesh mode ("daemons"), or to public nodes you trust.
Daemons only dial out, and their provider keys never leave them. This recipe sets up a team of a few people with one
GPU box.

You need an admin who creates the organisation, and each member's machine with the `venom` CLI
([install](/docs/getting-started/install.md)).

## 1. Create the organisation and your key {#org}

[Sign up](/auth/clerk/sign-up), name the organisation and follow Get started: it creates your first key (`vck_…`,
shown once) and shows the install-and-test commands ([Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md)).
You are the owner.

## 2. Invite the team {#members}

- **Settings → Tenants & key groups**: create a key group per group that shares keys, models and budgets (for
  example `platform`). A key group holds API keys, daemons, policies and GPU grants, not people; to group people,
  use [org teams](/docs/cloud/teams.md).
- **Settings → Members → Invite a member**: invite by email and pick a role. Owners and admins manage the
  organisation; a member needs a role that can write keys (owner, admin or developer) to approve their own
  `venom cloud login`. Roles and what each may do: [members and roles](/docs/cloud/console-orgs-members.md#roles).

## 3. Decide where models come from {#models}

Connect at least one source:

| Source | Set it up in | Keys live |
|---|---|---|
| Your organisation's provider keys (OpenAI, Anthropic, Qwen, Mistral, MiniMax, …) | **Providers** → Add provider | sealed in the cloud's vault (ADR 0028) |
| Your own GPU box or workstation as a daemon | **Daemons** → Connect a daemon (step 4) | on that machine only |
| Trusted public nodes | **Public nodes** and **Routing** | with the node's host |

**Routing** shows the order the cloud tries them in, per model, with a live preview of where a request would go.
Responses carry `x-venom-mesh-mode`, `x-venom-daemon` and `x-venom-daemon-region`, so you can see where each request
ran.

## 4. Join your GPU box as a daemon {#daemon}

On the console, **Daemons → Connect a daemon** mints a join token for a key group (one use, one hour by default) and shows
the command for each way to run the daemon, filled in. Pick one:

**The desktop daemon** (no Docker, macOS, Linux or Windows):

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

It opens its dashboard; paste the join token into "Connect to Venom Cloud". It enrolls and switches to mesh mode
without a restart, and the dashboard pulls models that fit the machine.

**The orchestrator by hand** (a server, a container):

```bash
orchestrator mesh join https://cloud.usevenom.dev -      # paste the vjt_… token on stdin
VENOM_CLOUD_URL=https://cloud.usevenom.dev VENOM_MESH_NAME=gpu-1 orchestrator
```

`mesh join` writes the daemon's key pair under `$VENOM_DATA_DIR/mesh/`; the private key never leaves the machine. In a
container, set `VENOM_MESH_JOIN_TOKEN` instead and the orchestrator enrolls at start. The daemon keeps serving its own
local `/v1` with its own keys as before. `orchestrator mesh status`, `mesh rotate` and `mesh leave` manage the
credential ([mesh mode](/docs/orchestrator/operations.md#mesh); every setting is in
[Connect a daemon](/docs/mesh/connect-daemon.md#settings)).

**From a source checkout**, `make daemon CLOUD_URL=https://cloud.usevenom.dev JOIN=vjt_…` starts the stack with
Ollama, pulls the models that fit the GPU and joins.

Within one heartbeat (10 s) the daemon shows as `active` under **Daemons** with its region, load and models, and
`GET /v1/models` lists what it serves. Without a reachable endpoint, requests are relayed through the cloud (about
one extra round trip). With one (`VENOM_MESH_ENDPOINTS`, for example a Tailscale address), the cloud answers `307`
with a short-lived ticket and the stream goes straight from the daemon to the client.

## 5. Connect each member {#connect}

Each person sets the endpoint and a key for model requests:

```bash
export VENOM_BASE_URL=https://cloud.usevenom.dev/v1
export VENOM_API_KEY=vck_…                    # Settings → API keys, or one an admin made for them
venom doctor
```

and signs the machine in for the team features (the fleet view, shared sessions, handoffs, the signed org policy,
the organisation's MCP servers):

```bash
venom cloud login             # shows a code and opens /device; approve it and pick the key group
venom mcp connect             # sign in to the organisation's OAuth MCP servers up front
venom cloud status            # the cloud, key group and key prefix in use, the pinned policy key
```

`venom cloud login` saves a client key named `venom cli · <machine>` in `~/.venom/cloud.json` (mode 600), pins the
organisation's policy-signing key and fetches the policy. It does not change `VENOM_BASE_URL`. `VENOM_CLOUD_URL` and
`VENOM_CLOUD_KEY`, when set, win over the file; `venom cloud logout` deletes it (revoke the key under Keys to stop it
working). For your own deployment of the cloud, pass `--url`.

On a tailnet with daemons, `export VENOM_NETWORKS=tailnet:<your-tailnet>.ts.net` lets the cloud send that machine
straight to them.

## 6. Budgets, guardrails and policy {#controls}

| Control | Where | What it does |
|---|---|---|
| Per-key limits | **Keys** ([API keys](/docs/cloud/console-api-keys.md)) | models (prefixes with `*`), an expiry, rate limits and a budget per key |
| Budgets | **Budgets** | spend guards per key, key group, member, gear or project, with a forecast of when each crosses its limit |
| Spend cap | **Usage** | the organisation's monthly cap, with a banner from 80 % |
| Guardrails | **Guardrails** | org and key group rules on what leaves a machine, which models, which tools ([guardrails](/docs/security/guardrails.md)) |
| Signed policy | **MCP servers** → Set up signing, then the policy | permission rules and approved MCP servers members' CLIs enforce ([signed policies](/docs/security/policy.md#signed)) |

Members can add their own stricter guardrails in `venom.yaml` and see everything that applies to them with
`/guardrails`.

## 7. Day to day {#daily}

- **Usage** and **Requests**: spend per key, day and model; each request with where it was served.
- `venom fleet`: your and your teammates' running agents. `/handoff @alice` in a session hands it to a teammate,
  who accepts with `venom handoff accept <id>` ([teams of agents](/docs/automation/teams.md)).
- **Audit**: every admin change and export. The compliance pack (Settings → Compliance) is the signed evidence for
  an audit, checked offline with `venom compliance verify` ([compliance packs](/docs/security/audit.md#compliance)).
- `venom cloud backup > org.json` saves the organisation's configuration (never secrets);
  `venom cloud restore org.json` shows what it would change, and `--apply` applies it.
- To stop a daemon, SIGTERM it (it drains running jobs for 30 s, then deregisters), or use Drain and Revoke on its
  page.

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| `401` from `/v1/models` | The key is wrong or revoked. Make a new one under Settings, API keys |
| `venom cloud login` says the organisation has no policy signing | An admin clicks "Set up signing" on the MCP servers page, then log in again |
| `venom cloud login: refused: the Cloud's policy key is not the one pinned` | The organisation rotated its key. Confirm the fingerprint with an admin, then `venom cloud login --trust-new-key` |
| The daemon never shows up | Check it reaches the cloud URL over HTTPS and that the join token was unused and not expired; `orchestrator mesh status` shows the credential |
| A model is listed but requests fail | The daemon serving it is draining or its upstream is down; **Daemons** shows the last error |

## Related {#related}

- [The Venom Cloud section](/docs/cloud.md): the console page by page.
- [Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md).
- [Local or cloud models](/docs/getting-started/local-or-cloud.md#cloud).
- [The daemon mesh](/docs/mesh.md) and [connecting a daemon](/docs/mesh/connect-daemon.md).
- [Orchestrator operations: mesh mode](/docs/orchestrator/operations.md#mesh).
- Venom Cloud API: `/docs/api/cloud`.
