Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff

trinity Plugin

Connect, deploy, operate, and sync agents on Trinity — the operating system for the AI-native company: open source, self-hosted, that you own. Seven skills (trinity v2.12.1) covering the complete lifecycle — from a guided first journey through connection, deployment, remote loops, and instance provisioning.

Build Autonomous Loops for Your AI Agents

Jun 2026

🧭 New to Trinity? Start with /trinity:start-here — a guided, resumable walkthrough that takes you from “what is Trinity?” to your first agent running on your own instance. Jump to the section ↓

Installation

/plugin install trinity@abilityai

Skills

SkillDescription
/trinity:start-hereNew here? Guided, resumable journey: what Trinity is → get an instance → connect → first agent alive
/trinity:connectOne-time: authenticate and configure the MCP connection
/trinity:onboardPer-agent: compatibility check, file creation, deploy from the repo - or, run inside an already-deployed agent, onboard it in place
/trinity:syncOngoing: git-based sync between your repo and the deployed agent, multi-remote, with schedule and plugin reconciliation
/trinity:loopRun a remote agent task in a sequential, bounded loop - fire once, disconnect, check back
/trinity:create-dashboardGenerate an agent-specific /update-dashboard skill that keeps dashboard.yaml current
/trinity:deploy-new-instanceDeploy a Trinity instance on any server and scaffold an ops agent to manage it

The Guided Journey: /trinity:start-here

/plugin marketplace add abilityai/abilities
/plugin install trinity@abilityai
/trinity:start-here

One command that concierges a newcomer through the whole path — it sequences the skills below rather than replacing them, so you never have to know which one comes next.

StageWhat happens
OrientWhat Trinity is, in plain terms, plus the current release
Choose your doorJust looking · build my first agent · I already have agents · set up my instance
Get an instanceHands off to /trinity:deploy-new-instance (the DigitalOcean installer, a Marketplace image on DigitalOcean, AWS or Vultr, your own server, or local Docker) — or takes the URL you already have
Connect + verifyHands off to /trinity:connect, then runs a live smoke test: fleet visible, instance healthy, docs assistant online
First agent aliveDeploys via /trinity:onboard (or picks an existing agent) and exchanges a real message with it
•Nothing is deployed until you choose it. The “just looking” door asks for no credentials and creates nothing.
•It resumes. Progress is saved in ~/.trinity/start-here.json, so quitting — or the Claude Code restart needed to load the MCP server — picks up exactly where you stopped. Run /trinity:start-here reset to start over.
•Answers come from live documentation, not a script. Questions are answered from these docs at run time — through the public Trinity Docs Q&A before you have an instance, and through your instance's own ask_trinity tool afterward.

Already know what you want? The individual skills below work standalone, in any order.

How It Works

Step 1: Connect (One-Time)

/trinity:connect

This:

1.Prompts for your Trinity instance URL
2.Authenticates via email verification
3.Provisions an MCP API key
4.Writes .mcp.json pointing at <instance-url>/mcp - the production frontend serves that path, so it works on installs that expose only ports 80/443; it falls back to the MCP server's own port 8080 when the route is not served

The connection works only while the instance has External MCP access on. A fresh install starts with it off and answers 403 external_mcp_access_off; an admin turns it on once under Settings → MCP Keys. See MCP Server.

An account that requires a second factor stops after step 2: complete the sign-in in the web UI, create the key under Settings → MCP Keys, then re-run /trinity:connect --force.

The account needs the operator role or above. A user account works in the Workspace only and is refused MCP access (403 workspace_only), so the skill stops and tells you an admin must raise it under Settings → Access → User Management. The email whitelist's role picker defaults to user, so whitelist a developer as operator; self-signup and sharing an agent only ever create user accounts. Two other stops are explained up front: when a login policy turns email-code sign-in off (403 email_code_disabled), sign in with SSO in the web UI and mint the key under Settings → MCP Keys; when the instance has no email provider, the skill says no code will arrive (it goes to the backend log). See Roles and Permissions.

After the instance upgrades and its backend restarts, sign in again in the browser and reconnect MCP clients (/mcp in Claude Code).

No instance yet? /trinity:connect hands you to /trinity:deploy-new-instance. There is no self-serve sign-up for a hosted instance: you deploy your own, or Ability AI opens a Trinity Managed instance for you. See Authentication.

After connecting, Trinity MCP tools become available: mcp__trinity__list_agents, mcp__trinity__chat_with_agent, mcp__trinity__deploy_local_agent, mcp__trinity__run_agent_loop (and the rest of the tool surface)

Step 2: Add your GitHub token (One-Time)

Deployment is repository-first: Trinity clones the agent straight from its GitHub repo. What the agent can do with that repo depends on the token:

