What is Trinity
Trinity is autonomous agent orchestration and infrastructure — deploy, orchestrate, and govern fleets of autonomous AI agents with real-time observability, fleet-wide scheduling, agent-to-agent delegation, and complete audit trails. On your own infrastructure.
Concepts
Autonomous Agent
An AI system that runs autonomously in its own isolated Docker container. Agents decompose goals into tasks, persist memory across sessions, delegate to specialized sub-agents, and execute on cron schedules. Each agent supports multi-runtime (Claude Code or Gemini CLI) with model selection per task.
Agent Container
An isolated Docker container with standardized interfaces for credentials, tools, and MCP server integrations.
Template
A GitHub repository or local directory that defines an agent's initial configuration, including CLAUDE.md, template.yaml, .mcp.json.template, and credential declarations.
MCP (Model Context Protocol)
The protocol agents use to communicate with each other and with external tools. Trinity's MCP server exposes 62 tools for fleet management, credential injection, scheduling, and more.
System Agent
An auto-deployed platform orchestrator ( trinity-system) that manages fleet operations such as health checks, scaling, and coordination.
Autonomy Mode
A master toggle that enables or disables all scheduled operations for a given agent.
Execution
A single run of a task on an agent. Executions can be triggered manually, by a cron schedule, by another agent, or via the API.
Public Link
A shareable URL that allows unauthenticated users to chat with an agent directly.
Process Engine
A BPMN-inspired workflow orchestration system for multi-agent processes with approval gates and conditional branching.
Four Pillars of Deep Agency
Hierarchical Delegation
Orchestrator-Worker pattern with context quarantine via MCP. Parent agents delegate tasks to child agents without leaking context between them.
Persistent Memory
SQLite chat persistence, virtual filesystems, and a file browser give agents continuity across sessions.
Extreme Context Engineering
Templates ship a CLAUDE.md that defines the agent's reasoning processes, tools, and behavioral constraints.
Autonomous Operations
Scheduling, monitoring, and self-healing allow agents to run without human intervention.
How It Works
Trinity runs as a set of Docker containers on your local machine or server. After starting the platform, you interact with it through the web UI or the API.
Start the platform
Run ./scripts/deploy/start.sh to bring up all services. The web UI is available at http://localhost and the API at http://localhost:8000/docs.
Create an agent
From the dashboard, click “Create Agent” and select a template (GitHub repo URL or local path). Trinity pulls the template, builds a container, and deploys the agent.
Configure credentials
Add API keys and secrets through the agent's credential panel. Credentials are encrypted in Redis and injected into the container at runtime with hot-reload support.
Chat with the agent
Open the agent detail page and use the built-in chat interface. The agent processes your request using its configured tools, MCP connections, and reasoning context.
Schedule autonomous work
Set up cron-based schedules so the agent executes tasks on its own. Enable Autonomy Mode to activate all schedules.
Monitor the fleet
Use the dashboard to view agent health, execution history, and the network graph showing inter-agent communication.
Architecture
| Component | Technology | Port | Purpose |
|---|---|---|---|
| Frontend | Vue.js 3 + Tailwind CSS | 80 | Web dashboard and chat UI |
| Backend | FastAPI (Python) | 8000 | REST API, 300+ endpoints across 45+ routers |
| MCP Server | FastMCP, Streamable HTTP | 8080 | 62 tools for agent-to-agent and agent-to-platform communication |
| Vector | Log aggregation | 8686 | Structured logging from all containers |
| Redis | Secrets and cache | 6379 | Encrypted credential storage |
| Docker Engine | Container orchestration | — | Agent lifecycle management |
| Agent Network | Isolated bridge | 172.28.0.0/16 | Container-to-container communication |
Key API Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/token | Authenticate and receive a JWT token |
| GET | /api/agents | List all agents |
| POST | /api/agents | Create a new agent from a template |
| GET | /api/agents/{name} | Get agent details |
| DELETE | /api/agents/{name} | Delete an agent |
| POST | /api/agents/{name}/start | Start an agent container |
| POST | /api/agents/{name}/stop | Stop an agent container |
| POST | /api/agents/{name}/chat | Send a message to an agent |
| GET | /api/agents/{name}/schedules | List agent schedules |
| POST | /api/agents/{name}/schedules | Create a scheduled execution |
Authentication uses Bearer tokens. Obtain a token from /api/token using form-encoded credentials, then pass it in the Authorization: Bearer <token> header on all subsequent requests.
# Authenticate
TOKEN=$(curl -s -X POST http://localhost:8000/api/token \
-d 'username=admin&password=your-password' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
# List agents
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/agentsPlatform Capabilities
Create agents from GitHub templates or local directories
Multi-runtime support: Claude Code, Gemini CLI
Credential management with encryption and hot-reload
Agent-to-agent collaboration via MCP tool calls
Cron-based scheduling with execution history
Real-time monitoring dashboard with network graph
Public chat links for external users
Slack integration for agent notifications and commands
Process engine for BPMN-style multi-agent workflows
Voice chat via Gemini Live API
x402 payment protocol for agent monetization