Trinity Ops Agent

Health check

./scripts/status.sh

Lists every trinity-* and agent-* container with its status, then probes the backend (/health on BACKEND_PORT), the frontend (HTTP code on FRONTEND_PORT), Redis (redis-cli ping) and the scheduler (its Docker health status), and prints the checkout's current git commit. It does not probe the MCP server or Vector — use the six-probe list in Monitoring for those.

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

In order, the script:

1. 1Checks CREDENTIAL_ENCRYPTION_KEY. It stops before touching anything if the key is empty in the server's .env, because the backend refuses to start without it once credentials are stored encrypted.
2. 2Backs up the database with backup.sh, and aborts if the backup fails.
3. 3Pulls the latest code from TRINITY_BRANCH (default main).
4. 4Updates the containers. On a source-built install it rebuilds the platform images (backend, frontend, mcp-server, scheduler) and runs docker compose up -d. On a hosted install it runs start.sh --hosted --unattended.
5. 5Sweeps agent restart policies. Agent containers created by older releases are moved to unless-stopped, so they come back after a host reboot. A stopped agent stays stopped.
6. 6Verifies. It checks backend and scheduler health, and whether the running version matches the image it runs in, so a stale platform image is called out rather than missed. It also warns if the PostgreSQL migration history has more than one head, which stops schema migrations from applying.

It does not rebuild the agent base image on a source-built install. That image changes rarely, and rebuilding it forces every agent to be re-deployed. The script tells you when the pulled range touched it, or on a hosted install that a new one was pulled. Agents adopt a new base image on a cold stop and start, and /rebuild-agent rolls it out to agents.

Backup database

./scripts/backup.sh

Takes an on-demand copy into ~/backups/ on the host: for SQLite an online backup (sqlite3 .backup, verified with PRAGMA quick_check — never a raw cp of a live database), for the bundled PostgreSQL container a pg_dump -Fc archive. An external PostgreSQL is not handled — use your provider's tooling. Run before any update or destructive change. Trinity also backs itself up nightly at 03:30 UTC into backups/ under its data directory; this script is for the extra copy you want right now. See Backup and Restore.

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 reach the Trinity UI and API locally while the instance runs on a remote server — the UI at http://localhost:13000 by default (TUNNEL_FRONTEND), the API at http://localhost:18000 (TUNNEL_BACKEND). With SSH_HOST empty it prints the direct local address instead.