Skip to content
Docs menu

Self-host Venom Cloud

Run the Venom Cloud workspace on your own server with Docker Compose, your own Postgres and a built-in cron runner, with no Vercel or Neon.

View .md

The same app and data model that run Venom Cloud run on one server you own. Nothing has to move into Venom's infrastructure: the workspace, its Postgres and its scheduled jobs all stay on your machine, and the only outbound calls are to the model providers you configure.

What you get

  • venom-cloud: the Next.js app as a container (Node 24, non-root, read-only root filesystem). It applies its migrations on start.
  • A built-in cron runner. It calls the same routes on the same schedules as services/nodejs-cloud/vercel.json with CRON_SECRET, once a minute. A cron_runs table lets replicas race for each duty, so none runs twice. It does nothing on Vercel.
  • Postgres 17 with pgvector (the postgres service of the cloud profile) and the orchestrator.
  • Optional HTTPS through Caddy (the cloud-tls profile).

Install

The one-command installers are shorter: on a Linux server, with HTTPS, or on a Mac, for that computer only at http://localhost:8080. From a venom checkout:

  1. Generate the secrets into .env. Nothing is printed or sent anywhere; an existing value is kept.

    scripts/cloud-env.sh --domain cloud.example.com
  2. Start it.

    docker compose --profile cloud --profile cloud-tls up -d --build

    For a public host set CLOUD_TLS_BIND=0.0.0.0 in .env so ports 80 and 443 are published; Caddy then gets a certificate for CLOUD_DOMAIN by itself. Without cloud-tls the app listens on 127.0.0.1:3100 only.

  3. Open https://<your domain> (or http://127.0.0.1:3100) and sign in to the console with VENOM_CLOUD_ADMIN_TOKEN, or with VENOM_CLOUD_CONSOLE_PASSWORD if you set one.

Back up .env: VENOM_VAULT_KEYS opens every provider key and content body the vault sealed.

Install from a .deb

On Ubuntu or Debian, a release built there also carries venom-cloud_<v>_all.deb. It holds that release's installer and one command:

sudo apt install ./venom-cloud_<v>_all.deb
sudo venom-cloud-setup

venom-cloud-setup runs the release's install-cloud.sh pinned to the package's version, with every flag passed through (--domain, --email, --yes, --dry-run, --help). Installing the package changes nothing else: the installer asks its questions and pulls its images only when you run it, as it does when downloaded. The package depends on curl, openssl and ca-certificates and recommends Docker. The venom-cloud command the installer leaves in /usr/local/bin is a different thing and is not shipped by the package; removing the package does not remove an install. Check the file against SHA256SUMS as for any download.

Environment

Name What
CLOUD_DB_PASSWORD the Postgres password (the database is not published beyond loopback)
VENOM_CLOUD_ADMIN_TOKEN admin API and console login
VENOM_VAULT_KEYS <kid>:<base64 32 bytes>; seals stored keys
VENOM_MESH_SIGNING_KEYS, VENOM_POLICY_SIGNING_KEY Ed25519 signing keys for tickets and policy
VENOM_RTC_ICE_SERVERS, VENOM_RTC_TURN_URLS, VENOM_RTC_TURN_SECRET, VENOM_RTC_TURN_TTL_S STUN and TURN servers for the live view of a computer over WebRTC; unset uses one public STUN server, which sees IP addresses only (watch and control)
VENOM_RTC_CF_TURN_KEY_ID, VENOM_RTC_CF_TURN_TOKEN optional: Cloudflare's managed TURN service instead of (or beside) your own coturn. Unset, the cloud never calls Cloudflare's API; set, it asks Cloudflare for a short-lived credential each time a live view opens, and Cloudflare sees the peers' IP addresses but not the encrypted stream (managed TURN)
CRON_SECRET what the built-in runner sends to /api/cron/*
AUTH_SECRET signs the console session
VENOM_CLOUD_ORIGIN, CLOUD_DOMAIN, CLOUD_TLS_BIND, CLOUD_PORT where it is served
VENOM_PRIVATE_BASE_URLS optional: comma-separated origins on your own network that provider base URLs may use, for example http://ollama:11434 (only those exact origins; ignored outside the self-hosted image). See where models come from

Build the image yourself

The image builds from the repository root, because the docs bundle reads docs/public:

docker build -f services/nodejs-cloud/Dockerfile -t venom-cloud .

Release images

The release workflow builds the image for amd64 and arm64 and pushes it to ghcr.io/elishahbiz/venom-cloud:<version>. The digest is listed in the release as venom-cloud-<version>.image and covered by its SHA256SUMS, so pulling it does not need the private source repository.

First visit: the setup screen

A fresh install has no organisation. On start, the server prints a one-time setup code in its logs:

docker compose logs venom-cloud

Open /setup (any other page sends you there; the page exists only where the image sets VENOM_CLOUD_SELFHOSTED=1, which the official image does), enter the setup code, name the organisation and give the owner an email address and a password of at least 12 characters. You land in the console signed in as that owner; later you sign in with the same email and password. The admin token still works as the operator's way in.

The setup is safe to leave on a reachable port:

  • Without the setup code, which is derived from your secrets, nothing happens. Wrong codes count against the sign-in rate limit.
  • It works once. The organisation, the owner and a single-use marker are written in one transaction, so two people racing each other cannot both succeed.
  • It disappears (/setup answers 404) as soon as any organisation exists, including one created some other way.
  • It does not exist on the hosted Venom Cloud, only in this image.

No GitHub or Clerk app is needed.

Checking an install

make smoke STAGES=cloud-selfhost builds the image, starts the cloud profile with fresh secrets and checks the migrations, the setup screen, and a cron duty answering 200 (and 401 without the secret).