Creating and Managing Agents

Every template follows a standard layout:

All bundled templates ship the canonical .gitignore, so an agent created from one never auto-commits caches, virtualenvs, or local databases into its repository. An agent created from any GitHub repository with auto-sync on gets the same rules merged into its .gitignore right after creation, before the first sync cycle can commit runtime state or credential files.

Runtime options: an agent's runtime — Claude Code (default), OpenAI Codex, or Gemini CLI — is chosen via runtime.type in template.yaml. The three options are claude-code (default), codex, and gemini-cli. See Agent Runtimes for details.

An agent has two names:

When you create an agent, Trinity performs these steps in order:

Once an agent is running, Trinity validates its workspace against best-practice conventions and surfaces the results in the Overviewtab on Agent Detail. The check is advisory only — it never blocks agent creation or deployment.

Results are grouped into findings ranked HARD / SOFT / INFO. Claude-specific checks (CLAUDE.md, .claude/ skills) are skipped for Codex and Gemini agents.

The 9 gitignore-related findings offer a one-click Fix button that rewrites the agent's .gitignore in place (uncommitted until the next git sync). Re-run anytime with Re-run analysis.

A github:owner/repo template does not need a template.yaml — Trinity creates the agent from the repository as it is. Because the trinity@abilityai plugin is pre-installed in the agent image and re-ensured on every boot, that agent can then make itself Trinity-compatible from inside its own container: run /trinity:onboard in its chat and choose Onboard in place. It writes template.yaml, .env.example, .gitignore, and .mcp.json.template and pushes them back to the repository (an agent with no push token prints the patch and says the result is container-local — in source mode, files written inside the container do not survive a reset unless pushed). The walkthrough lives in Abilities Marketplace under the trinity plugin. Whether the pre-installed plugin was present, withheld (with the reason), or switched off is reported by the compatibility check on the Overview tab.

When you create an agent from a repository you already have — rather than a curated template — you choose how Trinity should take it on:

Copy is the right choice when you want to start from someone's repository without staying attached to it. The agent gets the files and nothing else: no GitHub credentials are stored, no remote is configured, and the agent never appears on git-sync surfaces. If you later decide you do want a repository, use Initialize GitHub Syncon the agent's Git tab.

Creation refuses clearly rather than doing something surprising: an intent on a non-GitHub template, a fork without fork parameters, a copy or clone of a template that requires fork-to-own, and copy for an ephemeral agent all return a named error before anything is created. An unreadable or private source without a token is reported as “not found or private” — it never confirms whether a repository exists.

After creating an agent from a repository, the create dialog runs the compatibility check inline and shows the result before you leave. It waits for the agent to genuinely finish starting (not merely for the container to exist), then reports findings. If the agent fails to start, you are told so rather than left on a spinner.

The check is advisory — the agent exists either way, and you can re-run the analysis from the Overview tab at any time.

REST API:

POST /api/agents
Content-Type: application/json
Authorization: Bearer <token>
Idempotency-Key: <optional-unique-key>

{
  "name": "my-agent",
  "display_label": "My Agent",
  "template": "github:Org/repo@branch",
  "import_intent": "copy"
}

import_intent accepts fork, copy, or clone, and applies only to github: templates. Omit it for the legacy behaviour. Supplying an Idempotency-Key makes a retried create safe: the same key within 24 hours replays the original response instead of creating a second agent, and a duplicate still in flight returns 409.

A copy-intent response carries an import_snapshot block recording the source repo, branch, commit SHA, and file count.

MCP tool:

create_agent(name="my-agent", template="github:Org/repo@branch", import_intent="copy")

The MCP tool accepts copy and clone. Fork stays UI/REST-only because it needs fork parameters.

Some templates are meant to be owned by the person deploying them, not run directly from the shared upstream repo. A template opts into this by declaring fork_to_own: required in its template.yaml. When you create an agent from such a template, Trinity copies the template into your own GitHub repository before building the container:

Prerequisite:configure a GitHub PAT with repo-creation scope before creating the agent. If the destination repo name is already taken, Trinity reuses it when it's empty or already holds the template's exact tip; if it's bound to another live agent or contains unrelated data, creation fails with a conflict so nothing is overwritten.

Control the lifecycle, health, and resources of your Trinity agents through the UI, API, or MCP tools.

The Chat tab in Agent Detail provides a bubble UI for conversing with agents, with persistent history and real-time status updates.

Direct shell access to an agent container is by SSH with a short-lived key you supply. The browser terminal tab that once lived on the agent page has been retired; the WebSocket it used remains available to API clients.

Full details in Agent Terminal.

Two-panel file manager in the Agent Detail Files tab for browsing, previewing, and editing agent workspace files.

Per-agent settings for autonomy, read-only mode, resources, capabilities, execution timeout, and runtime.