AI Skills

Nevermined Hackathon Participants: See the Hackathon Getting Started Guide for instance access, agent templates, and instructions.

<div align="center"> <img src="docs/assets/trinity-logo.svg" alt="Trinity" width="120"/> <h1>Trinity</h1> <p><strong>Sovereign infrastructure for autonomous AI agents</strong></p> <p>Deploy, orchestrate, and govern AI agent teams with visual interface, enterprise-grade controls, and complete audit trails.</p> <p> <a href="https://github.com/abilityai/trinity/stargazers"><img src="https://img.shields.io/github/stars/abilityai/trinity?style=social" alt="Stars"></a> <a href="https://github.com/abilityai/trinity/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Polyform%20NC-blue.svg" alt="License"></a> <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python"> <img src="https://img.shields.io/badge/vue-3.x-green.svg" alt="Vue"> <img src="https://img.shields.io/badge/docker-required-blue.svg" alt="Docker"> </p> <p> <a href="#ways-to-use-trinity">How to Use</a> • <a href="#-quick-start">Quick Start</a> • <a href="#features">Features</a> • <a href="https://youtu.be/SWpNphnuPpQ">Demo Video</a> • <a href="#documentation">Docs</a> • <a href="#community--support">Community</a> </p> <br/> <a href="https://youtu.be/SWpNphnuPpQ"> <img src="https://img.shields.io/badge/▶_Watch_Demo-YouTube-red?style=for-the-badge&logo=youtube" alt="Watch the Demo"> </a> <br/><br/> <img src="docs/assets/screenshots/graph-view-collaboration.png" alt="Trinity Agent Collaboration" width="800"/> </div>

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 sovereign infrastructure with enterprise-grade controls. Human approvals where decisions matter. Your infrastructure, your security perimeter.

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 governance, no audit trails	Enterprise controls built-in

Ways to Use Trinity

Trinity supports three primary workflows depending on your starting point:

1. Onboard an Existing Claude Code Agent

You have: A Claude Code agent (local project with CLAUDE.md) You want: Deploy it to the cloud for autonomous operation, scheduling, and team access

# In Claude Code, install the Trinity plugin
/plugin marketplace add abilityai/trinity
/plugin install trinity-onboard@abilityai-trinity

# Run the onboarding wizard
/trinity-onboard:onboard

The plugin analyzes your agent, creates required configuration files, pushes to GitHub, and deploys to Trinity. After onboarding, you get management skills:

Skill	Description
`/trinity-sync`	Sync local ↔ remote via git
`/trinity-remote`	Execute tasks on remote agent
`/trinity-schedules`	Manage cron-based automation

2. Create an Agent in Trinity

You have: A Trinity instance running You want: Create a new agent from scratch or from a template

Open Trinity web UI → Create Agent
Choose a template:
- Blank — Start fresh, define behavior via chat
- Built-in templates — Pre-configured for common use cases
- GitHub template — github:org/repo (or github:org/repo@branch) for custom templates
Configure credentials and start chatting

3. Deploy a Multi-Agent System

You have: A complex workflow requiring multiple specialized agents You want: Orchestrated agent fleet with shared state and coordination

# 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:

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

Deep Agents vs Chatbots

Unlike reactive chatbots ("System 1" AI), Deep Agents operate with deliberative reasoning ("System 2" AI): they decompose goals into task graphs, persist memory across sessions, delegate to specialized sub-agents, and recover from failures autonomously.

The Four Pillars of Deep Agency

Trinity implements four foundational capabilities that transform simple AI assistants into autonomous agents:

Hierarchical Delegation — Orchestrator-Worker pattern with context quarantine
Persistent Memory — Virtual filesystems, vector databases, episodic memory
Extreme Context Engineering — High-Order Prompts defining reasoning processes
Autonomous Operations — Scheduling, monitoring, and self-healing capabilities

Features

Core Platform

Isolated Agent Containers — Each agent runs in its own Docker container with dedicated resources
Template-Based Deployment — Create agents from pre-configured templates or custom configurations
Agent Rename — Rename agents via UI, MCP, or API without deleting and recreating
Real-Time Monitoring — WebSocket-based activity streaming, telemetry, and context tracking
Dashboard Timeline View — Visual timeline showing executions with trigger-based color coding (manual/scheduled/MCP/agent-triggered)
Host Telemetry — Real-time CPU, memory, and disk monitoring in the dashboard header
First-Time Setup Wizard — Guided setup for admin password and API key configuration
Package Persistence — Installed packages survive container recreation via ~/.trinity/setup.sh
Base Image Versioning — Track agent versions and detect when updates are available

