---
title: Self-hosting Venom Cloud
description: Run your own Venom Cloud on Vercel and Neon, or locally for development, with every environment variable and make target it reads.
section: cloud
order: 96
audience: [operator]
sources: [services/nodejs-cloud/README.md, services/nodejs-cloud/AGENTS.md, services/nodejs-cloud/vercel.json, services/nodejs-cloud/lib/db/index.ts, services/nodejs-cloud/lib/jobs/timing.ts, services/nodejs-cloud/lib/crypto/envelope.ts, services/nodejs-cloud/lib/http/cron.ts, services/nodejs-cloud/lib/billing/plans.ts, services/nodejs-cloud/lib/guardrails/wire.ts, services/nodejs-cloud/lib/mesh/public.ts, services/nodejs-cloud/lib/public/witness.ts, Makefile]
features: [cloud.env, cloud.make]
---

Venom Cloud is a Next.js app on Postgres. The hosted service runs it on Vercel with Neon, and you can run the same app yourself: for a team that wants its own control plane, or locally while building on it. A self-hosted cloud with no Stripe key has no plans, limits or metering, and with no provider keys of its own it serves only through daemons you connect, so model provider keys never leave your machines.

This page is for people with a source checkout of venom. The commands below run from the repository root.

## Run it locally {#local}

You need Docker, Node 24 and, for a real daemon, Go.

```bash
make cloud-dev                  # Postgres 17 on 127.0.0.1:5433, migrations, next dev on :3100,
                                # then a tenant, a key group, a client key and a join token, printed
make cloud-dev SIM=3            # plus three simulated daemons with a fake upstream
make cloud-dev DAEMON=1         # plus a real Go daemon using your config/orchestrator.yaml upstreams
```

From other shells:

```bash
make cloud-sim N=3 JOIN=vjt_…          # more simulated daemons
make cloud-daemon JOIN=vjt_…           # a real daemon, serving :8788
export VENOM_BASE_URL=http://127.0.0.1:3100/v1 VENOM_API_KEY=vck_…
venom                                  # the CLI through the local cloud
```

The console is at `http://127.0.0.1:3100/`. Its local password is the admin token, `VENOM_CLOUD_ADMIN_TOKEN`, which defaults to a loopback-only development value printed by `make cloud-dev`. The local mesh signing key is generated once into `data/cloud-dev/signing-keys.json`, so daemons' cached keys stay valid across restarts.

### Make targets {#make}

| Target | What |
|---|---|
| `make cloud-dev [SIM=n] [DAEMON=1]` | Everything above: database, migrations, `next dev` on :3100, seeded tenant, key group, client key and join token. |
| `make cloud-db` | Only the local Postgres 17 on 127.0.0.1:5433, as its own compose project (`venom-cloud`), so `make up` and `make down` never touch it. Waits until healthy. |
| `make cloud-db-down [ARGS=-v]` | Stops it; keeps the volume unless `ARGS=-v`. |
| `make cloud-migrate [ARGS=--plan]` | Applies `services/nodejs-cloud/migrations` to the local database; `--plan` lists pending files. |
| `make cloud-sim N=3 JOIN=vjt_… [CLOUD_URL=…]` | Simulated daemons with a fake upstream against a cloud (default the local one). |
| `make cloud-daemon JOIN=vjt_… [CLOUD_URL=…] [NAME=…] [PORT=8788]` | A real Go daemon (the orchestrator in mesh mode) joining a cloud. Enrolls once into `data/cloud-daemon/<name>/`. |
| `make cloud-smoke URL=https://…` | Checks a deployed cloud: status and models; with an admin token also a simulated daemon, one relayed and one direct request. |
| `make cloud-latency URL=… KEY=vck_… [DAEMON=…] [RUNS=20]` | Measures the cloud hop: round trip, route (307), direct and relay time to first token, against the daemon. |
| `make cloud-chaos [LIVE=1]` | The chaos suite: streams killed mid-way, partitions, slow daemons, clock skew, key rotation, 3 regions. Simulated, or `LIVE=1` against the running local cloud. |
| `make test-cloud` | Typecheck, contracts and router tests, app tests (with a throwaway Postgres; `VENOM_CLOUD_TEST_DATABASE_URL` to use yours), console tests, the docs build, the production build. |

