---
title: Install Venom Cloud on a Linux server
description: 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.
section: deploy
order: 46
audience: [operator]
sources: [scripts/release/public/install-cloud.sh, scripts/publish-release.sh, docs/public/deploy/self-host-cloud.md, scripts/test-install-cloud.sh, scripts/test-install-cloud-container.sh, services/nodejs-cloud/lib/providers/ssrf.ts]
features: []
---

This is the short way to [self-host Venom Cloud](/docs/deploy/self-host-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](/docs/deploy/install-mac). `--local` (with `--port N`, default 8080) does the same on Linux.

```sh
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-cloud.sh | sh
```

Run 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](#production-your-own-database-server-and-daily-backups)),
- 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](#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](/docs/deploy/updates)).

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

1. **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.
2. **Downloads the release's `SHA256SUMS`** from the public releases repository and checks its minisign signature when `minisign` and the signing key are present. The image is pulled by the digest the release lists (`venom-cloud-<version>.image`, covered by `SHA256SUMS`), not by a mutable tag. The private source repository is never needed.
3. **Generates every secret on the server** into `/opt/venom/.env` (mode 600). Nothing is sent anywhere. Back that file up: `VENOM_VAULT_KEYS` opens everything the vault sealed.
4. **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.
5. **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](/docs/deploy/self-host-cloud#first-visit-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.

```bash
sh install-cloud.sh --database-host --listen 10.0.0.4
```

Let 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:

```bash
VENOM_DATABASE_URL="$(cat database-url)" sh install-cloud.sh --profile production --domain cloud.example.com
```

Before 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](/docs/deploy/aws#production):

| 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](/docs/deploy/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](/docs/deploy/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` (default `qwen3:4b`; `none` pulls nothing). `--ollama-url http://10.0.0.9:11434` uses an Ollama you already run instead. It must be an address the containers can reach, not `127.0.0.1`. After the first sign-in, add it in the console: Providers, Add, Other (OpenAI-compatible), base URL `http://ollama:11434/v1` (or your own), and any key, for example `ollama`. `venom-cloud models pull NAME` pulls 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 example `http://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`, `qwen` or `zai`, with the key in `VENOM_PROVIDER_KEY` or typed at a prompt that does not echo. It goes into `.env` as `OPENAI_API_KEY`, `QWEN_API_KEY` or `ZAI_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](/docs/deploy/updates). |
| `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](/docs/deploy/install-mac#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.
