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.
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.jsonwithCRON_SECRET, once a minute. Acron_runstable lets replicas race for each duty, so none runs twice. It does nothing on Vercel. - Postgres 17 with pgvector (the
postgresservice of thecloudprofile) and the orchestrator. - Optional HTTPS through Caddy (the
cloud-tlsprofile).
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:
Generate the secrets into
.env. Nothing is printed or sent anywhere; an existing value is kept.scripts/cloud-env.sh --domain cloud.example.comStart it.
docker compose --profile cloud --profile cloud-tls up -d --buildFor a public host set
CLOUD_TLS_BIND=0.0.0.0in.envso ports 80 and 443 are published; Caddy then gets a certificate forCLOUD_DOMAINby itself. Withoutcloud-tlsthe app listens on127.0.0.1:3100only.Open
https://<your domain>(orhttp://127.0.0.1:3100) and sign in to the console withVENOM_CLOUD_ADMIN_TOKEN, or withVENOM_CLOUD_CONSOLE_PASSWORDif 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-setupvenom-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-cloudOpen /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 (
/setupanswers 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).