Deploy Venom Cloud on AWS
Create one CloudFormation stack in your own AWS account. Standard is one encrypted EC2 instance with HTTPS and nightly snapshots; Production is an Auto Scaling group behind a load balancer, RDS Postgres with pgvector, Secrets Manager and an S3 bucket for backups.
You sign in to your own AWS account, review the template and create the stack. About ten minutes later Venom Cloud is running in your account. The database, files, secrets and logs stay there, and you pay AWS directly. Nothing is sent to Venom.
Pick a profile when you create the stack:
- Standard: one instance with its own Postgres. The cheapest, and fine for a team that can live with a few minutes of downtime for a reboot or an upgrade.
- Production: one to three app servers in an Auto Scaling group behind an Application Load Balancer with an ACM certificate, RDS for PostgreSQL 17 with pgvector and automated backups, the shared secrets in Secrets Manager and an S3 bucket for backups. It needs a domain. See Production.
- Production-MultiAZ: the same with two to six app servers and a Multi-AZ database (a standby in a second availability zone that RDS fails over to by itself).
Create the stack
In the CloudFormation console choose Create stack, With new resources, then Upload a template file and pick
venom-cloud.yaml(fromdeploy/aws/in a checkout, or the release's assets). If your operator publishes a Launch stack link (see below), it opens the same page with the template filled in.Fill in the parameters. Only the admin email is required.
Parameter Default What it does ProfileStandardStandard,ProductionorProduction-MultiAZ.AdminEmailnone Shown on the setup screen. Nothing is sent to it. Domainempty A host name. Standard: empty means the instance's public IP with a self-signed certificate (your browser warns once). Production: required; the stack refuses to start without it. InstanceTypet3.mediumx86 only: t3.medium/large/xlarge,m6i.large/xlarge/2xlarge. Production sizes each app server with it and picks the database class to match (see Cost).AutoUpdatenoWeekly venom-cloud upgrade(it backs up first and rolls back by itself on a failed health check).The template installs the latest release. To pin one, change
Release: Venom: Versionin the template'sMappingsto a version such as1.4.2before you upload it. The quick-create page shows at most five parameters, so the version is not one of them.Tick I acknowledge that AWS CloudFormation might create IAM resources and create the stack.
Open the Outputs tab when the stack reaches
CREATE_COMPLETE:SetupUrlis where to go. With a domain, first point its A record atPublicIp; the certificate is issued once DNS answers.SetupCodeCommandprints the one-time setup code. Run it with your own AWS credentials. The code is in Secrets Manager, never in the outputs or the instance's boot log.SessionManagerCommandopens a shell on the instance.
Open
SetupUrl, enter the code, name the organisation and give the owner an email and password (the setup screen).
What it creates (Standard)
| Resource | Notes |
|---|---|
| VPC, one public subnet, internet gateway, route table | New, 10.42.0.0/16. |
| Security group | Inbound 80 and 443 from anywhere. No SSH and no key pair. |
| EC2 instance (Ubuntu 24.04 from Canonical's public SSM parameter) | IMDSv2 required, 40 GB encrypted gp3 root volume. |
| Elastic IP | The address survives a reboot. |
| IAM role and instance profile | Session Manager, plus writing one secret and signalling the stack once. |
| Secrets Manager secret | Holds the setup code. |
| Data Lifecycle Manager policy and role | A snapshot of the volume every night at 03:00 UTC, 14 kept. |
On first boot the instance runs the release's install-cloud.sh (the same script as Install on a Linux server: one code path for starting the stack on a host). It generates every secret on the instance into /opt/venom/.env (mode 600, on the encrypted volume, so the snapshots carry it). Postgres 17 with pgvector runs in Docker on the same instance. The only outbound traffic is image pulls, the install script's download, the model providers you configure and, if on, the update checks.
Production
Create it
- Choose
ProductionorProduction-MultiAZand fill inDomain(for examplecloud.example.com). - While the stack is being created, open its Events tab. The
Certificateresource staysCREATE_IN_PROGRESSand its status reason shows a DNS record: a CNAME name and value. Add that record at your DNS provider. ACM issues the certificate a few minutes after the record answers, and the stack carries on. If the domain's zone is in Route 53 in the same account, the ACM console has a Create records in Route 53 button that does it for you. - RDS takes about 10 to 15 minutes (longer for Multi-AZ). The first app servers then boot, install and signal the stack.
- When the stack reaches
CREATE_COMPLETE, point a CNAME for your domain at theLoadBalancerDnsNameoutput (or a Route 53 alias record for a zone apex). - Run
SetupCodeCommand, openSetupUrland set up the organisation as with Standard.
What it creates
| Resource | Notes |
|---|---|
| VPC, two public subnets and two private database subnets in two availability zones | The database subnets have no route to the internet. |
| Application Load Balancer, HTTPS listener and an HTTP listener that redirects to HTTPS | TLS 1.2 or 1.3 (ELBSecurityPolicy-TLS13-1-2-2021-06). Idle timeout 15 minutes, so agent runs can stream. |
ACM certificate for Domain |
DNS validation; ACM renews it by itself while the record stays. |
| Auto Scaling group of app servers | Production: 1 to 3, Production-MultiAZ: 2 to 6, scaled on average CPU (60%). A server the load balancer reports unhealthy (/api/status) is replaced. Updates to the stack replace servers one at a time. |
| Security groups | The load balancer takes 80 and 443 from anywhere; app servers take port 80 from the load balancer only; the database takes 5432 from the app servers only. No SSH anywhere. |
| RDS for PostgreSQL 17 | Encrypted gp3 storage from 50 GB growing to 500 GB, private, automated backups kept 14 days with point-in-time restore, deletion protection on, a final snapshot when the stack is deleted. Multi-AZ with Production-MultiAZ. |
| Secrets Manager secrets | The database password (generated by Secrets Manager), the secrets every app server shares and the setup code. |
| S3 bucket for backups | Private (all public access blocked), encrypted, versioned, HTTPS only, kept when the stack is deleted. |
| IAM role for the app servers | Session Manager, reading the shared and database secrets, writing the shared secrets and the setup code once, signalling the stack, and reading and writing the backup bucket. Nothing else. |
How it works
Each app server runs the same install-cloud.sh as Standard, in its production profile:
- The shared secrets.
VENOM_VAULT_KEYS, the signing keys,AUTH_SECRET,CRON_SECRETand the admin token must be the same on every server. The first server to boot generates them withinstall-cloud.sh --secrets-onlyand stores them in theSharedSecretssecret; every server, including the ones the group adds later, writes them into its/opt/venom/.envbefore it installs. Secrets Manager accepts the first value only (a fixed request token), so two servers booting at once cannot end up with different keys. - The database. RDS's
vectorextension (pgvector) needs no parameter group: the app's migrations runCREATE EXTENSION vectoras the master user. The installer checks that the extension is available before it writes anything. The connection is TLS and checks RDS's certificate against Amazon's CA bundle, which each server downloads once at first boot fromtruststore.pki.rds.amazonaws.com(install-cloud.sh --database-ca). - HTTPS at the load balancer. The certificate lives in ACM. Each server's Caddy answers plain HTTP on port 80, reachable only from the load balancer (
install-cloud.sh --behind-proxy). - Scheduled jobs run once. The app's built-in scheduler claims each minute's job in the database, so one server runs it however many there are. The daily database backup (
venom-cloud backup --scheduled, 03:27 UTC) claims its day the same way (install-cloud.sh --shared-database), so one server takes it. - Upgrades. With
AutoUpdateon, each server upgrades its own image weekly; the database migrations take a lock, so they run once. A failed upgrade rolls the server back to its previous image, but never restores the shared database by itself: that is a decision for a person, with the other servers stopped.
Backups
- RDS automated backups are the backups of record: a daily snapshot and point-in-time restore to any second in the last 14 days, from the RDS console (Actions, Restore to point in time). Restoring creates a new database instance; point the stack's servers at it by hand, or restore into a new stack.
- The daily dump. One app server writes a
pg_dumpand an archive of its install files each day (/opt/venom/backups, the newest 14 kept), then copies both to the S3 bucket. App servers come and go, so the copy in S3 is the one to keep. - The S3 bucket (
BackupBucketNameoutput) holds those copies underbackups/. Its address is in each server's.env(VENOM_BACKUP_S3); the server signs the uploads (SigV4, withopensslandcurl) with its instance role's credentials from IMDSv2 and the region the instance runs in, so no key is stored anywhere. Versioning keeps older copies. The console (Settings, Server backups) can change the schedule, the bucket and how many are kept, and shows the last backup and its object; see Server backups. - Verify restore (in the console, or
venom-cloud verify-restorefrom a Session Manager shell) loads a dump into a scratch database on the RDS instance, checks it and drops it. The stack's database user is the RDS master user, which may create one. - Keep a copy of the
SharedSecretssecret with any backup you take out of AWS:VENOM_VAULT_KEYSopens what the vault sealed.
Day two
Open a shell with SessionManagerCommand (with Production it opens the group's first server), then use venom-cloud status | logs | backup | upgrade | rollback; see Update a self-hosted Venom Cloud. A failed first boot shows in the stack events and in /var/log/venom-first-boot.log.
Cost
Approximate AWS list prices for us-east-1, Linux on-demand, checked against the price list I knew in 2026-11; use the AWS Pricing Calculator for your region before you rely on them.
| Size | Per hour | Per month (730 h) |
|---|---|---|
t3.medium (2 vCPU, 4 GB) |
$0.042 | about $30 |
t3.large (2 vCPU, 8 GB) |
$0.083 | about $61 |
t3.xlarge (4 vCPU, 16 GB) |
$0.166 | about $121 |
m6i.large (2 vCPU, 8 GB) |
$0.096 | about $70 |
m6i.xlarge (4 vCPU, 16 GB) |
$0.192 | about $140 |
m6i.2xlarge (8 vCPU, 32 GB) |
$0.384 | about $280 |
Add about $3.65 for the public IPv4 address, about $3 for the volume, a few dollars for snapshots as the data grows and $0.40 for the secret.
Production adds, per month at the minimum size:
| Item | Approximate |
|---|---|
| The app servers | the table above, times the number running (1 for Production, 2 for Production-MultiAZ), plus $3.65 each for its public IPv4 address |
| Application Load Balancer | about $16, plus about $6 per LCU used |
RDS, single-AZ, for t3.medium to t3.xlarge |
db.t4g.medium about $47, db.t4g.large about $94, db.t4g.xlarge about $188 |
RDS, single-AZ, for m6i.large to m6i.2xlarge |
db.m7g.large about $122, db.m7g.xlarge about $244, db.m7g.2xlarge about $488 |
| RDS storage | 50 GB gp3 about $6.50 (Multi-AZ doubles the instance and storage) |
| RDS backups | free up to the database's size, then about $0.095 per GB |
| Secrets Manager, S3 | $1.20 for three secrets; S3 a few cents per GB |
So the smallest Production (t3.medium) is about $115 a month and the smallest Production-MultiAZ about $205, before traffic.
Tear down
Standard:
- If you want the data, run
venom-cloud backupfirst and copy the dump and/opt/venom/.envsomewhere safe (VENOM_VAULT_KEYSopens everything the vault sealed). - Delete the stack in CloudFormation. That removes the instance, volume, network, IP, secret and snapshot policy.
- Snapshots the policy already made are not part of the stack: delete them in EC2, Snapshots, filtered by the tag
app = venom-cloud.
Production:
- Copy the
SharedSecretssecret's value somewhere safe if you may restore the data later. - Turn off the database's deletion protection: RDS, Databases, the stack's database, Modify, untick Enable deletion protection, apply immediately.
- Delete the stack. RDS takes a final snapshot first; the S3 bucket is kept.
- Delete the final snapshot (RDS, Snapshots) and empty and delete the bucket when you no longer need them.
Publish the Launch stack link (owner)
CloudFormation reads a template from S3 (or an HTTPS URL it can fetch directly; GitHub release assets redirect, so use S3). Once per release, with your own AWS credentials:
aws s3 cp deploy/aws/venom-cloud.yaml s3://YOUR-BUCKET/venom-cloud/1.4.2/venom-cloud.yaml
aws s3 cp deploy/aws/venom-cloud.yaml s3://YOUR-BUCKET/venom-cloud/latest/venom-cloud.yamlThe bucket must allow public reads of that prefix (a bucket policy granting s3:GetObject on venom-cloud/*, with Block Public Access relaxed for it). The link is then:
https://console.aws.amazon.com/cloudformation/home#/stacks/quickcreate?templateURL=https://YOUR-BUCKET.s3.amazonaws.com/venom-cloud/latest/venom-cloud.yaml&stackName=venomAdd ¶m_Domain=cloud.example.com or ¶m_InstanceType=t3.large to preset a parameter. The template is plain YAML meant to be read: customers can open the link and review every resource before they create the stack.
Not in this version
- RDS Proxy.
install-cloud.shalready takes a pooledVENOM_DATABASE_URLand a directVENOM_DATABASE_URL_UNPOOLED, but the template does not create a proxy. - Azure and GCP equivalents.
- A Terraform module for AWS.
Tests
make test-scripts runs scripts/test-aws-template.sh: cfn-lint when installed, plus checks that the template has at most five parameters, no secret in the outputs, only ports 80 and 443 from the internet, IMDSv2, encrypted volumes, every resource tagged and user data that parses as shell. For Production it also checks that every resource sits behind the profile's condition, that a domain is required, the load balancer's certificate and redirect, a private and encrypted RDS 17 with automated backups and its password from Secrets Manager, a private and versioned bucket, a scoped role, that the shared secrets are seeded once, and that every installer flag the first boot passes exists in install-cloud.sh. scripts/test-install-cloud.sh covers those installer flags. Nothing touches AWS.