Skip to content

README.md

Latest commit

 

History

History
685 lines (527 loc) · 30.5 KB

README.md

File metadata and controls

685 lines (527 loc) · 30.5 KB
Trinity

Trinity

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.

Stars License Python Vue Docker PyPI

How to Use • Quick Start • Features • Demo Video • Docs • Community


Watch the Demo

Trinity Agent Fleet — Graph View

Why Trinity?

The problem: Everyone wants autonomous AI agents. But your options are terrible — SaaS platforms where data leaves your security perimeter, custom builds that take 6-12 months, or frameworks that don't handle governance and audit trails.

The solution: Trinity is autonomous agent orchestration infrastructure. Each agent runs in its own isolated Docker container. You get real-time observability, fleet-wide health monitoring, cron-based scheduling, agent-to-agent delegation, and cost tracking — all on your own hardware.

Option Problem Trinity
SaaS Platforms Data leaves your perimeter, vendor lock-in Your infrastructure, data never leaves
Build Custom 6-12 months, $500K+ engineering Deploy in minutes
Frameworks No observability, no fleet management Real-time monitoring, scheduling, audit trails

Getting Started — Deploy an Agent in 3 Minutes

You need: a Trinity instance running somewhere (localhost or remote) and a local agent directory with CLAUDE.md and template.yaml.

# 1. Install the CLI
pip install trinity-cli                     # or: brew install abilityai/tap/trinity-cli

# Upgrade to latest version
pip install --upgrade trinity-cli           # or: brew upgrade abilityai/tap/trinity-cli

# 2. Connect to your Trinity instance
trinity init
#    → Enter instance URL (e.g. trinity.example.com — bare domains work)
#    → Enter your email
#    → Enter the 6-digit verification code from your inbox
#    → Done — JWT + MCP key auto-provisioned

# Or login as admin (password-based)
trinity login --instance trinity.example.com --admin

# 3. Deploy your agent
cd my-agent/
trinity deploy .
#    → Packages directory, uploads, creates + starts the agent container
#    → Writes .trinity-remote.yaml for future redeploys

# 4. Use it
trinity agents list                         # see your agents
trinity chat my-agent "Hello, what can you do?"
trinity logs my-agent                       # container logs
trinity health fleet                        # fleet overview

# 5. Redeploy after changes
trinity deploy .                            # updates the same agent

Multiple Instances

The CLI supports named profiles for managing multiple Trinity instances:

# Each instance gets its own profile (derived from hostname by default)
trinity login --instance trinity.example.com --admin
trinity login --instance staging.example.com --admin

# Switch between instances with --profile
trinity --profile trinity.example.com agents list
trinity --profile staging.example.com agents list

# Check current profile
trinity status

See the CLI documentation for the full command reference.

Other Ways to Use Trinity

Deploy from Claude Code (Plugin)

Already have a Claude Code agent? Deploy it with the Trinity plugin:

/plugin marketplace add abilityai/abilities
/plugin install trinity@abilityai
/trinity:onboard

After onboarding you get management skills: /trinity:sync (push/pull code), /trinity:remote (execute tasks), /trinity:schedules (cron automation).

Create via Web UI

Open the Trinity web UI → Create Agent → pick a template (blank, built-in, or github:org/repo@branch) → configure credentials → start chatting.

Deploy a Multi-Agent System

# system-manifest.yaml
name: content-pipeline
agents:
  orchestrator:
    template: github:abilityai/agent-corbin
    schedules:
      - cron: "0 9 * * *"
        message: "Run daily content review"
  writer:
    template: github:abilityai/agent-ruby
permissions:
  preset: full-mesh

Deploy via MCP: mcp__trinity__deploy_system(manifest="...")

See the Multi-Agent System Guide for patterns.

For AI Agents

If you're an AI agent given this repository:

  1. This repo is a Claude Code plugin — Run /plugin marketplace add abilityai/abilities to install Trinity management skills
  2. To deploy yourself to Trinity — Run /plugin install trinity@abilityai then /trinity:onboard
  3. To interact with a Trinity instance — Use the MCP tools (list_agents, chat_with_agent, etc.) after configuring the MCP server connection
  4. To contribute to Trinity itself — Read CLAUDE.md for development guidelines

Features

