Getting Started/Deploying Trinity

Deploying Trinity

Trinity runs your agents 24/7 with scheduling, monitoring, and multi-agent coordination. Choose cloud-hosted for simplicity or self-hosted for complete control.

Cloud Hosted

ability.ai

Zero infrastructure to manage
Instant setup — deploy in 30 seconds
Automatic updates and backups
Pay-per-agent pricing

Best for: Teams who want to focus on building agents, not infrastructure.

Self Hosted

Your infrastructure

Complete data sovereignty
Data never leaves your perimeter
Unlimited agents (free forever)
Full customization

Best for: Enterprises with compliance requirements or teams with DevOps capacity.

Option A: Cloud Hosted (ability.ai)

Create an account

Get your MCP connection URL

After signup, go to Settings > API Keys and copy your MCP server URL.

Connect from Claude Code

/trinity:connect

The skill will ask for your connection URL and save it to your config.

Deploy your first agent

/trinity:onboard

Done! Your agent is now running on ability.ai.

Option B: Self Hosted

Requirements

Docker Desktop (or Docker + Docker Compose)

Git

8GB RAM minimum

Modern web browser

Clone the repo

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

Configure .env

cp .env.example .env

Four variables are security-critical and must be set before first boot:

Variable	How to set
SECRET_KEY	`openssl rand -hex 32`
INTERNAL_API_SECRET	`openssl rand -hex 32`
CREDENTIAL_ENCRYPTION_KEY	Auto-generated on first start if blank. Once set, do not change — encrypted credentials become unrecoverable.
ADMIN_PASSWORD	Choose a strong password (minimum 12 characters). This is the password you use to log in as `admin`.

Port conflicts: The frontend binds :80 by default. If another process already holds :80, add FRONTEND_PORT=8090 (or any free port) to .env.

Build the base agent image

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

Builds trinity-agent-base:latest — the Docker image every agent container inherits. This step is required before you can create any agents.Takes 5–10 minutes on first run.

start.sh will detect a missing base image and build it automatically — you can skip this step if you prefer.

Start services

./scripts/deploy/start.sh

Starts all services (backend, frontend, MCP server, Redis, scheduler, and Vector). If CREDENTIAL_ENCRYPTION_KEY was blank, the script generates it and writes it back to .env.

Open http://localhost (or http://localhost:$FRONTEND_PORT if you remapped) and log in with admin + the password you set in .env.

Connect from Claude Code

First, create an MCP API key in the web UI:

1.Log in to the web UI
2.Go to Settings → Platform API Keys
3.Create a new key and copy it

Then connect:

/trinity:connect

# When prompted, enter:
# URL: http://localhost:8080/mcp
# API Key: (from Settings → Platform API Keys)

Alternatively, use the email-verified login flow when prompted.

Deploy your first agent

/trinity:onboard

Key URLs (Self-Hosted)

Service	URL
Web UI	http://localhost
Backend API docs	http://localhost:8000/docs
MCP Server	http://localhost:8080/mcp

Managing Services (Self-Hosted)

# Start all services
./scripts/deploy/start.sh

# View backend logs
docker compose logs -f backend

# Rebuild platform services after code changes
docker compose build --no-cache backend frontend mcp-server

Stopping services safely

Use docker compose stop to pause services while preserving agent containers and the agent network. Do NOT use docker compose down — it destroys agent containers and the agent network.

Health Verification

Run ./scripts/deploy/verify-platform.sh after any change. For manual probes:

Service	Command
Backend	curl -sf http://localhost:8000/health
Scheduler	curl -sf http://localhost:8001/health
Frontend	curl -sf http://localhost
Redis	docker exec trinity-redis redis-cli ping
MCP Server	curl -sf http://localhost:8080/health
Vector	curl -sf http://localhost:8686/health

Upgrading

# 1. Back up the database first
docker run --rm -v trinity_trinity-data:/data -v $(pwd):/backup alpine \
  cp /data/trinity.db /backup/trinity.db.backup-$(date +%Y%m%d)

# 2. Pull latest changes
git pull origin main

