Skip to content
Docs menu

Put venom behind Venom Cloud for a team

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.

View .md

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).

1. Create the organisation and your key

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). You are the owner.

2. Invite the team

  • 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.
  • 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.

3. Decide where models come from

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

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):

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):

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; every setting is in Connect a daemon).

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

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

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):

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

Control Where What it does
Per-key limits Keys (API keys) 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)
Signed policy MCP servers → Set up signing, then the policy permission rules and approved MCP servers members' CLIs enforce (signed policies)

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

7. Day to day

  • 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).
  • 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).
  • 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

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