Fleet Observability

  • Graph View — Visual topology of your agent fleet with live status, success rates, cost tracking, and resource usage per agent
  • Timeline View — Gantt-style execution timeline with trigger-based color coding (manual, scheduled, MCP, agent-triggered, public, paid)
  • Host Telemetry — Real-time CPU, memory, and disk monitoring in the dashboard header
  • Fleet Health Monitoring — Multi-layer health checks (Docker, network, business) with alerting and WebSocket updates
  • OpenTelemetry Metrics & Tracing — Cost, token usage, and productivity tracking exportable to Grafana/Datadog; distributed traces across multi-agent calls

Trinity Timeline — Fleet Activity

Agent Runtime

  • Isolated Docker Containers — Each agent runs in its own container with dedicated resources
  • Multi-Runtime Support — Choose between Claude Code (Anthropic) or Gemini CLI (Google) per agent
  • Model Selection — Choose which Claude model (Opus, Sonnet, Haiku) per task or schedule
  • Agent Dashboard — Custom dashboards defined via dashboard.yaml with 11 widget types, historical tracking, and sparkline visualization
  • Playbooks — Browse and invoke agent skills (.claude/skills/) directly from the UI
  • Dynamic Thinking Status — Real-time status labels reflecting agent activity (Reading file, Searching code, etc.)
  • Persistent Memory — File-based and database-backed memory across sessions
  • Full Capabilities Mode — Optional elevated permissions for agents that need apt-get, sudo, etc.
  • Read-Only Mode — Protect source code from modification while allowing output to designated directories
  • Runaway Prevention — max_turns parameter limits agent execution depth
  • Guardrails — Deterministic safety enforcement with configurable per-agent overrides (GUARD-001)
  • Persistent Async Backlog — SQLite-backed FIFO queue for tasks that exceed parallel capacity, survives restarts
  • Execution Retry & Timeouts — Automatic retry for failed scheduled executions; configurable per-agent execution timeouts

Trinity Agent Dashboard