## Deploy to Vercel and Neon {#deploy}

Nothing in venom creates accounts, projects or secrets: deploying is your step.

1. **Neon.** Create a Postgres 17 project in the region next to your Vercel functions (the defaults are Singapore: Vercel `sin1`, Neon `aws-ap-southeast-1`). Copy the pooled connection string (`DATABASE_URL`) and the direct one (`DATABASE_URL_UNPOOLED`; migrations and LISTEN need it).
2. **Vercel.** Import the repository with root directory `services/nodejs-cloud`. `vercel.json` turns off Git deployments, pins the region, sets `maxDuration` 800 for the daemon channel and the `/v1` routes, and runs `/api/cron/sweep` every minute.
3. **Environment variables** from the table below.
4. **Migrate, then deploy.** Run `bun run migrate` in `services/nodejs-cloud` with `DATABASE_URL_UNPOOLED` pointing at production (forward-only, one transaction per file, an advisory lock), then build and deploy. Check it with `make cloud-smoke URL=https://<your domain>`.
5. Open the console, sign in with the admin token, create an organisation and a key group, and connect a daemon.

On Vercel Hobby, set both `maxDuration` values to 300, the cron to once a day, and `VENOM_FUNCTION_MAX_DURATION_S=300`. Relayed streams are then cut at 300 s with a `stream_time_limit` event the client can resume.

## Environment variables {#env}

All are server-side. The only `NEXT_PUBLIC_` value is Clerk's publishable key.

### Core {#env-core}