Process Engine

YAML-Based Workflows — Define multi-step business processes with declarative YAML syntax
Six Step Types — agent_task, human_approval, gateway (conditional), timer, notification, sub_process
Human-in-the-Loop — Approval gates with inbox, timeout handling, and decision tracking
Process Templates — Pre-built templates for common workflows (content pipelines, onboarding, etc.)
AI Process Assistant — Chat-based assistant that helps create and edit process definitions
Real-Time Monitoring — Live execution progress with step-by-step visibility
Analytics & Cost Tracking — Metrics, trends, and cost threshold alerts per process

Agent Capabilities

Multi-Runtime Support — Choose between Claude Code (Anthropic) or Gemini CLI (Google) per agent
MCP Integration — 59 tools for external agent orchestration via Model Context Protocol
Agent-to-Agent Communication — Hierarchical delegation with fine-grained permission controls
Persistent Memory — File-based and database-backed memory across sessions
Shared Folders — File-based state sharing between agents via Docker volumes
Model Selection — Choose which Claude model (Opus, Sonnet, Haiku) per task or schedule
Parallel Task Execution — Stateless parallel tasks for orchestrator-worker patterns
Agent Dashboard — Custom dashboards defined via dashboard.yaml with 11 widget types, historical tracking, and sparkline visualization
Full Capabilities Mode — Optional elevated permissions for agents that need apt-get, sudo, etc.
Playbooks Tab — Browse and invoke agent skills (.claude/skills/) directly from the UI
Dynamic Thinking Status — Real-time status labels reflecting agent activity in both authenticated and public chat (Reading file, Searching code, etc.)
Read-Only Mode — Protect source code from modification while allowing output to designated directories
Runaway Prevention — max_turns parameter limits agent execution depth

Operations

System Manifest Deployment — Deploy multi-agent systems from YAML configuration
Internal System Agent — Platform orchestrator for fleet health monitoring and operations
Fleet Health Monitoring — Multi-layer health checks (Docker, network, business) with alerting and WebSocket updates
Credential Management — Direct file injection with encrypted git storage (.credentials.enc)
Subscription Management — Centralized Claude Max/Pro subscription tokens (claude setup-token) shared across agents via env var injection
Agent Tags & System Views — Organize agents with tags and saved filter views for fleet management
Scheduling — Cron-based automation with dedicated scheduler service and Redis distributed locks
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
Trinity Connect — WebSocket event streaming for local Claude Code integration with MCP key authentication
OpenTelemetry Metrics — Cost, token usage, and productivity tracking
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 with verify/settle lifecycle
File Manager — Browse, preview, and download agent workspace files via web UI
Ephemeral SSH Access — Generate time-limited SSH credentials (key or password) for direct agent access

Comparison

Feature	Trinity	Custom Build	LangChain/CrewAI	SaaS Platforms
Time to production	Minutes	6-12 months	Weeks	Instant
Sovereignty	✅	✅	✅	❌
Workflow orchestration	✅	DIY	❌	Limited
Human approval gates	✅	DIY	❌	❌
Docker isolation per agent	✅	DIY	❌	❌
Complete audit trail	✅	DIY	❌	Basic
Cost tracking per workflow	✅	DIY	❌	Basic
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:

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

Access

Web UI: http://localhost
API Docs: http://localhost:8000/docs
MCP Server: http://localhost:8080/mcp

Create Your First Agent

Open http://localhost
Click Create Agent
Enter a name and select a template (or leave blank for a basic agent)
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
│   │   └── services/
│   │       └── process_engine/  # Process Engine (DDD architecture)
│   ├── frontend/         # Vue.js 3 + Tailwind CSS web UI
│   ├── mcp-server/       # Trinity MCP server (59 tools)
│   └── 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
│   ├── process-templates/ # Process definition templates
│   ├── process-docs/     # In-app documentation content
│   ├── 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
├── .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

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

The Multi-Agent System Guide covers Trinity's platform capabilities that enable autonomous operation:

Scheduling System — Cron-based autonomous execution
Shared Folders — File-based state sharing between agents
Agent-to-Agent MCP — Real-time delegation and collaboration
Centralized Logging — Vector-based log aggregation from all containers

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.

Trinity Onboard Plugin

See Ways to Use Trinity for the quick start guide.

The Trinity Onboard Plugin enables zero-friction deployment of any Claude Code agent to Trinity. After onboarding, you get management skills for ongoing operations:

