Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff

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.

Open the Marketplace listingVersion 1.0.5 · free software, pay for the instance

Pick an instance type

SizeInstance types on the listingFits
Large (2 vCPU / 8 GB)t3a.large, t3.large, m5.large, m6i.large, m7a.largeThe platform and its services, with a few agents
XLarge (4 vCPU / 16 GB)t3a.xlarge, t3.xlarge, m5.xlarge, m6i.xlarge, m7a.xlargeHeadroom 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. 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. 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. 3.Copy the instance ID and public IPv4 from the EC2 console (Instances → Instance ID, starting i-).
  4. 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 as admin. 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. 5.Connect Claude. As in Step 3, the first-run setup opens on the Dashboard; paste a subscription token from claude setup-token or an Anthropic API key. Because the image recorded aws-marketplace, the setup also offers Secure this instance: a domain, then a Cloudflare Tunnel. See First-Time Setup and Hardening a Marketplace Install.

Verify

CheckHowExpected
The site serves TrinityOpen https://<public-ip>/The Create your admin account form, valid padlock
ProvenanceSettings → General → Build InfoInstall 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):

PathStatusWhat you do
AWS Marketplace AMIAvailableSubscribe on the listing, launch from the EC2 console, claim the admin in the browser — below
Script install on your own instanceAvailableThe procedure under Procedure
CloudFormation stack (packer/aws/trinity.cfn.yaml)Template in the repo; no one-click Launch Stack link yetCreate 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.large is the size the CloudFormation template defaults to. The prebuilt images are published for linux/amd64 only.
  • •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

1

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

What it does, in order:

  1. 1.Reads the instance's public IP from the instance metadata service (IMDSv2).
  2. 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. 3.Writes /opt/trinity/.env with FRONTEND_PORT=8081 (Caddy owns 80 and 443), FRONTEND_URL=https://<public-ip> and TRINITY_INSTALL_SOURCE=aws-script.
  4. 4.With no ADMIN_PASSWORD in the environment or .env, writes this instance's ID to trinity-data/setup-claim and sets ADMIN_PASSWORD_SOURCE=instance-id. This is the instance-ID claim (step 2).
  5. 5.Obtains a Let's Encrypt certificate for the IP address.
  6. 6.Installs trinity-ip-refresh.timer, which follows a changed public IP (below).
  7. 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.

2

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.

3

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

CheckHowExpected
The site serves TrinityOpen https://<public-ip>/The setup form (or sign-in page), valid padlock
The certificate was issuedcat /etc/trinity/tls-statusok
The recorded addresscat /etc/trinity/public-ipThe instance's current public IP
The refresh timer is activesystemctl status trinity-ip-refresh.timeractive (waiting)
The platform is healthycurl -s http://localhost:8000/health{"status":"healthy",...}
ProvenanceSettings → General → Build InfoInstall 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), default t3a.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 SshCidr if 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.sh as root every five minutes. Keep /opt/trinity owned 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 changes

To 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.