Skip to content
Docs menu

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.

View .md

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 upstreams

From 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 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

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.

  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

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.

  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

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.