{"version":"1.4","created":"2026-04-30T00:00:00.000Z","author":"Ability.ai","changelog":["1.4: Removed the Step 2b healthcheck patch — trinity#443 fixed the /mcp probe upstream, and the old blanket `sed s|/mcp|/health|g` over every Dockerfile now CORRUPTS a fresh install by renaming the base image's /home/developer/mcp-servers to /home/developer/health-servers. Replaced with a read-only diagnostic","1.3: First-run setup now also seeds the instance GitHub token (Settings → GitHub token — fine-grained PAT, Contents: Read) alongside the MCP API key, in both the SSH and local-Docker paths — it is what the default deploy path (create_agent from github:owner/repo) clones with, so a private-repo fleet is unblocked before the first agent is deployed","1.2: Align with Trinity v0.7.0+ first-run flow — mandatory web setup with admin email replaces the removed setup token (#49), OWASP password complexity enforced (generator now keeps a special char), note that start.sh auto-generates AGENT_AUTH_SECRET/REDIS_* and probes DOCKER_GID","1.1: Scaffold the ops agent by cloning trinity-ops-public instead of generating files inline — agents now ship with the full, maintained skill set","1.0.1: Add a /bug-report skill to generated ops agents, and fix six production deploy gaps — port checks, Dockerfile, and macOS sed compatibility","1.0: Initial version — provision a Trinity instance on cloud, remote, or local Docker and scaffold a complete ops agent to manage it"]}
Deploy Trinity
ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. deploy-new-instance vX.Y — recent: <summary>. Then proceed.
Set up a Trinity instance and create a complete operations agent to manage it.
What you'll get:
A running Trinity instance (if fresh install) — your private AI agent orchestration platform
Cloud (ability.ai) — Managed hosting, zero infrastructure to run
Self-hosted, remote server — VPS, GCP, AWS, or any SSH-accessible machine
Self-hosted, local Docker — Docker running on this machine
PATH A: Cloud (ability.ai)
Cloud is fully managed — no server to configure.
Display this message and stop:
## Cloud Deployment
For ability.ai cloud hosting, use the standard connect flow:
1. Sign up at https://ability.ai
2. Go to Settings → API Keys and copy your MCP connection URL
3. Run: /trinity:connect
4. Run: /trinity:onboard (to deploy your current agent)
Ability.ai manages infrastructure — no ops agent needed.
Do not continue to agent generation.
PATH B: Self-Hosted Remote (SSH)
STEP B1: Fresh or Existing?
Use AskUserQuestion:
Question: "Is Trinity already installed on this server?"
Header: "Server Status"
Options:
Fresh install — Trinity is not yet installed
Already running — Trinity is installed and running
STEP B2: SSH Connection Details
Collect the following as three separate AskUserQuestion calls:
SSH Host:
Question: "What is the server's IP address or hostname?"
Example: 34.123.45.67 or my-server.example.com
Store as SSH_HOST
SSH User:
Question: "What SSH username? (common defaults: ubuntu for AWS/GCP, root for DigitalOcean)"
Store both values — you'll write them to Trinity's .env on the server.
Set admin password
Use AskUserQuestion (tool requires ≥2 options):
Question: "Set the Trinity admin password (12–128 chars, must include upper, lower, digit, and a special character)"
Options:
Generate a secure password → run openssl rand -base64 18 | tr '+/' '@#' and show the result; store as ADMIN_PASSWORD (keeps =/@/# — the first-run setup form rejects passwords with no special character)
I'll provide my own → follow up with a second AskUserQuestion to collect it (use the same 2-option constraint: option 1 = "Enter now", option 2 = "Back")
Validate: 12–128 characters with at least one uppercase, one lowercase, one digit, and one special character — Trinity enforces OWASP complexity at first-run setup, so a weaker password fails there. If it doesn't qualify, ask again.
Check port availability
Check all four required ports before starting (ss/netstat are universally available; lsof is not installed on many minimal images):
ssh -i {SSH_KEY} -o StrictHostKeyChecking=no {SSH_USER}@{SSH_HOST} \
"for p in 80 8000 8001 8080; do ss -tlnp 2>/dev/null | grep -q \":$p \" && echo \"IN_USE $p\" || echo \"FREE $p\"; done"
For each port reported IN_USE, use AskUserQuestion (tool requires ≥2 options — structure as choice 1: suggested alternate, choice 2: enter custom) to ask for an alternate:
Port in use
Question
Suggestion
Store as
80
"Port 80 is taken. What port for the frontend?"
8090
FRONTEND_PORT
8080
"Port 8080 is taken. What port for the MCP server?"
8085
MCP_PORT
8000
"Port 8000 is taken. What port for the backend API?"
8100
BACKEND_PORT
8001
"Port 8001 is taken. What port for the scheduler?"
8101
SCHEDULER_PORT
Defaults if port is free: FRONTEND_PORT=80, MCP_PORT=8080, BACKEND_PORT=8000, SCHEDULER_PORT=8001.
Verify firewall / security group
Display this warning and ask the user to confirm before proceeding:
## Open Required Ports
Before Trinity can be reached from outside the server, you need to open
these ports in your cloud firewall / security group:
Port {FRONTEND_PORT} — Web UI
Port {MCP_PORT} — MCP Server (for Claude Code connection)
How to open ports:
AWS → EC2 → Security Groups → Inbound Rules → Add Custom TCP for {FRONTEND_PORT} and {MCP_PORT}
GCP → VPC → Firewall → Create rule: tcp:{FRONTEND_PORT},{MCP_PORT} targeting your instance tag
Hetzner → Cloud Console → Firewall → Add Inbound rule for TCP {FRONTEND_PORT} and {MCP_PORT}
DigitalOcean → Networking → Firewalls → Add Inbound rule for TCP {FRONTEND_PORT} and {MCP_PORT}
VPS / bare metal → ufw allow {FRONTEND_PORT}/tcp && ufw allow {MCP_PORT}/tcp
If you're on a private network or Tailscale, ports only need to be
reachable by your machine — no public firewall rule needed.
Use AskUserQuestion:
Question: "Have you opened ports {FRONTEND_PORT} and {MCP_PORT} on the server's firewall / security group?"
Options: "Yes, done" / "I'm on a private network / Tailscale (no rules needed)" / "Skip — I'll do it later"
If they say "Skip", note that the web UI and MCP server will not be reachable until ports are opened.
Run deployment
Inform the user: "Deploying Trinity — first run takes 10-15 minutes to build the base Docker image."
No healthcheck patch is needed — and do not apply the old one. The MCP server's HEALTHCHECK has probed /health since trinity#443; the "/mcp returns 400, container reports (unhealthy)" bug this step used to work around is fixed upstream.
The retired workaround was a blanket find . -name Dockerfile | xargs grep -l '/mcp' | sed -i 's|/mcp|/health|g', and running it today corrupts the install: the only remaining /mcp substrings in the tree are a comment and the agent base image's /home/developer/mcp-servers directory, which the substitution renames to /home/developer/health-servers.
If a container really does report (unhealthy), read the actual probe before changing anything:
Set the three critical variables (start.sh auto-generates the other required secrets — AGENT_AUTH_SECRET, REDIS_PASSWORD, REDIS_BACKEND_PASSWORD — and auto-probes DOCKER_GID on fresh installs; note /update never regenerates them, so don't remove them from .env later):
ssh -i {SSH_KEY} -o StrictHostKeyChecking=no {SSH_USER}@{SSH_HOST} "
cd ~/trinity
sed -i 's|^SECRET_KEY=.*|SECRET_KEY={SECRET_KEY}|' .env
sed -i 's|^INTERNAL_API_SECRET=.*|INTERNAL_API_SECRET={INTERNAL_API_SECRET}|' .env
sed -i 's|^ADMIN_PASSWORD=.*|ADMIN_PASSWORD={ADMIN_PASSWORD}|' .env
echo 'configured'
"
## First-Run Setup + MCP API Key
Trinity is running. Complete the first-run setup, then create an API key for the ops agent.
1. Open: http://{SSH_HOST}:{FRONTEND_PORT}
(If unreachable, check your firewall / security group — port {FRONTEND_PORT} must be open.
On a private network? Run ./scripts/tunnel.sh first and use http://localhost:12080)
2. The first visit shows the first-run setup screen (the old setup token is removed, trinity#49):
enter an ADMIN EMAIL (required — it becomes your sign-in identity) and set the admin
password to {ADMIN_PASSWORD}. What you set here is authoritative — it overwrites the
.env-seeded value. Login attempts before setup completes return 403 setup_required.
⚠️ Do this immediately: the pre-setup window is unauthenticated. On an internet-reachable
host, complete setup via the tunnel (./scripts/tunnel.sh) BEFORE opening the firewall.
3. Log in with that admin email (or username admin) + password
4. Go to: Settings → Platform API Keys
5. Click "Create New Key" — copy the value
6. While you're in Settings, add your GitHub token (Settings → GitHub token):
a fine-grained PAT with Contents: Read on the repos your agents live in.
Agents are deployed by cloning their GitHub repo, so this is what makes the
normal deploy path work — required for private repos, recommended for public
ones (it lifts GitHub's anonymous rate limits).
Use AskUserQuestion (tool requires ≥2 options):
Question: "Paste your MCP API key (from Settings → Platform API Keys)"
Options:
Paste key now → collect from user input; store as MCP_API_KEY
I'll configure it later → set MCP_API_KEY="" and note that .env must be updated before using the ops agent
Set ports: BACKEND_PORT=8000, FRONTEND_PORT={FRONTEND_PORT}, MCP_PORT={MCP_PORT}, SCHEDULER_PORT=8001
for p in 80 8000 8001 8080; do
lsof -i ":$p" >/dev/null 2>&1 && echo"IN_USE $p" || echo"FREE $p"done
For each IN_USE port, use AskUserQuestion (≥2 options) to ask for an alternate — same table as PATH B. Set defaults FRONTEND_PORT=80, MCP_PORT=8080, BACKEND_PORT=8000, SCHEDULER_PORT=8001.
Deploy:
git clone https://github.com/abilityai/trinity ~/trinity
cd ~/trinity && cp .env.example .env
Patch the MCP server Dockerfile healthcheck (upstream bug — /mcp returns 400; /health returns 200):
Open http://localhost:{FRONTEND_PORT}/ — the first visit shows the first-run setup screen: enter an admin email + the admin password (same rules and same authority as PATH B; the setup token is gone). Then Settings → Platform API Keys → create and copy the MCP key. Add your GitHub token too (Settings → GitHub token — fine-grained PAT, Contents: Read): agents deploy by cloning their GitHub repo, so private-repo agents need it.
Set SSH_HOST="" (empty — local, no SSH).
STEP C2b (Existing): Collect Credentials
curl -sf http://localhost:8000/health
Ask for ADMIN_PASSWORD and MCP_API_KEY. Set SSH_HOST="".
STEP 2: Agent Configuration
Use AskUserQuestion to collect:
Instance Name:
Question: "What should this Trinity instance be called? (e.g., production, my-company, dev)"
Used as the agent directory name: {INSTANCE_NAME}-ops
Store as INSTANCE_NAME
Destination:
Question: "Where should the ops agent be created?"
Show options:
~/{INSTANCE_NAME}-ops (recommended)
Custom path
Expand ~ to $HOME
Store as DEST
If destination already exists, warn and offer to pick a different path
Anthropic API Key (optional but recommended):
Question: "Anthropic API key for agent containers? (agents won't run without this — get one at console.anthropic.com)"
Options:
Paste key now → collect as ANTHROPIC_API_KEY
I'll add it to .env later → set ANTHROPIC_API_KEY=""
Store as ANTHROPIC_API_KEY
Contact email (optional):
Question: "Contact email for this instance? (press Enter to skip)"
Store as CONTACT_EMAIL (may be blank)
Compute today's date:
date +%Y-%m-%d
Store as TODAY.
STEP 3: Clone and Configure Ops Agent
Clone the trinity-ops-public repository into {DEST}:
If git is not installed locally, display: Install git: https://git-scm.com/downloads and stop.
If the destination already exists, warn and offer to pick a different path.
Copy .env.example to .env:
cp {DEST}/.env.example {DEST}/.env
Configure credentials — use perl -i -pe for cross-platform compatibility:
For local Docker: set host.address: localhost and omit user and key.
STEP 4: Finalize
Make scripts executable:
chmod +x {DEST}/scripts/*.sh
Run a quick status check to verify the connection works from the new agent:
source {DEST}/.env && {DEST}/scripts/status.sh
STEP 5: Handoff
Display:
## Trinity Ops Agent Ready
Instance: {INSTANCE_NAME}
Agent: {DEST}
### Open the agent
cd {DEST}
claude
### Skills available
/status — health check all services
/restart — restart Trinity services
/update — pull latest Trinity + rebuild
/logs — view service logs
/agents — list and manage agent containers
/cleanup — prune unused Docker images and resources
/diagnose — run a deep diagnostic sweep
/rebuild-agent — rebuild a specific agent container
/rollback — roll back Trinity to a previous version
/telemetry — view aggregated logs and metrics
/provision — provisioning guides for cloud providers
### Access Trinity
Web UI: http://{SSH_HOST}:{FRONTEND_PORT}
Backend: http://{SSH_HOST}:{BACKEND_PORT}
MCP Server: http://{SSH_HOST}:{MCP_PORT}
Credentials are in {DEST}/.env — keep this file secret.
Error Handling
Situation
Action
SSH connection fails
Show error, ask to verify host/user/key
Docker not found on server
Show install command for their OS
Port 80 taken
Ask for alternate port (suggest 8090)
Deployment times out
Show sudo docker logs trinity-backend --tail 30
Health check fails after deploy
Show backend logs, offer to retry
Destination already exists
Warn, offer to pick a different path
git clone fails
Check network connectivity and git installation
Trinity already running at wrong port
Ask for actual backend port before collecting credentials