| Variable | Default | What |
|---|---|---|
| `DATABASE_URL` | required | Pooled Postgres URL. |
| `DATABASE_URL_UNPOOLED` | required | Direct Postgres URL, for migrations and LISTEN (poolers refuse both). |
| `VENOM_DB_POOL_MAX` | `10` | Connections per instance. |
| `VENOM_CLOUD_ADMIN_TOKEN` | none | At least 32 characters. The admin API and console answer 503 without it. |
| `VENOM_CLOUD_ORIGIN` | the request's host | `https://<your domain>`: the issuer of direct-path tickets and the daemons' audience. Set it with a custom domain. |
| `VENOM_CLOUD_ALT_ORIGINS` | none | Other origins the same deployment answers on, comma-separated. See [Change the domain](#change-domain). |
| `VENOM_GLOBE_HOST` | none | A second host for Venom Notes (`globe.<your domain>`): its `/` opens the vault and the main host's Notes pages redirect to it. Without it Notes is at `/globe/vault` on your one host. |
| `VENOM_GLOBE_ORIGIN` | `https://` + `VENOM_GLOBE_HOST` | The origin of Venom Notes, accepted by the sign-in's same-origin check. |
| `VENOM_PUSH_VAPID_PUBLIC_KEY`, `VENOM_PUSH_VAPID_PRIVATE_KEY`, `VENOM_PUSH_VAPID_SUBJECT` | none (push off) | Your own VAPID key pair (base64url) and contact (`mailto:` or `https:`) for the Agents app's notifications ([Notifications](/docs/agents/app.md#for-operators-vapid-keys)). With any unset, the switch is hidden and nothing is sent to a push service. |
| `VENOM_COOKIE_DOMAIN` | none | The session cookie's domain (`.<your domain>`), so one sign-in covers both hosts. Without it the cookie is host-only. |
| `VENOM_MESH_SIGNING_KEYS` | none | JSON list of Ed25519 keys (`bun run keygen` prints one). Without it the direct path is off and everything relays. Rotate by putting the new key first and keeping the old one for 10 minutes. |
| `VENOM_POLICY_SIGNING_KEY` | none | Signs organisation policy envelopes and compliance packs (`bun run keygen -- --policy`). |
| `VENOM_VAULT_KEYS` | none | `<kid>:<base64 32 bytes>,…`; the first seals, all open. Generate with `echo "v1:$(openssl rand -base64 32)"` and back it up out of band. Without it organisations can't store provider keys, integration credentials, Stripe keys or per-org signing keys. |
| `CRON_SECRET` | none | Vercel sends it to the cron routes as a bearer token. Without it the cron routes are closed. |
| `VENOM_FUNCTION_MAX_DURATION_S` | `800` | The function limit: 800 on Vercel Pro, 300 on Hobby. The daemon channel lives 30 s less. |
| `VERCEL_REGION` | set by Vercel | The region label in `/api/status` and provider catalog checks. Off Vercel, `VENOM_CLOUD_REGION` (default `sin1`). |
| `VENOM_GUARDRAIL_URL_BASE` | the production domain, else `https://cloud.usevenom.dev` | Where guardrail code pages linked from refusals live. Set it on a self-hosted cloud. |
| `VENOM_RELAY_REDIS_URL` | none | Optional Redis relay bus, only past what Postgres carries. |

### Public mesh {#env-public}

| Variable | Default | What |
|---|---|---|
| `VENOM_PUBLIC_SESSION_KEY` | derived from the admin token | HMAC key for public-mesh session ids. Set it to keep sessions stable across an admin token rotation. |
| `VENOM_PUBLIC_TEST_P_AUDIT_PPM` | `0` | Tests only: raises the audit sampling rate to at least this many parts per million (1 to 1,000,000). Leave unset in production. |

### Sign-in (Clerk) {#env-clerk}

The token login always exists. GitHub, Clerk and single sign-on are optional; the sign-in pages of this section list every sign-in variable. The Clerk keys that the deployment itself reads:

| Variable | What |
|---|---|
| `CLERK_SECRET_KEY` | Server-side Clerk key. With `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, enables Clerk sign-in; either unset and the Clerk routes 404. |
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk's publishable key, compiled into the build: redeploy after changing it. |
| `CLERK_WEBHOOK_SIGNING_SECRET` | `whsec_…` for `/api/clerk/webhook` (organisation and membership sync). Without it the webhook answers 503; memberships still sync at sign-in. |

### Billing {#env-billing}

| Variable | Default | What |
|---|---|---|
| `STRIPE_SECRET_KEY` | none | Turns billing on. Without it: no plans, no limits, no metering, no Stripe call. |
| `STRIPE_WEBHOOK_SECRET` | none | For `/api/billing/webhook`; it answers 503 without it. |
| `STRIPE_PRICE_PLAN_TEAM` | none | The flat annual price (`price_...`, $249 a month) of the Team plan. Checkout sells it at quantity 1. |
| `STRIPE_PRICE_PLAN_BUSINESS` | none | The Business plan's flat annual price. |
| `STRIPE_PRICE_PLAN_ENTERPRISE` | none | The Enterprise plan's flat price, when you sell it through Checkout (otherwise by contact). |
| `STRIPE_PRICE_PLAN_TEAM_MONTHLY`, `STRIPE_PRICE_PLAN_BUSINESS_MONTHLY` | none | Optional monthly prices (20% above annual). Without one the monthly choice is not offered. |
| `STRIPE_PRICE_SEAT` | none | Old per-seat price. Read only to recognise existing seat subscriptions until they are moved to a flat plan price; never sold. |
| `VENOM_LICENSE_PUBKEY` | none | Ed25519 public key (PEM, or 32 raw bytes in base64; comma-separate to roll) that signed licenses for paid self-hosted plans are checked against. |
| `VENOM_LICENSE_CHECK` | on | Set `off` for an air-gapped install: the daily online license check is never made and the license is valid offline until its expiry. |
| `VENOM_LICENSE_SERVER_URL` | Venom's license server | Where the daily check goes (license id and version only). Only with a paid license installed. |
| `VENOM_LICENSE_SIGNING_KEY` | none | Issuer only (the hosted cloud): the Ed25519 private key (PEM) that signs licenses. Never set on a customer install. |
| `STRIPE_PRICE_USAGE` | none | Optional metered price added at Checkout. |
| `STRIPE_PRICE_GLOBE_SEAT` | none | Old per-seat price of the Venom Notes add-on, read only to recognise existing items. Nothing is sold per seat. |
| `STRIPE_PRICE_TASKS_SEAT` | none | Old per-seat price of the Venom Tasks add-on, read only to recognise existing items. |
| `STRIPE_PRICE_FLAGS_SEAT` | none | Old per-seat price of the Venom Flags add-on, read only to recognise existing items. |
| `STRIPE_METER_EVENT_NAME` | none | Usage is reported to Stripe only with it. |
| `VENOM_BILLING_MARKUP` | `1.2` | Multiplier on platform-paid usage before it is metered. |

Organisations' own Stripe accounts for invoicing their customers are connected in the console, not here.

### Cloud provider keys {#env-providers}

Optional: `OPENAI_API_KEY`, `QWEN_API_KEY` (with `QWEN_BASE_URL`), `ZAI_API_KEY` (with `ZAI_BASE_URL`), `TYPESAFE_API_KEY` let the cloud call providers itself, so it serves with no daemon online. Those keys then live in your deployment, and prompts for those models go from it to the provider. Requests are marked `served_by: cloud` or `daemon`, and keys marked `sovereign_only` never reach a cloud-served model.

### Test-only overrides {#env-test}

These point outbound clients at fakes and accept only HTTPS, or HTTP on loopback. Never set them in production.

| Variable | Replaces |
|---|---|
| `LINEAR_API_URL` | Linear's GraphQL endpoint for issue intake |
| `JIRA_API_BASE` | Jira Cloud's base URL for issue intake |
| `STRIPE_API_BASE` | Stripe's API |
| `SLACK_API_BASE` | Slack's API |
| `TELEGRAM_API_BASE` | Telegram's Bot API, for the People bot |

## Change the domain {#change-domain}

A deployment can answer on two domains at once, so you can move to a new one without cutting anything off.
Daemons, MCP clients, API clients and webhooks that use the old address keep working on it.

1. Attach the new domain to the same deployment and point its DNS there.
2. Set `VENOM_CLOUD_ALT_ORIGINS=https://<new domain>` and redeploy. `VENOM_CLOUD_ORIGIN` stays the old origin.
   The new domain now serves the API, the docs and the console. Its sign-in page sends you to the old domain,
   because the sign-in providers still know only that callback address.
3. Add the new domain's callback addresses where you configured sign-in and integrations: Clerk, Google and
   Microsoft calendar clients. A GitHub OAuth app holds one callback address (`/auth/github/callback`): change
   it at the moment you do step 4.
4. Swap the two: `VENOM_CLOUD_ORIGIN=https://<new domain>` and `VENOM_CLOUD_ALT_ORIGINS=https://<old domain>`.
   If you set `VENOM_COOKIE_DOMAIN`, change it to the new domain too. Redeploy. Sign-in, emails and new links
   now use the new domain. People are asked to sign in once more.
5. Keep the old domain attached for as long as anything still calls it.

Single sign-on keeps working on the old domain. An organisation's identity provider holds the addresses of the
domain it was set up on, so `/login?sso=1` and `/auth/sso` are answered on whichever domain they are opened on.
Members of an organisation with SSO sign in at `https://<old domain>/login?sso=1` until its admin adds the new
addresses (Settings → Single sign-on shows them) at the identity provider.

What stays on the old domain until you change it there: daemons (each keeps the address it joined; to move one,
disconnect it in its dashboard and connect it again with the new address), MCP clients (re-add the server with the new
address), and webhook addresses pasted into other tools.

Several other origins are separated by commas. Each must be exactly `https://host`, with no path. An address
that is not in the list is never used in a link or a redirect.

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| Console and admin API answer 503 | `VENOM_CLOUD_ADMIN_TOKEN` is missing or shorter than 32 characters. |
| Every request relays, none go direct | `VENOM_MESH_SIGNING_KEYS` is unset. |
| Daemons reject tickets after a domain change | Keep the old origin in `VENOM_CLOUD_ALT_ORIGINS` (see [Change the domain](#change-domain)), or set `VENOM_CLOUD_ORIGIN` to the new origin and have each daemon leave and join again. |
| `503 vault_not_configured` when adding a provider key or integration | Set `VENOM_VAULT_KEYS`. |
| Migrations fail with a pooler error | Use the direct URL in `DATABASE_URL_UNPOOLED`. |
| Cron work never runs | `CRON_SECRET` is unset, or the platform doesn't call `/api/cron/sweep`. |

## Related

- [Daemons](/docs/cloud/console-daemons.md): connect daemons to your cloud.
- [The public site and docs routes](/docs/cloud/cloud-site.md): what your deployment serves publicly.
- [Venom Cloud overview](/docs/cloud.md).
