Getting Started/Deploying Trinity/Local Development

Local Development

Run Trinity on your own machine for development and experimentation. All services run in Docker; nothing is installed on the host except Docker and Git.

Prerequisites

•Docker Desktop (includes Docker Compose) — version 24 or later recommended
•Git
•openssl on your PATH (comes with macOS and most Linux distributions)
•8 GB RAM available to Docker

1. Clone the Repository

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

2. Configure `.env`

cp .env.example .env

Required for a working dev boot

Variable	Where used	How to set
SECRET_KEY	Backend — JWT signing	`openssl rand -hex 32`
ADMIN_PASSWORD	Backend — admin login	Choose a strong password
REDIS_PASSWORD	Redis `default` ACL user	Auto-generated by `start.sh` on a fresh install
REDIS_BACKEND_PASSWORD	Redis `backend` and `scheduler` ACL users	Auto-generated by `start.sh` on a fresh install
CREDENTIAL_ENCRYPTION_KEY	Backend — encrypts OAuth tokens	Auto-generated by `start.sh` if blank; do not change once set

Redis passwords and start.sh auto-generation: On a fresh install (no redis-data volume), start.sh detects missing REDIS_PASSWORD / REDIS_BACKEND_PASSWORD values and fills them in automatically. If the volume already exists and the passwords are missing, the script will exit with an error and point you at the migration guide.

Optional but recommended

Variable	Purpose
ANTHROPIC_API_KEY	Lets agents use Claude. Can be left blank and configured in Settings after login.
EMAIL_PROVIDER	How verification codes are sent. Set to `console` for dev (codes print to backend logs).
RESEND_API_KEY	Required if `EMAIL_PROVIDER=resend`.
GITHUB_PAT	Needed to clone private template repos.
INTERNAL_API_SECRET	Shared secret for scheduler-to-backend calls. Falls back to `SECRET_KEY` if unset.
FRONTEND_PORT	Override port `80` if another process already holds it (e.g., `FRONTEND_PORT=8090`).

3. Build the Base Agent Image

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

This builds trinity-agent-base:latest — the Docker image every agent container inherits. It includes Python 3.11, Node.js 20, Go 1.21, and Claude Code. The platform can start without this, but you cannot create any agents until the image exists. First build takes 5–10 minutes.

start.sh detects a missing base image and calls this script automatically. You can skip this step if you prefer.

4. Start Services

./scripts/deploy/start.sh

Once complete, all six platform services are running:

Service	Container	Port
Backend (FastAPI)	trinity-backend	8000
Frontend (nginx)	trinity-frontend	80 (or $FRONTEND_PORT)
MCP Server	trinity-mcp-server	8080
Scheduler	trinity-scheduler	8001 (health only)
Redis	trinity-redis	127.0.0.1:6379 (loopback only)
Vector (logs)	trinity-vector	8686

5. Open the Web UI

Navigate to http://localhost and log in with username admin and the ADMIN_PASSWORD you set in .env.

URL	Purpose
http://localhost	Web UI
http://localhost:8000/docs	Backend API (Swagger)
http://localhost:8080/mcp	MCP Server endpoint
http://localhost:8686/health	Vector log aggregator health

Hot Reload

The dev compose mounts source trees into the containers:

•Backend: ./src/backend is bind-mounted inside trinity-backend. Uvicorn runs with --reload, so any change to a .py file restarts the backend worker automatically.
•Frontend: ./src/frontend is bind-mounted into trinity-frontend. Vite watches for .vue and .js changes and hot-reloads automatically.

If you add or remove a Python dependency or change package.json, rebuild the affected image:

docker compose build backend   # after requirements.txt change
docker compose build frontend  # after package.json change
docker compose up -d backend   # restart after rebuild

Viewing Logs

# All services
docker compose logs -f

# One service
docker compose logs -f backend
docker compose logs -f frontend

# Structured platform logs via Vector
docker exec trinity-vector sh -c "tail -50 /data/logs/platform.json" | jq .

# Structured agent logs via Vector
docker exec trinity-vector sh -c "tail -50 /data/logs/agents.json" | jq .

Stopping Services

./scripts/deploy/stop.sh

Local vs. server behavior

stop.sh runs docker compose down, which stops and removes containers and the agent network. This is acceptable for local development where agent containers are recreated frequently. On a server running persistent agents, use docker compose stop instead.

Data Persistence

All platform state is stored in Docker named volumes. These survive docker compose down and docker compose up cycles.

Volume	Contents
trinity_trinity-data	`trinity.db` — agents, schedules, chat history, credentials metadata
trinity_redis-data	Redis AOF journal
trinity_agent-configs	Agent configuration files
trinity_trinity-logs	Vector log aggregation output

Troubleshooting

ModuleNotFoundError on backend startup

A Python dependency was added since your last build. Rebuild:

docker compose build backend && docker compose up -d backend

Port 80 already in use

Add FRONTEND_PORT=8090 to .env, then restart.

Agents can't be created

The base image is missing. Run:

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

Redis password errors on startup

Passwords changed after the redis-data volume was created. See docs/migrations/REDIS_AUTH.md for the upgrade path.

Deploying Trinity Single Server