Agents

Three ways, all equivalent: in the UI, click Create Agent in the Dashboard header (or Use Template on the Library page), pick a template source, enter a name (lowercase, hyphens allowed), and click Create; via the API, POST /api/agents with {"name": "my-agent", "template": "github:Org/repo"}; or via the MCP tool create_agent. In every case Trinity clones the template, builds an isolated Docker container from the base image, copies the template files into /home/developer/, and starts the agent automatically. See Creating Agents.

Yes. Use the github:Org/repo template format, and append @branch to build from a specific branch: github:Org/repo@branch. Private repositories require a GitHub personal access token configured before you use them as a template source. See Creating Agents and GitHub PAT Setup.

Yes. A github:owner/repo template that points at a publicrepository clones anonymously — no personal access token required. This is source-mode only, though: without a token the agent can read and run the template but cannot push its changes back, and features that write to GitHub (the working-branch auto-sync heartbeat, fork-to-own) stay unavailable until you add a token. Add a per-agent or personal PAT later to unlock write access. See Creating Agents and GitHub PAT Setup.

No. The Librarypage (formerly Templates — the old /templates path redirects to /library) ships a curated Starter Templates section (recommended starters: scout, sage, scribe) auto-discovered from the platform's config/agent-templates/ directory, plus any GitHub templates an admin has configured as cards. If you want a blank slate, choose From Scratch— it creates a minimal agent with a default CLAUDE.md you can build on. See Creating Agents.

template.yaml is the agent's metadata file: display_name, description, resources, credentials, and runtime (which CLI harness the agent uses, plus an optional model override). It can also declare data_paths (globs under data/holding runtime data, auto-added to the agent's .gitignore), schedules: (recurring work created with the agent), plugins: (the Claude Code marketplace plugins the agent depends on, re-installed on every boot), and fork_to_own: required (copy the template into your own GitHub repo at creation). The rest of a template is CLAUDE.md (agent instructions), .mcp.json.template (MCP config with ${VAR} placeholders), and .env.example (required credentials). Note that GitHub template metadata is cached for 10 minutes, so template.yaml edits may not appear immediately. See Creating Agents.

Declare them in a plugins: block in template.yaml — a marketplaces: list (name plus owner/repo or an https source) and an installed: list of plugin@marketplace entries. Trinity materializes the block at creation as a committed, secret-free ~/.trinity/plugins.yaml, and on every container boot the agent re-installs anything declared but missing, headlessly. Plugins installed by hand inside the agent are notcaptured back — they live in gitignored Claude Code state and vanish when the workspace is reconstituted from git onto a fresh volume or another host — so add them to the template too. Adding the block to an existing agent takes effect on its next restart; the abilities /trinity:sync plugins skill installs the difference right away. See Creating Agents.

Every template's base_image is validated against an allowlist, and blocked images are rejected with HTTP 403. By default only trinity-agent-base:* images are permitted; an admin can configure additional allowed images. Either switch the template to the standard base image or ask your admin to extend the allowlist. See Creating Agents.

