Getting Started/Deploying Trinity/Ops Agent

Trinity Ops Agent

A Claude Code agent for operating a Trinity instance — health checks, log tailing, restarts, updates, rollbacks, diagnostics, and agent management — all from a single .env pointed at any server.

When to Use

Use the ops agent instead of raw Docker commands for day-to-day Trinity operations. It codifies production runbook knowledge into repeatable skills that improve over time.

Use raw Docker only for one-off debugging or when the ops agent itself is unavailable.

Getting It

Clone the public ops repo and configure your .env:

git clone https://github.com/abilityai/trinity-ops-public
cd trinity-ops-public
cp .env.example .env
# Edit .env with your instance's connection details (see Configuration below)

Then open the directory in Claude Code. The repo ships with its own .claude/skills/ so all the ops commands shown below work out of the box.

Configuration

The ops agent connects to a Trinity instance via a .env file in its workspace.

Variable	Required	Default	Description
SSH_HOST	Remote only	—	Server IP or hostname. Leave empty for localhost.
SSH_USER	Remote only	ubuntu	SSH username
SSH_KEY	Remote only	~/.ssh/id_rsa	Path to private key
SSH_PASSWORD	Optional	—	Password fallback if no key
SSH_PORT	Optional	22	SSH port
TRINITY_PATH	Optional	~/trinity	Trinity install directory on the server
ADMIN_PASSWORD	Optional	—	Trinity admin password for API calls
MCP_API_KEY	Optional	—	MCP API key for agent queries

Local mode: Leave SSH_HOST empty. All commands run directly against the local Docker daemon. Remote mode: Set SSH_HOST. Commands are forwarded over SSH.

Day-to-Day Operations

Health check

./scripts/status.sh

Checks all six Trinity services and reports container status, HTTP endpoint responses, and the current git version.

View and diagnose logs

# Backend
./scripts/run.sh "sudo docker logs trinity-backend --tail 100"

# Scheduler
./scripts/run.sh "sudo docker logs trinity-scheduler --tail 50"

# Specific agent
./scripts/run.sh "sudo docker logs agent-myagent --tail 50"

# Errors only
./scripts/run.sh "sudo docker logs trinity-backend 2>&1 | grep -i 'error|exception|traceback'"

Restart services

./scripts/restart.sh

Restarts all platform services using docker compose restart — not down/up, which would orphan running agent containers.

Update Trinity

./scripts/update.sh

Pulls the latest Trinity code, rebuilds platform images (backend, frontend, mcp-server, scheduler), restarts, and verifies health. Does not rebuild the agent base image.

Backup database

./scripts/backup.sh

Copies the SQLite database to /tmp/trinity-<timestamp>.db on the server. Run before any update or destructive change.

Agent management

# List running agents
./scripts/run.sh "sudo docker ps -a --format '{{.Names}}' | grep agent-"

# Start / stop an agent
./scripts/run.sh "sudo docker start agent-myagent"
./scripts/run.sh "sudo docker stop agent-myagent"

# Open a shell inside an agent
./scripts/run.sh "sudo docker exec -it agent-myagent bash"

SSH tunnel (remote instances)

./scripts/tunnel.sh

Opens SSH port-forwarding so you can access the Trinity UI and API locally while the instance runs on a remote server.

Rollback

# Revert to the previous commit
./scripts/run.sh "cd ~/trinity && git checkout HEAD~1"

# Rebuild platform services from the reverted code
./scripts/run.sh "cd ~/trinity && docker compose build --no-cache backend frontend mcp-server"

# Restart
./scripts/restart.sh

Minimum Server Requirements

Resource	Minimum
CPU	1 vCPU
RAM	2 GB
Disk	20 GB
OS	Ubuntu 22.04+

Supported providers: Hetzner Cloud, GCP, AWS, DigitalOcean, any Linux VM, localhost.