Self-hosting Venom Cloud
Run your own Venom Cloud on Vercel and Neon, or locally for development, with every environment variable and make target it reads.
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
You need Docker, Node 24 and, for a real daemon, Go.
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 upstreamsFrom other shells:
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 cloudThe 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
| 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
Nothing in venom creates accounts, projects or secrets: deploying is your step.
- Neon. Create a Postgres 17 project in the region next to your Vercel functions (the defaults are Singapore: Vercel
sin1, Neonaws-ap-southeast-1). Copy the pooled connection string (DATABASE_URL) and the direct one (DATABASE_URL_UNPOOLED; migrations and LISTEN need it). - Vercel. Import the repository with root directory
services/nodejs-cloud.vercel.jsonturns off Git deployments, pins the region, setsmaxDuration800 for the daemon channel and the/v1routes, and runs/api/cron/sweepevery minute. - Environment variables from the table below.
- Migrate, then deploy. Run
bun run migrateinservices/nodejs-cloudwithDATABASE_URL_UNPOOLEDpointing at production (forward-only, one transaction per file, an advisory lock), then build and deploy. Check it withmake cloud-smoke URL=https://<your domain>. - 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
All are server-side. The only NEXT_PUBLIC_ value is Clerk's publishable key.
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. |
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). 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
| 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)
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
| 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
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
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
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.
- Attach the new domain to the same deployment and point its DNS there.
- Set
VENOM_CLOUD_ALT_ORIGINS=https://<new domain>and redeploy.VENOM_CLOUD_ORIGINstays 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. - 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. - Swap the two:
VENOM_CLOUD_ORIGIN=https://<new domain>andVENOM_CLOUD_ALT_ORIGINS=https://<old domain>. If you setVENOM_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. - 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
| 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), 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: connect daemons to your cloud.
- The public site and docs routes: what your deployment serves publicly.
- Venom Cloud overview.