Getting Started/Deploying Trinity/Single Server

Single-Server Deployment

Run Trinity on a Linux VPS or dedicated server with a stable public URL. This guide uses docker-compose.prod.yml, which disables hot-reload, adds health checks and restart policies to every service, and keeps Redis off the public network.

Prerequisites

•Linux server (Ubuntu 22.04 LTS or later recommended), minimum 8 GB RAM
•Docker Engine 24+ and Docker Compose plugin (docker compose — no hyphen)
•A domain or subdomain pointing to your server's IP (e.g., trinity.your-domain.com)
•openssl on the server for secret generation
•Outbound HTTPS access from the server (for Docker image pulls and Anthropic API calls)

1. Clone the Repository

git clone https://github.com/abilityai/trinity.git
cd trinity

2. Configure `.env`

cp .env.example .env

Security-critical (must be set before first boot)

Variable	How to generate	Notes
SECRET_KEY	`openssl rand -hex 32`	JWT signing key. Never reuse across instances.
ADMIN_PASSWORD	Choose a strong password	Minimum 12 characters. Drives both `admin` login and the MCP server's legacy auth path. Required — `docker-compose.prod.yml` refuses to render if unset (issue #692).
CREDENTIAL_ENCRYPTION_KEY	`openssl rand -hex 32`	Encrypts OAuth tokens and credentials. If lost, all encrypted credentials become unrecoverable.
INTERNAL_API_SECRET	`openssl rand -hex 32`	Authenticates scheduler-to-backend calls.
REDIS_PASSWORD	`openssl rand -hex 24`	Admin/default ACL user. For recovery and ad-hoc ops.
REDIS_BACKEND_PASSWORD	`openssl rand -hex 24`	Runtime ACL user for `backend` and `scheduler`. Required — compose refuses to render without it.

Generate all six at once:

echo "SECRET_KEY=$(openssl rand -hex 32)"
echo "CREDENTIAL_ENCRYPTION_KEY=$(openssl rand -hex 32)"
echo "INTERNAL_API_SECRET=$(openssl rand -hex 32)"
echo "REDIS_PASSWORD=$(openssl rand -hex 24)"
echo "REDIS_BACKEND_PASSWORD=$(openssl rand -hex 24)"

Redis security note: Trinity uses two separate Redis passwords by design. REDIS_BACKEND_PASSWORD is the runtime credential embedded in REDIS_URL for the backend and scheduler containers. Even if a platform container were compromised and this password leaked, it does not grant access to destructive Redis commands (FLUSHALL, CONFIG, SHUTDOWN) — those require REDIS_PASSWORD.

Required for agent functionality

Variable	Notes
ANTHROPIC_API_KEY	Required for agents to run Claude. Can be left blank and configured in Settings after login.
GITHUB_PAT	Required to clone private GitHub template repos.

Required for production access

Variable	Notes
FRONTEND_URL	Your public-facing domain (e.g., `https://trinity.your-domain.com`). Used for OAuth redirect callbacks and email verification links.
PUBLIC_CHAT_URL	The externally reachable URL for public chat links and webhooks. Often the same as `FRONTEND_URL`. Leave blank if all users access via VPN.

Email authentication

Variable	Notes
EMAIL_PROVIDER	`resend` (recommended), `sendgrid`, `smtp`, or `console` (dev only)
RESEND_API_KEY	Required when `EMAIL_PROVIDER=resend`.
SENDGRID_API_KEY	Required when `EMAIL_PROVIDER=sendgrid`.
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASSWORD / SMTP_FROM	Required when `EMAIL_PROVIDER=smtp`.

Data path

The prod compose uses a bind-mount directory for trinity.db instead of a named Docker volume. Use an absolute path on a server for clarity:

TRINITY_DATA_PATH=/srv/trinity-data

Create the directory before starting:

mkdir -p /srv/trinity-data

3. Build the Base Agent Image

./scripts/deploy/build-base-image.sh

Required before you can create any agents. Takes 5–10 minutes on first build.

4. Build and Start Platform Services

docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d

This starts: backend, frontend, redis, mcp-server, scheduler, vector, and otel-collector.

The cloudflared tunnel service is not started by default — it requires an explicit --profile tunnel flag. See the Public Access guide.

5. First Login

Open your domain in a browser. Log in with:

Username: admin
Password: the ADMIN_PASSWORD you set in .env

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

6. Connect from Claude Code

Create an MCP API key first:

Go to Keys in the top navigation

Create a new key and copy it

Then connect from your Claude Code session:

/trinity:connect
# URL: http://your-server:8080/mcp  (or https://trinity.your-domain.com/mcp if behind a reverse proxy)
# API Key: (your MCP API key)

Restart vs. Down

Use docker compose restart, not down/up. docker compose down removes the trinity-agent-network, which orphans every running agent container — they keep running but lose their network and have to be removed and recreated. restart preserves both the agents and the network.

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

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

Verify Service Health

# 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

See the Monitoring guide for the full health check reference.

Local Development Public Access