TokenResult
Your own token (Settings → MCP Keys → Personal GitHub Token), fine-grained PAT with Contents: Read and write, on a repo your GitHub account ownsThe agent gets a working branch it alone writes, with auto-sync on, so its work lands back in git
A read-only token, or the instance-wide token an admin setThe agent is pull-only: it tracks the branch and its own changes never reach git
No tokenPublic repos clone pull-only; private repos fail

The create response's git_mode says which you got and why. See GitHub Sync and GitHub PAT Setup.

Step 3: Onboard (Per Agent)

/trinity:onboard            # asks what you want: deploy, adapt only, or onboard in place
/trinity:onboard analyze    # report only — no changes
/trinity:onboard in-place   # force the in-place path (see below)

Run it in the agent's directory. It analyzes the current state, then:

1.Creates the Trinity files it finds missing - template.yaml (with plugins:, schedules:, and credential declarations), .env.example, .gitignore, .mcp.json.template
2.Checks GitHub readiness - the token tier and a pushed remote - before any deploy runs
3.Deploys - from the repository by default (create_agent with github:owner/repo@branch, as kind: "agent" unless you want a pull-only deployment); from a local archive as the fallback when the repo doesn't exist yet or the instance can't reach GitHub, with an offer to promote the agent onto the repo path afterwards
4.Injects gitignored credentials (.env) after deploy, since they are never in the clone or the archive
5.Reconciles declared schedules onto the instance, matching on schedule name
6.Verifies with the platform's own compatibility report - the report, not the skill's checklist, is the definition of “compatible”

Two things it will tell you and you cannot skip: declared schedules arm only on a literal enabled: true, and a newly created agent's autonomy toggle is off- until you turn it on in the UI, the scheduler skips every cron trigger for that agent. Turning autonomy on is a person's act; an agent's own key cannot do it.

