Install Venom Cloud on a Linux server
One command that checks your server, generates the secrets, starts Venom Cloud with HTTPS (on one server, or with your own database server and daily backups) and leaves a venom-cloud command for status, logs, backups, restores and upgrades.
This is the short way to self-host Venom Cloud: one script for a fresh Ubuntu or Debian server, or any Linux host with Docker. On a Mac the same script sets up Venom Cloud for that computer only, at http://localhost:8080: see Install Venom Cloud on a Mac. --local (with --port N, default 8080) does the same on Linux.
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-cloud.sh | shRun it as root, or as a user who can use Docker. It asks a few questions and takes the default when you press Enter:
- the domain (empty: the server's IP address with a self-signed certificate),
- the admin email,
- the size profile: standard (Postgres on this server, the default) or production (your own database server and daily backups; see Production),
- where models come from: ollama (Ollama runs on this server), key (a provider API key) or later (the default: add them in the console); see Where models come from,
- whether to turn on automatic updates (default no). They start as patch releases on Sundays at 04:00 UTC; change the window, the level and the channel in the console under Settings, Updates (Update a self-hosted Venom Cloud).
--channel preview installs the newest release including pre-releases (the default is stable); the console can switch the channel later.
For an unattended install, pass the answers as flags: sh install-cloud.sh --domain cloud.example.com --email you@example.com --profile standard --models later --auto-update no --yes. --dry-run writes the files and does everything except start Docker. Keep secrets out of flags: the database URL comes from VENOM_DATABASE_URL and a provider key from VENOM_PROVIDER_KEY, or from a prompt that does not echo.
What it does
- Checks the server before touching anything. At least 2 CPU cores, 2 GB of memory and 10 GB of free disk, an amd64 or arm64 CPU, ports 80 and 443 free, and the domain resolving in DNS. A problem stops the install with what to change. If Docker is missing it offers to install it with Docker's own script; say no and it tells you how to install it yourself.
- Downloads the release's
SHA256SUMSfrom the public releases repository and checks its minisign signature whenminisignand the signing key are present. The image is pulled by the digest the release lists (venom-cloud-<version>.image, covered bySHA256SUMS), not by a mutable tag. The private source repository is never needed. - Generates every secret on the server into
/opt/venom/.env(mode 600). Nothing is sent anywhere. Back that file up:VENOM_VAULT_KEYSopens everything the vault sealed. - Starts the stack: Postgres 17 with pgvector (standard profile only),
venom-cloud(it applies its migrations on start), Ollama when you chose it, and Caddy, which gets a Let's Encrypt certificate for a domain or makes a self-signed one for an IP. - Checks it and prints the URL and the one-time setup code. Open
/setup, enter the code, name the organisation and give the owner an email and a password. See the setup screen.
Production: your own database server and daily backups
The production profile keeps the database off the app server, so you can size, patch and back up each one separately. It needs Postgres 14 to 17 with the vector extension (pgvector), reachable from the app server.
A second server for the database. Run the installer there with --database-host. It starts pgvector/pgvector:pg17 listening on the address you give, generates its password and writes the connection URL to /opt/venom-db/database-url (mode 600). It never prints the password.
sh install-cloud.sh --database-host --listen 10.0.0.4Let only the app server reach port 5432, on a private network or with a firewall rule: the traffic between the two is not encrypted. A managed Postgres (RDS, Cloud SQL, Azure Database for PostgreSQL) works too: turn on its vector extension and use its URL.
The app server. Copy that file over a channel you trust and install with it:
VENOM_DATABASE_URL="$(cat database-url)" sh install-cloud.sh --profile production --domain cloud.example.comBefore it writes anything, the installer checks that the database answers and has pgvector. It runs that check from a throwaway container with the URL in the container's environment, never on a command line. The URL is kept in /opt/venom/.env only. The stack then has no Postgres container; a pgtools container with Postgres' client tools runs only for backups and restores.
A managed database (RDS and others). A few more options, all used by the AWS Production profile:
| Option | What |
|---|---|
--database-ca FILE |
The database server's CA bundle (for RDS, Amazon's global-bundle.pem). It is copied next to .env and mounted read-only into the app and pgtools, and the URL gets sslmode=verify-full&sslrootcert=…, so the connection checks the server's certificate. |
VENOM_DATABASE_URL_UNPOOLED |
With a pooler in front (RDS Proxy, PgBouncer): the direct URL. The app uses it for migrations and notifications, and backups and restores use it too. Without it, the one URL is used for both. |
--shared-database |
Other app servers use this database too (an Auto Scaling group). Only one of them takes each day's scheduled backup (it claims the day in the database), and a failed upgrade never restores the database by itself. |
--behind-proxy |
A load balancer in front holds the certificate. Caddy answers plain HTTP on port 80 for any host name and keeps the load balancer's X-Forwarded-* headers. Needs --domain, the name the load balancer serves. |
--backup-s3 s3://bucket/prefix |
Where off-site copies of the scheduled backups go. Kept in .env as VENOM_BACKUP_S3: each scheduled backup (the dump and the install's files) is copied there with a SigV4-signed upload, signed with the server's instance role, or with keys you store with venom-cloud backup s3-key. Without it, backups stay on this server's disk only. See Server backups. |
--secrets-only |
Only generate the secrets into DIR/.env and stop: no checks, no Docker. Seeds the secrets that every app server of a group must share. |
Backups. The production profile turns on a daily backup at 03:27 from cron (/etc/cron.d/venom-cloud), written to this server's disk in /opt/venom/backups/: the database dump and an archive of the install's own files (.env, the Caddyfile, the compose file, state/), both mode 600. The newest 14 are kept and older scheduled backups are deleted. Nothing is sent anywhere unless a bucket is set (--backup-s3, or in the console). Once an admin sets a schedule in the console (Settings, Server backups: off, daily or weekly at an hour in the org's time zone, how many to keep, and this disk or the org's own S3-compatible bucket), venom-cloud tick takes the backups instead and the installer's cron line steps aside. See Server backups.
| Flag | Default | What |
|---|---|---|
--backups daily or --backups off |
daily for production, off for standard | the daily backup from cron (a standard install can turn it on too) |
--backup-keep N |
14 | how many scheduled backups to keep |
--backup-dir DIR |
/opt/venom/backups |
where backups go |
Backups taken before an upgrade (pre-upgrade-*) or a restore (pre-restore-*), and the ones an admin asks for in the console (manual-*), are never deleted by the retention.
Verify restore. venom-cloud verify-restore [FILE] (or Verify restore in the console) loads the newest backup, or the one named, into a scratch database venom_verify_<time>, checks that it holds the app's migrations and organisations, and drops it. The live database is never touched. With the production profile the database role needs CREATEDB; without it the check says so.
Restore. venom-cloud backup --list shows the backups, newest first. venom-cloud restore FILE --yes backs up the database as it is now (pre-restore-<time>.sql.gz), stops the app, replaces the database with the backup, starts the app and checks it over HTTPS. Everything written after that backup was taken is lost, which is why it asks for --yes. A restored database also needs its .env: VENOM_VAULT_KEYS opens what the vault sealed, so keep a copy of .env with your backups.
Where models come from
ollama. Adds an Ollama container to the stack (its models live in a Docker volume) and pulls the model you name with
--ollama-model(defaultqwen3:4b;nonepulls nothing).--ollama-url http://10.0.0.9:11434uses an Ollama you already run instead. It must be an address the containers can reach, not127.0.0.1. After the first sign-in, add it in the console: Providers, Add, Other (OpenAI-compatible), base URLhttp://ollama:11434/v1(or your own), and any key, for exampleollama.venom-cloud models pull NAMEpulls more models later.The hosted cloud only calls public HTTPS servers. A self-hosted install may also call the exact origins listed in
VENOM_PRIVATE_BASE_URLS(comma-separated, for examplehttp://ollama:11434). The installer writes the Ollama origin there and nothing else, so another host, port or scheme on a private network is still refused. The setting is ignored outside the self-hosted image.key.
--provider openai,qwenorzai, with the key inVENOM_PROVIDER_KEYor typed at a prompt that does not echo. It goes into.envasOPENAI_API_KEY,QWEN_API_KEYorZAI_API_KEY, and that provider's models serve as soon as the organisation exists. The key is never printed. Other providers (Anthropic, Gemini, Mistral and more) are added in the console.later. Nothing is set up. Add a provider key in the console (Providers), or connect a daemon next to your own GPUs.
The only downloads a model source adds are the Ollama image and the model you named, from the Ollama registry.
The venom-cloud command
| Command | What it does |
|---|---|
venom-cloud status |
The containers, whether the app answers over HTTPS and, with daily backups, the newest one. |
venom-cloud logs [service] |
Follow the logs (venom-cloud, postgres, ollama, caddy). |
venom-cloud backup [file] |
A gzip'd SQL dump of the database, by default in /opt/venom/backups/. Keep .env with it. |
venom-cloud backup --scheduled |
The same plus the files archive and the copy to the bucket, then keeps only the newest --backup-keep scheduled backups (what cron runs; it steps aside once the console sets a schedule). |
venom-cloud backup --list |
The backups, newest first. |
venom-cloud backup s3-key |
Store the access key the S3 copies are signed with in .env (asked without echo, or from VENOM_BACKUP_S3_ACCESS_KEY_ID and VENOM_BACKUP_S3_SECRET_ACCESS_KEY). Without one, the EC2 instance role is used. |
venom-cloud verify-restore [file] |
Restore a backup into a scratch database, check it and drop it. |
venom-cloud tick |
What cron runs every five minutes: reports this server to the console, carries out what an admin asked for there, and runs the automatic update and the scheduled backup when they are due. |
venom-cloud restore FILE --yes |
Back up the current database, replace it with FILE, start the app and check it. |
venom-cloud upgrade [--bundle file] |
Preflight, back up, pull the latest release by digest, migrate, check health, and roll back by itself if it fails. --bundle upgrades from an offline bundle with no network. See Update a self-hosted Venom Cloud. |
venom-cloud rollback |
Back to the release you ran before the last upgrade. |
venom-cloud models list, venom-cloud models pull NAME |
The models of the Ollama in the stack. |
venom-cloud uninstall --keep-data |
Stop the stack and keep the database and certificates. Without --keep-data it asks for --yes and deletes them (with the production profile, your database server is not touched). |
The cron entries are in /etc/cron.d/venom-cloud: venom-cloud tick every five minutes, and venom-cloud backup --scheduled daily when backups are on. On a Mac a LaunchAgent runs venom-cloud tick --up instead, which also starts the stack after a login (how it starts at login). An install from before the tick gets it on its next upgrade (a weekly upgrade --yes line there becomes automatic updates switched on in the console).
How the console reaches the server. The console never holds the Docker socket. It writes what an admin asks for (settings and requests: upgrade, roll back, back up, verify restore, export) into Postgres; venom-cloud tick reads them with psql, does the work on the host and writes back what happened: this server's version, the release it can roll back to, the last backup and verify restore, and the history of upgrades. Every value reaches psql as a variable, never spliced into the SQL. With several app servers on one database (--shared-database), any of them takes a request without a target, and one of them takes each day's scheduled backup.
Automatic updates. Off until an admin switches them on in the console (or --auto-update yes at install). In the maintenance window (a weekday or every day, and an hour, in the org's time zone) the tick takes the newest release its level allows: patch releases of the running minor only, or minor releases too; never a new major version. To find the newest patch while a newer minor is out, it asks for each next patch's SHA256SUMS in turn. The preview channel adds pre-releases, named by the releases repository's CHANNELS file. The upgrade is the same venom-cloud upgrade: preflight, backup, migrate, health check, automatic rollback. The only network calls are to the releases repository and, when a bucket is set, to that bucket.
The export. Download a full export in the console asks a server for a fresh dump and the files archive in one .tar.gz. The tick stores it in Postgres as a large object for 24 hours (up to VENOM_EXPORT_MAX_MB, 2048 by default) and the console streams it to you; after that it is deleted. It holds the secrets in .env, so treat it like the server itself.
How it is tested
scripts/test-install-cloud.sh (in make test-scripts) runs the installer and the venom-cloud command offline, against stand-ins for Docker and the release server. make test-install-cloud-container (also make smoke STAGES=install-cloud; opt-in, a few minutes) runs the real installer in a privileged docker:dind container with no route to the internet, against a local registry and a local release server. scripts/test-install-cloud.sh also covers venom-cloud tick against a stand-in database: the console's requests, the scheduled backups, the S3 copy (its SigV4 signature checked against AWS's documented example), verify restore, the export, and automatic updates in and out of their window, by level and channel. The container test covers a standard install, scheduled backups with retention and a restore, an upgrade to a release that never becomes healthy and rolls back by itself, a good upgrade and a rollback, and the production profile against a --database-host on the same machine.