The runtime is the CLI harness that executes the agent inside its container, chosen via runtime.type in template.yaml: claude-code (default), codex (OpenAI Codex), or gemini-cli. They differ in auth (Codex uses OPENAI_API_KEY and skips Claude-subscription auto-assignment; Gemini uses a Gemini API key), instruction file (Codex reads AGENTS.md— Trinity mirrors the template's CLAUDE.md into it at startup), session resume (a Codex agent cannot resume, so its Workspace turns replay the visible history as text rather than carrying working memory forward), and cost reporting (estimated for Codex, actual for the others). The runtime is fixed at creation: to change it, recreate the agent from a template that declares a different runtime. See Agent Runtimes.

Toggle the Running/Stopped switch on the Dashboard (Grid tiles and List rows both carry it) or the Agent Detail page — a spinner shows while the state changes. Via the API, use POST /api/agents/{name}/start and POST /api/agents/{name}/stop; via MCP, start_agent(name) and stop_agent(name). See Managing Agents.

A plain stop/start keeps the same container, so everything in it survives — except /tmp, which is RAM-backed scratch space. A recreate replaces the container (this happens on resource, capability, or mount changes, per-agent API key changes, and image upgrades), but the agent's home directory /home/developer lives on a durable named Docker volume, so your workspace files and anything under data/survive recreates, image upgrades, template re-pulls, and subscription switches. A template re-pull resets git-tracked files to the template's main branch but never wipes untracked files. Only files written outside the home volume are lost on recreate. See Agent Data & Portability.

No. Deleting stops and removes the container immediately, but it is a soft delete: the workspace volumes, schedules, chat history, sharing records, permissions, and credentials are all preserved until a retention sweep purges them (default: 180 days). Schedules stop firing right away. During the retention window an admin can recover the agent — recovery restores the record but does not recreate the container, so start the agent afterwards. See Managing Agents.

Yes, with an enterprise-tier feature: a disposable ("ghost") agent is created with a hard budget — a maximum number of runs and/or a time limit. When the budget is spent it is discarded immediately and completely: the container and its data are removed with no soft-delete window and no reserved name. This is aimed at one-off jobs, often spawned on demand by another agent, rather than long-lived agents you manage by hand. In a community build agents are always long-lived (no budget). See Managing Agents.

Renaming is atomic: Trinity updates the agent's name across every database record that references it (schedules, executions, chat history, sharing, permissions, tags, skills, shared files, and more), renames the Docker container, and broadcasts the change live over WebSocket. Click the pencil icon next to the agent name on the Agent Detail page, or use PUT /api/agents/{name}/rename / the MCP tool rename_agent. Only owners and admins can rename, and system agents cannot be renamed. See Managing Agents.

Set a display label. The label is the human-facing name shown across the UI — the header, agent pickers, search, sort, and the activity timeline — and editing it never moves the immutable slug, so URLs, MCP tool names, schedules, and webhooks all keep working. It's owner-only, and clearing it back to blank falls back to showing the slug. This is the change you want for everyday relabeling. See Managing Agents.

Renaming moves the immutable slug — the agent's canonical name that URLs, MCP tool names, schedules, and webhooks all resolve to — so it's the heavier operation and rewrites records across the platform. A display label is a presentation-only friendly name layered on top of the unchanged slug. Prefer the label for day-to-day relabeling and reserve a rename for when you genuinely need the canonical name to change. See Managing Agents.

Click the gear button ("Configure resources") in the agent header to open the resource modal. Memory options are 1g through 64g and CPU options are 1, 2, 4, 8, or 16 cores; either limit can be left as "Inherit default". Limits are enforced at the container level via Linux cgroups and take effect on the next restart. Admins set the fleet-wide defaults for new agents under Settings. See Agent Configuration.

Each agent has an execution timeout, configurable from 60 to 7200 seconds (default: 3600 seconds / 60 minutes), applied to every trigger method — tasks, chat, schedules, MCP, and paid endpoints. The agent timeout is also the ceiling for its schedules: lowering it below an active schedule's own timeout is rejected with 400 error=agent_timeout_below_active_schedules, and creating a schedule with a longer timeout than the agent cap is rejected too. Manage it via GET/PUT /api/agents/{name}/timeout. See Agent Configuration.

Read-only mode prevents the agent from modifying source files (*.py, *.js, and so on) inside its container by intercepting Write, Edit, and NotebookEdit tool calls with hooks. Generated output is still allowed under output/* and content/*. Toggle it in the agent header. Codex agents enforce the same restriction through the Codex sandbox (--sandbox read-only) instead of tool hooks. See Agent Configuration.

Autonomy is the master switch for an agent's scheduled operations: turning it off pauses all of that agent's schedules at once, and turning it back on resumes them. You can flip it from the Dashboard (Grid or List), or the Agent Detail view, or via PUT /api/agents/{name}/autonomy. It only affects schedules — it is not a general on/off switch for the agent itself. See Agent Configuration and Scheduling.

Export the agent's runtime data with POST /api/agents/{name}/data/export (or the MCP tool export_agent_data) — it captures everything under /home/developer/data as a tar archive with a manifest. On the destination instance, recreate the agent from the same template, then import the archive with POST /api/agents/{name}/data/import (or import_agent_data). Import only writes inside data/ and skips any entries that try to escape it. Export requires a running agent, and a per-agent lock prevents concurrent export/import. See Agent Data & Portability.

Yes, via SSH — but it is admin-only and disabled by default. An admin first enables ssh_access_enabledunder Settings → Ops Settings, then generates ephemeral credentials with POST /api/agents/{name}/ssh-access or the MCP tool get_agent_ssh_access. Access is key-based only— you supply your own public key and the server never handles a private key (the old password option was removed; the agent's SSH daemon rejects password auth). Credentials expire automatically after their TTL, which is now enforced on the container itself, not just in metadata. Agents listen on incrementing SSH ports starting at 2222. See Agent Terminal.

Open the Files tab on the Agent Detail page: the left panel is a searchable file tree of the workspace (/home/developer/), and the right panel previews the selected file — images, video, audio, PDF, and text are supported. Text files can be edited and saved inline, New folder creates a directory in place (workspace-confined), and files can be deleted with warnings on protected paths. Toggle Show hidden files to reveal dotfiles like .env and .claude/. Downloads are supported up to 100 MB per file. See Agent Files.

The Logstab on the Agent Detail page shows the container's stdout/stderr with auto-refresh and smart auto-scroll, also available via GET /api/agents/{name}/logs or the MCP tool get_agent_logs. All container logs are additionally captured by the Vector log aggregator into structured JSON files — /data/logs/platform.json for platform services and /data/logs/agents.jsonfor agents — which you can query with docker exec trinity-vector sh -c "tail -50 /data/logs/agents.json" | jq .. Anything your agent prints to stdout or stderr lands there automatically. See Agent Logs and Telemetry.

Once an agent is running, Trinity checks its workspace against 88 best-practice conventions — a valid template.yaml, a non-gitignored .claude/ directory, accidentally committed secrets, and more — and shows the findings in the Agent Detail Overview tab, ranked HARD / SOFT / INFO. It is purely advisory and never blocks creation or deployment; Claude-specific checks are skipped for Codex and Gemini agents. The nine gitignore-related findings offer a one-click Fixbutton that rewrites the agent's .gitignorein place — the change stays uncommitted until the agent's next git sync. Use Re-run analysis to re-check at any time. See Creating Agents.

Create an agent from it and pick an import intent. Clone (the default) keeps the agent wired to that remote and pushes back to it. Fork forks it into your own GitHub account first, with upstream pointing at the original. Copy takes a one-time snapshot of the files, strips the git history, and gives the agent a standalone workspace with no remote, no token, and no sync. Copy is the right choice when you want to start fromsomeone's repository without staying attached to it. After creation the dialog runs the compatibility check inline and shows the result before you leave. See Creating Agents.

Yes — use Bind to your own repoon the agent's Gittab. Trinity creates the destination repository under your account (private by default), pushes the agent's current workspace history into it, repoints origin, saves your token as the agent's own, and rebuilds the container so the change survives a restart. The agent keeps its name, identity, name reservation, data volumes, and history — nothing is re-provisioned. The agent must be running, and the action is owner-only and human-only (there is deliberately no MCP tool, since it needs your personal token). See GitHub Sync.

The Credentialstab shows a per-variable checklist: what the agent needs (read from its live workspace, so a forked or hand-edited agent reports its actual requirements), which are already set (probed from the agent's own .env— names only, values are never read), and where to get the missing ones via the template author's setup link. Fill values in directly on the checklist. It renders even when the agent is stopped, and a failed status probe is reported as a failure rather than shown as “nothing configured”. See Credential Management.

Three tiers, in order: an admin-curated list in Settings, if one exists — in which case nothing else is consulted; otherwise a curated remote registry fetched over HTTPS, so the starter catalogue can refresh without upgrading Trinity; otherwise the bundled defaults, which are empty. Registry results are cached for about an hour with a durable last-known-good copy, and every failure degrades quietly to the next tier, so agent creation never depends on a registry being reachable. See Creating Agents.