Single-Server Deployment

Trinity ships three complete stacks, not one base file plus overlays. docker-compose.prod.yml and docker-compose.hosted.yml are standalone: each restates the hardening (security_opt, group_add, cap_drop) because nothing else supplies it.

The remaining files are narrow overlays and never a third stack: docker-compose.override.example.yml (the Docker Desktop Vector log source — start.sh copies it to docker-compose.override.yml on Docker Desktop and appends it by name under --hosted), docker-compose.gitea.yml (dev-only: a local Gitea for git-sync testing, layered on the dev file), docker-compose.prod.enterprise.yml (layers the private enterprise submodule onto prod), and docker-compose.sibling.yml (a Redis-only stack for integration tests).

git clone https://github.com/abilityai/trinity.git && cd trinity
cp .env.example .env
# Set ADMIN_PASSWORD, ANTHROPIC_API_KEY, FRONTEND_URL / PUBLIC_CHAT_URL, and an email provider (see the .env sections below)

# Pin the release you want, in .env — `latest` moves on every Trinity release,
# so an unpinned install turns your next re-run into an unscheduled upgrade.
echo 'TRINITY_IMAGE_TAG=v0.9.0' >> .env

./scripts/deploy/start.sh --hosted --unattended

What --hosted changes, and nothing else:

• •Compose file. docker-compose.hosted.yml — docker-compose.prod.yml with every build: block replaced by a GHCR image: reference. Same ports, volumes, networks, .env keys and security posture; a CI guard fails the build if the two files ever disagree.
• •Image tag. TRINITY_IMAGE_TAG selects the image set (default latest). Precedence: a value in the shell or CI → .env → latest. Put it in .env: that is where the pin survives a reboot and whoever runs the next upgrade. Each release publishes v0.9.0, 0.9.0, 0.9, latest and sha-<short> for one digest, so either version spelling works. A pre-release tag (for example v0.9.5-rc1) publishes its own tags but never moves latest.
• •Agent base image. The backend creates agent containers from the local tag trinity-agent-base:latest, which is not a compose service. start.sh --hosted pulls ghcr.io/abilityai/trinity-agent-base:<tag> and tags it locally before bringing the stack up. A bare docker compose -f docker-compose.hosted.yml up -d starts a platform that cannot create a single agent and does not fail until the first agent-create.
• •No fallback to building. A failed pull is fatal and the message names the likely causes: the tag is not published (check the release list), the GHCR package is private (denied / unauthorized — a publishing fault, report it), or no route to ghcr.io. Drop --hosted to build from source instead.
• •Tunnel. A non-empty TUNNEL_TOKEN in .env starts the cloudflared service (--profile tunnel) and persists COMPOSE_PROFILES=tunnel to .env, so later bare docker compose -f docker-compose.hosted.yml stop / logs commands act on the tunnel container too. See Public Access.
• •Build provenance. Not stamped from your checkout — GET /api/version reports the commit the release workflow built.

Everything else — secret generation, the ADMIN_PASSWORD contract, DOCKER_GID detection, the data-directory ownership fix, the 180-second serving poll and the next-steps card — is the same start.sh behaviour described in Local Development → Start Services.

docker compose -f docker-compose.hosted.yml ps
docker compose -f docker-compose.hosted.yml logs -f backend
./scripts/deploy/stop.sh                       # runs `stop`, never `down`; detects the hosted file itself
./scripts/deploy/start.sh --hosted             # start again — and the upgrade command (see Upgrading)

Upgrading a hosted install is a re-run of start.sh --hosted with a new TRINITY_IMAGE_TAG, never a bare docker compose pull (which skips the agent base image and leaves agents on the old runtime) — see Upgrading → Hosted installs.