# 3. Rebuild platform services (NOT the base image)
docker compose build --no-cache backend frontend mcp-server

# 4. Restart platform services
docker compose restart backend frontend mcp-server scheduler

# 5. Verify health
./scripts/deploy/verify-platform.sh

To roll back: restore the DB backup → git checkout <previous-sha> → rebuild → restart.

Resource Thresholds

Metric	Warning	Critical	Action
Agent context usage	>70%	>90%	Restart the agent
Host CPU	>70%	>90%	Scale down active agents
Host memory	>80%	>95%	Restart idle agents
Disk usage	>70%	>85%	Archive or prune logs
Container restarts	>3/hour	>10/hour	Check logs for crash loop
DB size	>500 MB	>1 GB	Run log archival

Common Recovery Patterns

Agent stuck at >90% context

docker restart <agent-container-name>

“network not found” error

docker rm <agent-container-name>
docker restart trinity-backend

Database locked

Check for duplicate backend processes (should be exactly one):

docker ps | grep trinity-backend

Backup Strategy

docker run --rm -v trinity_trinity-data:/data -v /your/backup/path:/backup alpine \
  sh -c "cp /data/trinity.db /backup/trinity-$(date +%Y%m%d-%H%M%S).db"

Retain 14 daily backups. The database contains agent state, schedules, chat history, and credentials metadata.

Managing a Running Instance (Ops Agent)

The trinity-ops-public repo is a Claude Code agent for day-to-day Trinity operations. It works against a local installation or any remote server over SSH — configured with a single .env file.

Quick Start

git clone https://github.com/abilityai/trinity-ops-public.git
cd trinity-ops-public

cp .env.example .env
# Edit .env — set SSH_HOST (leave blank for local), ADMIN_PASSWORD, MCP_API_KEY

# Test the connection before launching Claude Code
./scripts/status.sh

# Then launch the ops agent
claude

Connection Modes

Mode	`SSH_HOST`	How commands run
Local	empty	Runs directly on this machine
Remote	IP or hostname	SSH (key or password auth from `.env`)

Skills

Skill	What it does
/status	Health check — backend, scheduler, containers, version
/logs <service> [lines] [errors]	View logs for any service or agent
/restart [service\|all]	Restart services with health verification
/update	Pull latest, rebuild containers, restart, verify
/agents [list\|start\|stop\|logs\|exec]	Manage individual agent containers
/rebuild-agent <name\|--all>	Rebuild agent container(s) from latest base image
/diagnose	Full error scan — logs, restarts, disk, DB integrity
/telemetry	CPU, memory, disk, and container resource stats
/rollback [commit] [backup]	Rollback to a previous commit + optional DB restore
/cleanup [--execute]	Prune Docker images, build cache, old backups
/provision [provider]	Step-by-step guide to provision a new cloud server

Cloud Providers

Use /provision to walk through setup for any of these:

Provider	Size	Cost
Hetzner ← cheapest	CX23 (2 vCPU, 4 GB)	€3.49/mo
DigitalOcean	s-2vcpu-4gb	$24/mo
AWS	t3.medium (2 vCPU, 4 GB)	~$30/mo
Google Cloud	e2-medium (2 vCPU, 4 GB)	~$40/mo
Localhost	Any OS with Docker	Free

Key `.env` Variables

Variable	Default	Purpose
SSH_HOST	empty	Server IP/hostname; empty = local
SSH_USER	ubuntu	SSH username
SSH_KEY	~/.ssh/id_rsa	Private key path (or use SSH_PASSWORD)
TRINITY_PATH	~/trinity	Trinity install dir on the server
ADMIN_PASSWORD	required	Trinity admin login password
MCP_API_KEY	—	MCP server API key
TUNNEL_FRONTEND	13000	Local port when SSH-tunneling to remote UI

Next Steps

Build your first agent

Create and deploy with Claude Code + abilities

Learn the Trinity UI

Dashboard, agent management, monitoring

Architecture deep dive

Multi-agent coordination, event subscriptions, system manifest

Building Agents Using Trinity