# Example post-onboarding workflow
/trinity-sync push                    # Push local changes to remote
/trinity-remote exec "Run my task"    # Execute on remote agent
/trinity-schedules list               # View scheduled tasks

For detailed plugin documentation, see plugins/trinity-onboard/README.md.

MCP Integration

Trinity includes an MCP server for external orchestration of agents:

{
  "mcpServers": {
    "trinity": {
      "type": "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
`start_agent`	Start a stopped agent
`stop_agent`	Stop a running agent
`rename_agent`	Rename an agent
`delete_agent`	Delete an agent

Communication

Tool	Description
`chat_with_agent`	Send a message and get response (supports parallel mode)
`get_chat_history`	Retrieve conversation history
`get_agent_logs`	View container logs

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
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

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.

Process Engine

Trinity includes a BPMN-inspired Process Engine for orchestrating multi-step workflows with AI agents, human approvals, and automated scheduling.

Example Process Definition

name: content-review-pipeline
description: Review and publish content with human approval

triggers:
  - type: schedule
    cron: "0 9 * * 1-5"  # Weekdays at 9 AM

steps:
  - id: draft-content
    name: Draft Content
    type: agent_task
    agent: content-writer
    task: "Draft the weekly newsletter based on recent updates"

  - id: review-gate
    name: Editorial Review
    type: human_approval
    title: "Approve Newsletter Draft"
    description: "Review the drafted newsletter before publishing"
    timeout: 24h
    depends_on: [draft-content]

  - id: publish
    name: Publish Content
    type: agent_task
    agent: publisher
    task: "Publish the approved newsletter"
    depends_on: [review-gate]

Step Types

Type	Description
`agent_task`	Execute a task via an AI agent
`human_approval`	Pause for human decision with timeout
`gateway`	Conditional branching based on expressions
`timer`	Delay execution for a specified duration
`notification`	Send notifications to users or systems
`sub_process`	Call another process as a nested workflow

AI Process Assistant

The Process Editor includes an AI-powered chat assistant that helps you:

Create new processes from natural language descriptions
Edit existing YAML with conversational commands
Get explanations of step types and syntax
Debug validation errors

Access it via the Chat tab in the Process Editor.

See docs/PROCESS_DRIVEN_PLATFORM/ for detailed design documents.

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:

Email Login (primary): Users enter email → receive 6-digit code → login
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 Workflow — How to develop Trinity (context loading, testing, documentation)
Deployment Guide — Production deployment instructions
Versioning & Upgrades — Version strategy and upgrade procedures
Gemini Support Guide — Using Gemini CLI runtime for cost optimization
Trinity Compatible Agent Guide — Creating Trinity-compatible agents
Multi-Agent System Guide — Building multi-agent systems with coordinated workflows
Process Engine Design — Process Engine architecture and design documents
Testing Guide — Testing approach and standards
Contributing Guide — How to contribute (PRs, code standards)
Known Issues — Current limitations and workarounds

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

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

GitHub Issues: Report bugs and request features
GitHub Discussions: Ask questions and share ideas
Demo Video: Watch Trinity in action
Security Issues: See SECURITY.md for reporting vulnerabilities
Commercial inquiries: hello@ability.ai

<div align="center"> <sub>Built by <a href="https://ability.ai">Ability.ai</a> — Sovereign AI infrastructure for the autonomous enterprise</sub> </div>

Name	onboard
Description	Onboard this agent to Trinity platform. Creates required files, sets up git, deploys to Trinity, and installs Trinity skills for ongoing management.

onboard

SKILL.md

Why Trinity?

Ways to Use Trinity

1. Onboard an Existing Claude Code Agent

2. Create an Agent in Trinity

3. Deploy a Multi-Agent System

For AI Agents

Deep Agents vs Chatbots

The Four Pillars of Deep Agency

Features

Core Platform

Process Engine

Agent Capabilities

Operations

Comparison

Quick Start

Prerequisites

One-Line Install

Manual Installation

First-Time Setup

Access

Create Your First Agent

Architecture

Project Structure

Agent Templates

Template Structure

Design Guides

Public Agent Templates

Trinity Onboard Plugin

MCP Integration

Available Tools

Agent Management

Communication

System Management

Configuration

Additional Tool Categories

Multi-Agent Systems

Trinity Connect

Process Engine

Example Process Definition

Step Types

AI Process Assistant

Configuration

Environment Variables

Authentication

Documentation

Development

License

Contributing

Community & Support