Orchestration

  • Agent-to-Agent Communication — Hierarchical delegation with fine-grained permission controls
  • Parallel Task Execution — Stateless parallel tasks for orchestrator-worker patterns
  • Shared Folders — File-based state sharing between agents via Docker volumes
  • System Manifest Deployment — Deploy multi-agent systems from a single YAML configuration
  • Scheduling — Cron-based automation with dedicated scheduler service and Redis distributed locks
  • MCP Integration — 72 tools for external agent orchestration via Model Context Protocol
  • Trinity Connect — WebSocket event streaming for local Claude Code integration
  • Channel Adapters — Pluggable external messaging: Slack (Socket Mode + webhooks, per-channel agent binding) and Telegram (DMs, groups, voice transcription, file uploads)
  • Unified Access Control — Verified-email allow-list governs access across web, Slack, and Telegram with per-agent require_email / open_access policies (#311)
  • Proactive Messaging — Agents initiate user conversations via send_message / send_group_message MCP tools (#321, #349)

Operations

  • Template-Based Deployment — Create agents from pre-configured templates or GitHub repos
  • Credential Management — Direct file injection with encrypted git storage (.credentials.enc)
  • Per-Agent GitHub PAT — Encrypted per-agent tokens override the global PAT for private template access (#347)
  • Subscription Management — Centralized Claude Max/Pro subscription tokens shared across agents
  • Platform Audit Log — Append-only cross-cutting audit trail for lifecycle, auth, and MCP events (SEC-001, admin-only API)
  • Role Hierarchy — 4-tier RBAC (user < operator < creator < admin) with whitelist-driven role on first login
  • Agent Tags & System Views — Organize agents with tags and saved filter views for fleet management
  • Live Execution Streaming — Real-time streaming of execution logs to the web UI
  • Execution Termination — Stop running executions gracefully via SIGINT/SIGKILL
  • Continue as Chat — Resume failed or completed executions as interactive chat with full context
  • Agent Notifications — Agents send structured notifications to platform with Events page UI
  • File Manager — Browse, preview, and download agent workspace files via web UI
  • Ephemeral SSH Access — Generate time-limited SSH credentials for direct agent terminal access
  • Public Agent Links — Shareable links for unauthenticated agent access with session persistence and Slack integration
  • Paid Agent Access (x402) — Per-agent monetization via Nevermined x402 payment protocol
  • Mobile Admin PWA — Standalone mobile admin at /m, installable as a home screen app
  • First-Time Setup Wizard — Guided setup for admin password and API key configuration

Comparison

Feature Trinity Custom Build LangChain/CrewAI SaaS Platforms
Time to production Minutes 6-12 months Weeks Instant
Data sovereignty ✅ ✅ ✅ ❌
Docker isolation per agent ✅ DIY ❌ ❌
Fleet observability ✅ DIY ❌ Basic
Agent-to-agent delegation ✅ DIY Limited ❌
Cron scheduling & autonomy ✅ DIY ❌ Limited
Cost tracking per agent ✅ DIY ❌ Basic
Complete audit trail ✅ DIY ❌ Basic
Multi-runtime (Claude/Gemini) ✅ DIY ❌ ❌
State persistence (GitHub sync) ✅ DIY Partial Session-only
Open source ✅ N/A ✅ ❌

Quick Start

Prerequisites

  • Docker and Docker Compose v2+
  • Anthropic API key (for Claude-powered agents) OR Google API key (for Gemini-powered agents)

One-Line Install

curl -fsSL https://raw.githubusercontent.com/abilityai/trinity/main/install.sh | bash

This will clone the repository, configure environment, build the base image, and start all services.

Manual Installation

# 1. Clone the repository
git clone https://github.com/abilityai/trinity.git
cd trinity

# 2. Configure environment
cp .env.example .env
# Edit .env - at minimum set:
#   SECRET_KEY (generate with: openssl rand -hex 32)

# 3. Build the base agent image
./scripts/deploy/build-base-image.sh

# 4. Start all services
./scripts/deploy/start.sh

First-Time Setup

On first launch, Trinity will guide you through initial setup:

  1. Open http://localhost — you'll be redirected to the setup wizard
  2. Set your admin password (minimum 8 characters)
  3. Log in with username admin and your new password
  4. Go to Settings → API Keys to configure your Anthropic API key

Access

Create Your First Agent

  1. Open http://localhost
  2. Click Create Agent
  3. Enter a name and select a template (or leave blank for a basic agent)
  4. Click Create

Your agent will start automatically. Use the Chat tab to interact with it.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                       Trinity Platform                           │
├─────────────────────────────────────────────────────────────────┤
│  Frontend (Vue.js)  │  Backend (FastAPI)  │  MCP Server         │
│      Port 80        │     Port 8000       │    Port 8080        │
├─────────────────────────────────────────────────────────────────┤
│  Scheduler Service  │  Redis (secrets +   │  SQLite (data)      │
│    Port 8001        │   distributed locks)│   /data volume      │
├─────────────────────────────────────────────────────────────────┤
│  Vector (logs)      │                                           │
│    Port 8686        │                                           │
├─────────────────────────────────────────────────────────────────┤
│                    Agent Containers                              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌────────────────┐    │
│  │ Agent 1 │  │ Agent 2 │  │ Agent N │  │ trinity-system │    │
│  └─────────┘  └─────────┘  └─────────┘  └────────────────┘    │
├─────────────────────────────────────────────────────────────────┤
│  (Optional) OTel Collector - Port 4317/8889 for metrics export  │
└─────────────────────────────────────────────────────────────────┘

Project Structure

trinity/
├── src/
│   ├── backend/          # FastAPI backend API
│   ├── frontend/         # Vue.js 3 + Tailwind CSS web UI
│   ├── mcp-server/       # Trinity MCP server (72 tools)
│   ├── cli/              # Trinity CLI (pip install trinity-cli)
│   └── scheduler/        # Dedicated scheduler service (Redis locks)
├── docker/
│   ├── base-image/       # Universal agent base image
│   ├── backend/          # Backend Dockerfile
│   ├── frontend/         # Frontend Dockerfile
│   └── scheduler/        # Scheduler Dockerfile
├── config/
│   ├── agent-templates/  # Pre-configured agent templates
│   ├── vector.yaml       # Vector log aggregation config
│   ├── otel-collector.yaml # OpenTelemetry collector config
│   └── trinity-meta-prompt/ # Platform injection templates
├── scripts/
│   └── deploy/           # Deployment and management scripts
└── docs/                 # Documentation

Agent Templates

Trinity deploys agents from templates. Templates define agent behavior, resources, and credential requirements.

Template Structure

my-template/
├── template.yaml              # Metadata, resources, credentials
├── CLAUDE.md                  # Agent instructions (owned by agent)
├── .claude/                   # Claude Code configuration
│   ├── agents/               # Sub-agents (optional)
│   ├── commands/             # Slash commands (optional)
│   └── skills/               # Custom skills (optional)
├── .mcp.json.template        # MCP config with ${VAR} placeholders
└── .env.example              # Documents required env vars

# Generated at runtime by the platform (not in templates):
# CLAUDE.local.md              # Platform instructions (gitignored, managed by Trinity)
# .trinity/prompt.md           # Operator communication protocol

Design Guides

Guide Use Case
Trinity Compatible Agent Guide Single agents — Template structure, CLAUDE.md, credentials, platform injection
Multi-Agent System Guide Multi-agent systems — Architecture patterns, shared folders, coordination, deployment

Public Agent Templates

Trinity includes three reference agent implementations that demonstrate real-world agent patterns. These repositories are public and available for use as templates for your own agents:

Agent Repository Purpose
Cornelius github.com/abilityai/agent-cornelius Knowledge Base Manager — Obsidian vault management, insight synthesis, research coordination
Corbin github.com/abilityai/agent-corbin Business Assistant — Google Workspace integration, task coordination, team management
Ruby github.com/abilityai/agent-ruby Content Creator — Multi-platform publishing, social media distribution, content strategy

These agents demonstrate:

  • Production-ready template structure with template.yaml, CLAUDE.md, and .claude/ configuration
  • Agent-to-agent collaboration patterns via Trinity MCP
  • Custom metrics definitions for specialized tracking
  • Credential management for external API integrations
  • Real-world slash commands and workflow automation

Usage: Create agents from these templates via the Trinity UI:

# Via UI: Create Agent → Select "github:abilityai/agent-cornelius"
# Via MCP: trinity_create_agent(name="my-agent", template="github:abilityai/agent-cornelius")

Note: You'll need to configure a GITHUB_PAT environment variable in .env to use GitHub templates.

Abilities — The Agent Development Toolkit

abilityai/abilities is the canonical development workflow for building and managing autonomous agents with Claude Code.

It provides 5 focused plugins covering the full agent lifecycle — from scaffolding and onboarding to deployment, scheduling, and ongoing operations:

Plugin What it does
create-agent 12 wizards for agent scaffolding (prospector, chief-of-staff, webmaster, recon, receptionist, ghostwriter, kb-agent, website, custom, clone, adjust)
agent-dev Add skills, memory systems, GitHub backlog workflow, autonomous work loops
trinity Deploy to Trinity platform: connect, onboard, sync
dev-methodology 14 skills for implementation, testing, security, and PR validation
utilities Ops: incident investigation, safe deployment, Docker ops, batch processing 
# Install the abilities marketplace (one-time)
/plugin marketplace add abilityai/abilities

# Example: onboard an agent to Trinity
/plugin install trinity@abilityai
/trinity:onboard

# Example: scaffold a new agent
/plugin install create-agent@abilityai
/create-agent:create

See the abilities repository for full plugin documentation and installation instructions.

MCP Integration

Trinity includes an MCP server for external orchestration of agents:

{
  "mcpServers": {
    "trinity": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Available Tools

Agent Management

Tool Description
list_agents List all agents with status
get_agent Get detailed agent information
get_agent_info Get agent template metadata (capabilities, commands, etc.)
create_agent Create a new agent from template
deploy_local_agent Package and deploy a local agent directory
start_agent / stop_agent Start or stop an agent container
rename_agent Rename an agent
delete_agent Delete an agent
initialize_github_sync / set_agent_github_pat GitHub sync and per-agent PAT management

Communication

Tool Description
chat_with_agent Send a message and get response (supports parallel and async modes)
get_chat_history Retrieve conversation history
get_agent_logs View container logs
fan_out Dispatch N parallel tasks to an agent and collect results
send_message Proactive user message by verified email (agent-initiated)
send_group_message / list_channel_groups Proactive group messaging across Slack/Telegram

Note: Claude Code enforces a 60-second timeout on MCP HTTP tool calls. For longer tasks, use async=true with parallel=true to get an execution_id immediately and poll for results. See Known Issues for details.

System Management

Tool Description
deploy_system Deploy multi-agent system from YAML manifest
list_systems List deployed systems with agent counts
restart_system Restart all agents in a system
get_system_manifest Export system configuration as YAML

Configuration

Tool Description
list_templates List available templates
inject_credentials Inject credential files directly to agent
get_credential_status Check credential files
get_agent_ssh_access Generate ephemeral SSH credentials for direct terminal access

Additional Tool Categories

  • Scheduling (8 tools) — Create, list, update, delete, enable/disable schedules, trigger manually
  • Executions (3 tools) — List recent executions, poll async results, get agent activity summaries
  • Tags (5 tools) — List, get, set, add, remove agent tags for fleet organization
  • Subscriptions (6 tools) — Register and assign Claude Max/Pro subscriptions to agents
  • Skills (7 tools) — List, create, update, delete, assign skills to agents
  • Monitoring (3 tools) — Get fleet health, agent health details, trigger health checks
  • Payments (4 tools) — Configure Nevermined x402 payments, toggle, view payment history
  • Notifications (1 tool) — Send structured notifications from agents to platform
  • Events (4 tools) — Emit events, subscribe to agent events, list/delete subscriptions

Multi-Agent Systems

Deploy coordinated multi-agent systems from a single YAML manifest:

name: content-production
description: Autonomous content pipeline

agents:
  orchestrator:
    template: github:abilityai/agent-corbin
    resources: {cpu: "2", memory: "4g"}
    folders: {expose: true, consume: true}
    schedules:
      - name: daily-review
        cron: "0 9 * * *"
        message: "Review today's content pipeline"

  writer:
    template: github:abilityai/agent-ruby
    folders: {expose: true, consume: true}

permissions:
  preset: full-mesh  # All agents can communicate

Deploy via MCP or API:

# Via MCP tool
mcp__trinity__deploy_system(manifest="...")

# Via REST API
curl -X POST http://localhost:8000/api/systems/deploy \
  -H "Content-Type: application/json" \
  -d '{"manifest": "...", "dry_run": false}'

See the Multi-Agent System Guide for architecture patterns and best practices.

Trinity Connect

Trinity Connect enables real-time coordination between local Claude Code instances and Trinity-hosted agents via WebSocket event streaming.

# Install listener dependencies
brew install websocat jq

# Set your MCP API key (from Settings → API Keys)
export TRINITY_API_KEY="trinity_mcp_xxx"

# Listen for events from a specific agent
./scripts/trinity-listen.sh my-agent completed

The listener blocks until a matching event arrives, then prints the event and exits — perfect for event-driven automation loops:

while true; do
    ./scripts/trinity-listen.sh my-agent completed
    # React to the completed event...
done

Events include: agent_started, agent_stopped, agent_activity (chat/task completions), and schedule_execution_completed.

Configuration

Environment Variables

Variable Required Description
SECRET_KEY Yes JWT signing key (generate with openssl rand -hex 32)
ADMIN_PASSWORD Yes Admin password for admin login
ANTHROPIC_API_KEY No For Claude-powered agents (can also be set via Settings UI)
GITHUB_PAT No GitHub PAT for cloning private template repos
OTEL_ENABLED No Enable OpenTelemetry metrics export (default: false)
EMAIL_PROVIDER No Email provider: console (dev), smtp, sendgrid, resend
EXTRA_CORS_ORIGINS No Additional CORS origins

See .env.example for the complete list.

Authentication

Trinity supports two login methods:

  1. Email Login (primary): Users enter email → receive 6-digit code → login
  2. Admin Login: Password-based login for admin user
# Admin password (required)
ADMIN_PASSWORD=your-secure-password

# Email provider for verification codes
EMAIL_PROVIDER=console  # Use 'resend' or 'smtp' for production

Documentation

Development

# Start in development mode (hot reload)
./scripts/deploy/start.sh

# View logs
docker compose logs -f backend
docker compose logs -f frontend

# Rebuild after changes
docker compose build backend
docker compose up -d backend

Codebase Hygiene

Weekly maintenance skills to keep the codebase clean and consistent:

Skill What it checks
/validate-architecture 15 architectural invariants (layer separation, auth patterns, etc.)
/validate-schema Schema drift between db/schema.py, db/migrations.py, and architecture.md
/validate-config Env var consistency across docker-compose.yml, .env.example, and code
/refactor-audit Dead code, complexity hotspots, large files/functions
/cso --supply-chain Dependency freshness and known CVEs
/tidy Orphan files, misplaced configs, test artifacts

Releasing the CLI

The CLI auto-publishes to PyPI and Homebrew on every push to main that changes src/cli/. The patch version auto-increments from the latest cli-v* tag.

For explicit major/minor bumps, tag manually:

git tag cli-v1.0.0
git push origin cli-v1.0.0

License

This project is licensed under the Polyform Noncommercial License 1.0.0.

Free for:

  • Personal use
  • Research and education
  • Non-profit organizations
  • Hobby projects

Commercial use requires a separate license. Contact hello@ability.ai for commercial licensing.

Contributing

See CONTRIBUTING.md for guidelines.

Community & Support

Built by Ability.ai — Sovereign AI infrastructure for the autonomous enterprise