Deploy Trinity on AWS
Run Trinity on AWS, in your own account and VPC. The quickest route is the Trinity AMI on the AWS Marketplace: subscribe, launch, and open the address. The other is a script install on an EC2 instance of your own: one command, run as root on a fresh Ubuntu 24.04 instance, installs Docker, a web server with an HTTPS certificate for the instance's public IP, a host firewall, and Trinity itself from prebuilt images. Either way you prove the instance is yours by entering its EC2 instance ID when you create the admin account.
AWS Marketplace AMI
Trinity 1.0.5 is published on the AWS Marketplace as a 64-bit x86 AMI on Ubuntu 24.04 LTS, with Trinity, Caddy, Redis and PostgreSQL baked in. The software is free and the subscription has no end date; you pay AWS for the EC2 instance, its EBS volume and the public IPv4 address. No shell is needed at any point.
Pick an instance type
| Size | Instance types on the listing | Fits |
|---|---|---|
| Large (2 vCPU / 8 GB) | t3a.large, t3.large, m5.large, m6i.large, m7a.large | The platform and its services, with a few agents |
| XLarge (4 vCPU / 16 GB) | t3a.xlarge, t3.xlarge, m5.xlarge, m6i.xlarge, m7a.xlarge | Headroom for several agents running at once |
See Sizing Your Serverto estimate your fleet. Trinity caps every agent's CPU limit at the host's CPU count, so a 2-vCPU instance runs agents with 2 CPUs. An Elastic IP is optional but keeps the address across a stop/start.
Launch and claim
- 1.Subscribe and launch. From the listing, continue to launch into the EC2 console. Give the instance a public IPv4 address and a security group that allows TCP 80 and 443 from anywhere (port 80 carries the certificate validation and a redirect). Keep 22 closed, or open it to your own address only. The instance needs no IAM role and no user data.
- 2.Wait for first boot. It takes a few minutes: the instance reads its public IP, obtains a Let's Encrypt certificate for it, and starts Trinity on the bundled PostgreSQL. Nothing is pulled from the internet except the certificate.
- 3.Copy the instance ID and public IPv4 from the EC2 console (Instances → Instance ID, starting
i-). - 4.Open
https://<public-ip>/— the browser shows no warning. The Create your admin account form asks for the EC2 instance ID — the same claim as the script install (Step 2); enter it and set a password (12+ characters with uppercase, lowercase, a digit and a special character). Email is optional: leave it blank to sign in asadmin. A wrong ID is refused, and the claim is consumed once the admin exists, so the form cannot be used twice. Someone who finds the IP before you cannot take the instance without reading the ID from your AWS account. - 5.Connect Claude. As in Step 3, the first-run setup opens on the Dashboard; paste a subscription token from
claude setup-tokenor an Anthropic API key. Because the image recordedaws-marketplace, the setup also offers Secure this instance: a domain, then a Cloudflare Tunnel. See First-Time Setup and Hardening a Marketplace Install.
Verify
| Check | How | Expected |
|---|---|---|
| The site serves Trinity | Open https://<public-ip>/ | The Create your admin account form, valid padlock |
| Provenance | Settings → General → Build Info | Install source AWS Marketplace |
With a shell on the instance (SSH or EC2 Instance Connect), the script-install checks apply as well: the same files, timer and health endpoint exist on the AMI. Day-two operations are the same too (Managing the instance) — the checkout lives at /opt/trinity, nightly backups land in /opt/trinity/trinity-data/backups/ on the instance's own disk, and after a stop/start without an Elastic IP the certificate follows the new address within about five minutes (below). Take EBS snapshots as well.
Problems with the image itself go to GitHub issues with the aws-marketplace label.
Script install: when to use it
- •You already have an EC2 instance, or want to build it from a plain Ubuntu image rather than the Marketplace AMI.
- •You want the admin password set before the instance is reachable, instead of claiming it in the browser.
- •You can open a shell on the instance (SSH or EC2 Instance Connect).
Three ways onto EC2 run the same installer (start.sh --provision --cloud aws):
| Path | Status | What you do |
|---|---|---|
| AWS Marketplace AMI | Available | Subscribe on the listing, launch from the EC2 console, claim the admin in the browser — below |
| Script install on your own instance | Available | The procedure under Procedure |
| CloudFormation stack (packer/aws/trinity.cfn.yaml) | Template in the repo; no one-click Launch Stack link yet | Create the stack with the AMI ID from your Marketplace subscription; it adds an Elastic IP and a security group for 80/443 |
All three end the same way: open https://<public-ip>/, enter the instance ID, set a password. For any other Linux server, see Single-Server Deployment. For every path side by side, including the DigitalOcean 1-Click, see Deploying Trinity.
Pre-flight
- •An x86_64 instance with 8 GiB of memory.
t3a.largeis the size the CloudFormation template defaults to. The prebuilt images are published forlinux/amd64only. - •Ubuntu 24.04. The installer adds Docker from Docker's Ubuntu repository.
- •A public IPv4 address — auto-assigned by the subnet, or an Elastic IP. An Elastic IP also keeps the address across a stop/start.
- •A security group allowing TCP 80 and 443 from anywhere. Port 80 carries the Let's Encrypt validation and a redirect. Keep 22 closed, or open it to your own address only. The instance needs no IAM role.
- •A Trinity release with AWS support. v0.9.5 and earlier reject
--cloud aws. Releases are listed on the releases page. - •A Claude subscription or an Anthropic API key, to paste in the browser after the install.
Procedure
Run the installer
On the fresh instance, as root:
git clone --depth 1 --branch <release-tag> https://github.com/abilityai/trinity.git /opt/trinity
cd /opt/trinity
./scripts/deploy/start.sh --provision --cloud aws --hosted --unattendedWhat it does, in order:
- 1.Reads the instance's public IP from the instance metadata service (IMDSv2).
- 2.Installs Docker, Caddy and the host firewall. The firewall allows 22, 80 and 443 on the host; the security group decides what actually reaches it.
- 3.Writes
/opt/trinity/.envwithFRONTEND_PORT=8081(Caddy owns 80 and 443),FRONTEND_URL=https://<public-ip>andTRINITY_INSTALL_SOURCE=aws-script. - 4.With no
ADMIN_PASSWORDin the environment or.env, writes this instance's ID totrinity-data/setup-claimand setsADMIN_PASSWORD_SOURCE=instance-id. This is the instance-ID claim (step 2). - 5.Obtains a Let's Encrypt certificate for the IP address.
- 6.Installs
trinity-ip-refresh.timer, which follows a changed public IP (below). - 7.Runs the normal hosted install: pulls the platform images and the agent base image, starts the stack on the bundled PostgreSQL, and waits for the backend to answer.
To skip the claim and set the admin password up front, pass it in the environment: ADMIN_PASSWORD='your-password-here' ./scripts/deploy/start.sh --provision --cloud aws --hosted --unattended. The admin is then admin with that password.
Claim the admin account
Open https://<public-ip>/. The certificate is a real Let's Encrypt certificate for the IP, so the browser shows no warning.
The Create your admin account form asks for one extra field: EC2 instance ID. Find it in the EC2 console under Instances → Instance ID (it starts with i-). Then:
- •Admin email is optional here. Leave it blank to sign in as
admin. - •Password needs 12+ characters with uppercase, lowercase, a digit and a special character.
A wrong instance ID is refused with That instance ID does not match this server. The claim file is consumed when the admin is created, so the form cannot be used twice. Someone who finds the IP before you cannot take the instance: they would also need to read the instance ID from your AWS account. See First-Time Setup → Instance-ID claim.
Creating the admin also deploys the built-in system agent (trinity-system) in the background. On a 2-vCPU instance it runs with 2 CPUs: Trinity caps every agent's CPU limit at the host's CPU count, because Docker refuses a larger one.
Connect Claude
The first-run setup opens on the Dashboard. Connect Claude is the one required step: paste a subscription token from claude setup-token or an Anthropic API key. Trinity checks it with Anthropic before saving it. Because the install recorded aws-script, the setup also offers Secure this instance: a domain, then a Cloudflare Tunnel. See First-Time Setup and Hardening a Marketplace Install.
Verify
| Check | How | Expected |
|---|---|---|
| The site serves Trinity | Open https://<public-ip>/ | The setup form (or sign-in page), valid padlock |
| The certificate was issued | cat /etc/trinity/tls-status | ok |
| The recorded address | cat /etc/trinity/public-ip | The instance's current public IP |
| The refresh timer is active | systemctl status trinity-ip-refresh.timer | active (waiting) |
| The platform is healthy | curl -s http://localhost:8000/health | {"status":"healthy",...} |
| Provenance | Settings → General → Build Info | Install source AWS (install script) |
The full six-probe check is in Monitoring.
When the public IP changes
EC2 gives an instance without an Elastic IP a new public IPv4 after a stop/start. trinity-ip-refresh.timer checks the metadata service a minute after boot and every five minutes after that. When the address changed, it:
- •rewrites the Caddyfile and obtains a certificate for the new IP;
- •rewrites
FRONTEND_URL, but only if it still points at the old IP (a domain you set is kept); - •recreates the backend from the images already on the instance.
It never pulls or upgrades Trinity, and it logs only when something changed or failed. Allow a few minutes after a start before opening the new address. An Elastic IP avoids the change altogether.
No public IPv4 at first boot. The installer stops with this EC2 instance has no public IPv4 address after recording everything that needs no address and installing the refresh timer. Attach an Elastic IP or a public address. Within five minutes the timer finishes the setup and starts Trinity, with no shell needed.
The CloudFormation template
packer/aws/trinity.cfn.yaml creates:
- •one instance from the Trinity AMI (
ImageId), defaultt3a.large(choices:t3a.large,t3.large,m7i-flex.large,t3a.xlarge,t3.xlarge,m7i-flex.xlarge); - •a security group open on 80 and 443, plus SSH from
SshCidrif you set one, with an optional key pair (KeyName); - •an Elastic IP;
- •no IAM role.
The instance goes into a default subnet of the region's default VPC, or into SubnetId (set VpcId with it), and always gets a public IPv4 address. The stack outputs TrinityUrl and InstanceId — the value the setup form asks for. The Trinity AMI boots with no user data and always takes the instance-ID claim, ignoring any password in user data. Use the AMI ID from your Marketplace subscription for your region as ImageId. A one-click Launch Stack link is not published yet; this page will carry it when it is.
Security notes
- •Agents cannot reach the metadata service. The host firewall drops container traffic to
169.254.0.0/16, so an agent cannot read user data or instance-role credentials. - •Container ports are not reachable from off the instance. The backend, MCP server and log collector answer only through Caddy on 80/443, or from the instance itself.
- •The refresh timer runs the checkout's
start.shas root every five minutes. Keep/opt/trinityowned by root and writable by nobody else.
Managing the instance
Day-two commands are the same as on any hosted install, run from /opt/trinity:
cd /opt/trinity
docker compose -f docker-compose.hosted.yml ps # status
./scripts/deploy/stop.sh # stop (never `down`)
./scripts/deploy/start.sh --hosted # start, and apply .env changesTo upgrade, pin the new release in .env, check out the matching tag, and re-run start.sh --hosted — see Upgrading. Automatic database backups land in /opt/trinity/trinity-data/backups/, on the instance's own disk; take EBS snapshots as well. See Backup and Restore.
See also
Deploying Trinity
Every install path, side by side
Single-Server Deployment
The hosted install, .env reference and database backend
Hardening a Marketplace Install
A domain, then a tunnel, a private network, or both
Monitoring
Health probes and recovery patterns
Ops Agent
Day-to-day operations from Claude Code