The files it scaffolds follow current platform rules: .gitignore excludes .trinity/ runtime state with the star form (.trinity/*) and re-includes the files you author there (pre-check, post-check, pre-snapshot, setup.sh, persistent-processes.allow, brain-orb/, pipelines/, plugins.yaml), which the platform's hard compatibility check requires; it no longer ignores .claude/settings.json (project settings may be committed; Trinity keeps a copy out of a commit only when it carries platform hook paths or credential-bearing keys), a skill that needs a person raises an ask with ask_operator and reads the result with get_my_ask (one decision per ask; when the facts change while it is pending, the agent replaces its own ask rather than repeating it, and when the ask goes moot it ends it with withdraw_ask; see Approvals), and a call refused for exceeding the instance's chain-depth limit is never retried.

Run from inside a deployed agent, onboarding needs a permission. An agent's own key can create or deploy another agent only when that agent holds Manage other agents, and /trinity:sync schedules can write another agent's schedules only with Change other agents' schedules. An instance admin grants both in the agent's Settings → Guardrails → Permissions to change itself. Without them the call is refused, and the skill names the missing permission instead of working around it. Your own user key needs neither.

There are three ways an agent gets onto Trinity:

PathWhenWhat happens
From the GitHub repo (default)The agent is adapted and pushedTrinity clones the repo - onto a working branch with auto-sync, or pull-only on the tracked branch, depending on the token (Step 2) - and materializes declared schedules and plugins at creation
From local files (fallback)No repo yet, air-gapped instance, or a throwawayA snapshot of your directory is deployed; promote it onto the repo path with initialize_github_sync before it becomes long-lived
Deploy as-is, then onboard in placeA repo you can't or shouldn't adapt locally - someone else's agent, a bare repo with no template.yamlCreate the agent from the bare repo first (Trinity tolerates a missing template.yaml), then run /trinity:onboard inside that agent - see below

Step 4: Sync (Ongoing)

/trinity:sync                       # status of every remote
/trinity:sync push [@remote] [branch]
/trinity:sync pull [@remote]
/trinity:sync deploy [@remote] <branch>
/trinity:sync remotes | add-remote <name> <agent> [branch] | set-default <name>
/trinity:sync schedules [@remote]   # reconcile template.yaml schedules: against the live agent
/trinity:sync plugins [@remote]     # reconcile template.yaml plugins: against what's installed

Sync is git-based and multi-remote - a .trinity-remote.yaml registry lets one repo serve several instances (production, staging), each tracking its own branch. push advances the deployed agent to your new commit; pull brings the agent's own commits back; deploy switches a remote to another branch.

An agent created from your own repo with your own token runs on its own working branch (trinity/<agent>/<id>), which merges main in on every pull. Sync verifies such an agent by checking that its branch contains your local HEAD, not that the two are equal, and never checks that clone out onto another branch: push @remote <branch> and deploy refuse it and tell you to recreate the agent from github:owner/repo@<branch> instead.

schedules and plugins treat template.yaml as the design truth and the operator as owner of the live extras: they create or install what is declared but missing, and report what is live but undeclared - never delete, never uninstall. Both also run automatically after push, pull, and deploy, and read-only in status. plugins reads what is installed from the platform's compatibility report first, and only falls back to the CLI inside the container. A plugin installed by reconciliation loads on the agent's next execution.

Onboarding a Deployed Agent In Place

When /trinity:onboard detects it is running inside a deployed Trinity agent - the agent's own workspace, with the platform's MCP tools already injected - it offers Onboard in place as the recommended goal (or take it directly with /trinity:onboard in-place, which is also the one-line form an orchestrator dispatches after deploying a bare repo). Nothing is created; the agent already exists. Instead it:

1.Writes the Trinity files - template.yaml (with plugins: declaring at least trinity@abilityai), .env.example, .gitignore, .mcp.json.template if the agent runs MCP servers of its own
2.Installs the declared plugins now, with the same CLI calls the container's boot hook uses, so they are present from the next execution rather than the next restart
3.Commits and pushes the result back to the repo - this step matters: a pull-only agent tracks its branch read-only, so a file written in the container is lost on the next reset unless it reaches the repo. If the agent has no write credentials, the skill tries the platform's push path and, failing that, stops and says so - it prints the patch and states that the result is container-local, rather than pretending
4.Reconciles declared schedules live
5.Finishes with get_agent_compatibility_report - every HARD finding is yours to fix; SOFT and AI findings are advisory

The trinity plugin is provided by the platform. The in-place path needs the plugin present in the container, and a bare repo declares nothing - so Trinity's agent image ships with it pre-installed, and every container boot re-installs it if missing, whether or not template.yaml declares it. A new agent therefore runs /trinity:onboard in-place straight away. Only an agent still running on an image built before the pre-install needs the one-time bootstrap from its terminal, followed by a fresh session:

claude plugin marketplace add abilityai/abilities && claude plugin install trinity@abilityai --yes

Onboarding in place is idempotent - if the push was refused, grant the agent write credentials and re-run.

Remote Loops: /trinity:loop

The remote counterpart to Claude Code's built-in /loop. Where /loop re-invokes your local session on a cadence, /trinity:loop hands one bounded, sequential loop to a remote Trinity agent: it fires run_agent_loop once, returns a loop_id, and you can disconnect - the Trinity backend runs every iteration in order and exits on a hard cap or a stop signal. Use it for iterative refinement, agentic retry, and bounded polling that must outlive your session.

/trinity:loop [@agent] <message>             start a loop
/trinity:loop status <loop_id>               show per-run progress
/trinity:loop stop <loop_id>                 request a graceful stop
/trinity:loop local <message>                run the same bounded loop in this session

No @agent means this agent's remote copy - the usual case is looping your own remote counterpart on Trinity (resolved from .trinity-remote.yaml or by name match).

Modifiers, anywhere in the message:

ModifierEffect
5 times / x5 / max 10Iteration cap (max_runs, 1-100; default 5)
every 2m / every 30sPause between iterations (delay_seconds, up to 1 hour - for slower cadences, use a schedule instead)
until <condition> / stop when ...Until mode - the skill rewrites the message so the agent emits a [[DONE]] sentinel when the condition is met, and the loop exits early

Examples:

/trinity:loop @researcher draft section {{run}} of the report, 5 times
/trinity:loop @ci-agent run the test suite until it passes, max 10
/trinity:loop @monitor poll the deploy every 2m until it's healthy
/trinity:loop status loop_a1b2c3
/trinity:loop stop loop_a1b2c3

After firing, the skill starts a lightweight local watch by default - it polls the loop and reports run-by-run progress, stalls, and the final result. Say "fire and forget" to skip the watch; the remote loop runs either way and also appears on the agent's Loops tab in the Trinity web UI. Inside a deployed Trinity agent there is no watch - the wake-up tools it relies on are denied there - so poll with /trinity:loop status or a set_reminder instead.

Raising the per-run timeout is the owner's act. A loop's timeout_per_run cannot exceed the agent's execution timeout. The agent's owner raises that cap in the agent's settings. An agent key can raise it only when the agent holds the Manage other agents permission, which an instance admin grants; without it, a loop launched from inside a deployed agent raises an ask naming that permission instead of trying again.

A denial is a permission, not a typo. The loop tools enforce the same agent-to-agent permissions as chat_with_agent. An agent-scoped key can loop itself and the agents it has been granted, nothing else; your own user key is unaffected. A refused status or stop call answers Loop '<id>' not found or not accessible, whether or not the loop exists. Do not retry under another name: ask the agent's owner to grant the permission.

A peer loop runs only the target's declared skills. A loop one agent starts on another is a peer request: if its message invokes a skill the target got from the skills library rather than declaring it in its own repo, every iteration is refused skill_not_granted and nothing runs, unless an admin granted that skill to the caller. A loop on the agent itself, or one a person starts, is unaffected. See Agent Permissions.

local runs the same Fixed or Until loop natively in your Claude Code session - no Trinity connection, no loop_id. Use it when the task lives on this machine or Trinity is unreachable; if the loop must outlive your session, it is remote.

The loop mechanics - modes, template variables, stop signals, capacity, costs - are the platform's Sequential Agent Loops feature.

When to use what

You wantUse
One remote turnchat_with_agent
The same task over many inputs, all on one agentfan_out - see Fan-Out; for many agents, dispatch chat_with_agent per agent
One agent, N sequential iterations/trinity:loop (or run_agent_loop directly)
A recurring task on a cron cadenceA Trinity schedule

Dashboard Generation: /trinity:create-dashboard

/trinity:create-dashboard

Analyzes the agent's purpose and data sources, proposes a set of metrics, and - after your approval - scaffolds an agent-specific /update-dashboard skill that keeps dashboard.yaml current. Declare that skill's cron in template.yaml schedules:to keep the agent's dashboard live.

It also proposes which of those numbers to declare as business metrics, and writes or extends the metrics: block in template.yaml (name, type, label, a cadence that matches the schedule). The generated skill then records the same numbers as points with the record_metrics MCP tool after it writes the dashboard. That step is guarded: off Trinity it is skipped silently. A point for an undeclared metric comes back metric_undeclared. On an agent that is already deployed, an edit it makes to its own template.yaml is not seen by Trinity until you call refresh_metric_definitions or restart the agent, because auto-sync pushes and never pulls. Widgets can bind to a declared metric with metric: <name> and read the recorded series instead of a hand-typed value.

The generated skill writes only widget types Trinity renders - metric, status, progress, text, markdown, table, list, link, image, divider, spacer; anything else is stripped by the agent. There is no chart type: trend lines and sparklines come from the platform, which records each metric and progress widget's value on every fetch, keyed by the widget's stable id: - so the skill gives those widgets an id (reordering unkeyed widgets orphans their history) and never emits YAML anchors, which Trinity's hardened loader rejects. See Dynamic Dashboards.

Instance Provisioning: /trinity:deploy-new-instance

/trinity:deploy-new-instance

Deploys a complete Trinity instance - through the DigitalOcean guided installer (which you run in your own terminal, so your password never passes through the session), a Marketplace image (DigitalOcean 1-Click, the AWS Marketplace AMI or Vultr, launched from your cloud console and claimed in the browser), on any server you can reach over SSH (AWS EC2 included), or on local Docker; fresh installs and existing instances both - and scaffolds a dedicated ops agent with 13 skills to manage it (health checks, updates, rollbacks, provisioning). It builds from source or pulls prebuilt images (start.sh --hosted with a pinned TRINITY_IMAGE_TAG), seeds the admin account from .env so there is no first-run setup screen, and needs only the frontend port opened in the firewall - the MCP server is reachable through it at /mcp once an admin turns on External MCP access (Settings → MCP Keys). See Deploying Trinity and the Trinity Ops Agent.

Alternative: Trinity CLI

You can also deploy via the command line:

# Install CLI
pip install trinity-cli

# Initialize (one-time)
trinity init

# Deploy agent
trinity deploy .

See Trinity CLI for details.

Compatibility Requirements

Agents must have:

FilePurpose
CLAUDE.mdAgent identity and instructions
template.yamlTrinity metadata (name, description, resources, declared schedules and plugins)
.env.exampleDocuments required environment variables

Optional but recommended: dashboard.yaml (custom metrics dashboard), .mcp.json.template (MCP server configuration), template.yaml schedules: (declared recurring work, materialized at creation), and template.yaml plugins: (declared Claude Code plugins, re-installed on every boot - declare trinity@abilityai at minimum so the intent is in the repo; the platform provides that one plugin on every boot even when it is undeclared)

The authoritative verdict is the platform's compatibility report (Agent Detail → Overview), which /trinity:onboard runs at the end of every path. See Creating Agents.

See Also

•Agent Loops - The server-side loops feature /trinity:loop drives
•Trinity CLI - Command-line deployment
•Creating Agents - Agent creation in Trinity
•Trinity Ops Agent - Instance operations post-deploy
•Abilities Overview - Full toolkit overview