Open your domain (or http://your-server-ip, or http://your-server-ip:$FRONTEND_PORT) in a browser. Log in with:

• Username: admin (or ADMIN_USERNAME if you changed it)
• Password: the ADMIN_PASSWORD you set in .env (re-applied on every backend boot — change it there, not in the UI, then recreate the backend container with docker compose -f <file> up -d backend; a plain restart does not re-read .env)

There is no setup wizard on a server install: setting ADMIN_PASSWORD provisions the admin account during startup, and the unauthenticated first-run form refuses to run once a usable admin exists. The one exception is a Marketplace 1-Click Droplet created without a password, which deliberately boots with no admin and is claimed in the browser — see DigitalOcean 1-Click. What you see instead is the Dashboard with a fresh install's starter fleet and the first-run setup sequence — a Sign-in email step (so you can log in with email + password), the required Connect Claude step, and optional keys — see First-Time Setup.

After login, go to Settings → Access → Email Whitelist to allow team members to log in via email verification.

/trinity:connect
# URL: https://trinity.your-domain.com/mcp   (the production frontend proxies /mcp to the MCP server)
#      or http://your-server:8080/mcp        (the MCP server's own port, where it is reachable)
# API Key: (your MCP API key)

The /mcp proxy on the production nginx means an install that exposes only ports 80/443 — a tunnel, a reverse proxy, the DigitalOcean 1-Click — still serves MCP at the same hostname as the web UI. Settings → MCP Keys → MCP Server URL sets the URL the UI shows to users; leave it empty to derive it from the hostname.

# Correct way to restart platform services
docker compose -f docker-compose.prod.yml restart backend frontend mcp-server scheduler
# Hosted installs
docker compose -f docker-compose.hosted.yml restart backend frontend mcp-server scheduler

# Full stop (agents will need to be restarted/recreated)
docker compose -f docker-compose.prod.yml down

Since agent containers are created with Docker's unless-stopped restart policy, a down no longer leaves them merely orphaned: dockerd retries each one in a backoff loop against a network that no longer exists, and the roster shows them as stopped while it churns. Recovery: docker compose -f <file> up -d (recreates the network), then docker rm -f each stale agent container and start it again from the UI or Operations → Restart All— the workspace volume holds the agent's data and is untouched by a container removal.

./scripts/deploy/stop.sh runs stop, never down, and reads the running stack's compose label to pick docker-compose.hosted.yml when needed. It does not detect a source-built production stack — on one of those, use the explicit docker compose -f docker-compose.prod.yml stop.

After starting, verify all services are healthy:

# Backend
curl -s http://localhost:8000/health

# Scheduler
curl -s http://localhost:8001/health

# Frontend
curl -s -o /dev/null -w '%{http_code}' http://localhost

# Redis
docker exec trinity-redis redis-cli ping

# MCP Server
curl -s http://localhost:8080/health

# Vector
docker exec trinity-vector wget -q -O - http://localhost:8686/health

The scheduler's port 8001 is not published to the host by either server compose file — probe it from inside the container instead: docker exec trinity-scheduler curl -sf http://localhost:8001/health. See the Monitoring guide for the full monitoring reference.

Trinity serves plain HTTP and terminates TLS outside the application. There is no HTTPS listener in any compose file and no auto-certificate step, so pick one of these before putting an instance on a public address:

Plain HTTP on a public IPv4 with none of the above is the one combination to avoid: credentials and JWTs cross the network in the clear. A provisioned DigitalOcean Droplet — the 1-Click or the installer script below — is the deliberate exception: it ships its own Caddy with a short-lived certificate for the Droplet's IP, and the first-run setup then prompts you to add a domain and a tunnel. Tunnel setup: Public Access.

The Trinity 1-Click is a Droplet image with Docker, Caddy, ufw and a pinned Trinity release already pulled — Option A baked into a snapshot, so first boot pulls nothing.

Trinity is published on the DigitalOcean Marketplace. The button below opens Droplet creation with the Trinity image already selected — choose a region and a size from the table below, then create. You can also find it by searching Trinity under Marketplace when creating a Droplet from the control panel.

Trinity is free and open source; you pay DigitalOcean for the Droplet.

Prefer to choose the admin password and hand over a Claude subscription before the Droplet exists? trinity-do-create.sh gives the same result from your own terminal — see Deploy on DigitalOcean. The sections below (first boot, sign-in, managing the Droplet) apply to both, with four differences: an installer Droplet has its admin account from first boot, takes about six minutes rather than ninety seconds (it installs and pulls everything on first boot), records do-script instead of do-marketplace as its provenance, and has no login banner.

#cloud-config
write_files:
  - path: /etc/trinity/admin-password
    permissions: '0600'
    content: "your-password-here"

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
docker compose -f docker-compose.hosted.yml restart     # restart
docker compose -f docker-compose.hosted.yml logs -f backend

cd /opt/trinity
echo 'TRINITY_IMAGE_TAG=v0.9.1' >> .env
sudo git fetch --tags && sudo git checkout v0.9.1
sudo ./scripts/deploy/start.sh --hosted

scripts/deploy/trinity-do-create.sh gives you the 1-Click result from your own terminal, with the admin password chosen before the Droplet exists — so there is no claim window. It needs doctl installed and signed in (doctl auth init with a write-scoped API token). The step-by-step walkthrough — from installing doctl to adding a domain, with the installer's error messages and how to remove the Droplet — is Deploy on DigitalOcean.

bash <(curl -fsSL https://raw.githubusercontent.com/abilityai/trinity/<release-tag>/scripts/deploy/trinity-do-create.sh)

It asks four questions and writes nothing to your computer:

1. 1Admin password (twice; 12+ characters, guessable prefixes refused). Your username will be admin.
2. 2Claude subscription token — run claude setup-token in another terminal and paste the sk-ant-oat01-… value. An API key is not accepted here; add one later under Settings → Integrations if you prefer.
3. 3Region and Droplet name (defaults offered), then a confirmation that names the monthly cost.

It then creates an Ubuntu 24.04 Droplet (4 vCPU / 8 GB — Trinity's recommended size), attaches every SSH key already on your account, and hands the Droplet a first-boot script that clones the pinned release to /opt/trinity, runs start.sh --provision --cloud digitalocean --hosted --unattended (Docker, Caddy with the IP certificate, the firewall, then the install itself), registers your Claude subscription and assigns it to the seeded agents. Both secrets travel only in the Droplet's own user-data; the firewall blocks containers from reading it back. The script polls https://<ip>/ with certificate verification for up to fifteen minutes and prints the address when it answers. If it times out, open the Droplet's Console and read /var/log/trinity-install.log.

The install records do-script as its provenance, so the first-run Secure this instance step appears exactly as on the 1-Click. Day-two operations are identical — see Managing the Droplet. The script pins the release it was fetched from; set TRINITY_IMAGE_TAG in the environment before running it to pick another.

Every key in .env.example, with the compose files that forward it. A key a compose file does not forward does nothing on that install. Legend: dev = docker-compose.yml, prod = docker-compose.prod.yml, hosted = docker-compose.hosted.yml. Keys marked “commented” ship commented out in .env.example and take effect only when you uncomment them.