Creating and Managing Agents
Everything you need to create, manage, and interact with Trinity agents: templates, lifecycle control, chat, terminal, files, logs, and configuration.
Creating Agents
Agents are created from templates or from scratch. Each agent runs as an isolated Docker container with its own filesystem, credentials, and MCP server configuration.
Template Sources
github:Org/repo format. Supports branch selection with github:Org/repo@branch. Private repos require a GitHub PAT.template.yaml via the GitHub API and cached for 10 minutes. These appear as cards on the Templates page.config/agent-templates/ directory.CLAUDE.md.Template Structure
Every template follows a standard layout:
| File | Purpose |
|---|---|
| template.yaml | Agent metadata: display_name, description, resources, credentials, runtime |
| CLAUDE.md | Agent instructions and system prompt |
| .mcp.json.template | MCP config template with ${VAR} placeholders for credential injection |
| .env.example | Example credentials file listing required environment variables |
Runtime options: claude-code (default) or gemini-cli, set via runtime.type in template.yaml.
Creation Flow
When you create an agent, Trinity performs these steps in order:
Template is cloned (GitHub) or copied (local/from-scratch).
base_image is validated against the allowlist. Only trinity-agent-base:* is permitted by default.
A Docker container is built from the base image.
Template files are copied into /home/developer/ inside the container.
Credential requirements are extracted from .mcp.json.template.
If API subscriptions exist, one is auto-assigned via round-robin (fewest agents first).
The agent starts automatically and is labeled for fleet management.
Creating via UI
Click Create Agent on the Dashboard or Agents page.
Select a template source. GitHub templates display as cards with metadata from template.yaml.
Enter an agent name (lowercase, hyphens only).
Click Create.
Creating via API and MCP
REST API:
POST /api/agents
Content-Type: application/json
Authorization: Bearer <token>
{
"name": "my-agent",
"template": "github:Org/repo@branch"
}MCP tool:
create_agent(name="my-agent", template="github:Org/repo@branch")What Agents Inherit
CLAUDE.md from the template as their system prompt.mcp.json.template, with placeholders resolved at runtime/home/developer/Limitations
base_image must match the configured allowlist. Requests for blocked images return HTTP 403.template.yaml may not appear immediately.Managing Agents
Control the lifecycle, health, and resources of your Trinity agents through the UI, API, or MCP tools.
Start and Stop
Toggle an agent between Running and Stopped using the switch on the Dashboard, Agents page, or Agent Detail page. A loading spinner displays during state transitions.
API: POST /api/agents/{name}/start and POST /api/agents/{name}/stop
MCP: start_agent(name) and stop_agent(name)
Rename
Click the pencil icon next to the agent name on the Agent Detail page to edit inline. Renaming is atomic: it updates the database, renames the Docker container, and broadcasts the change via WebSocket. System agents cannot be renamed. Only owners and admins have permission.
API: PUT /api/agents/{name}/rename with body {"new_name": "new-name"}
Delete
Use the Delete button on the Agent Detail page. A confirmation dialog is required. Deletion cleans up the container, network, sharing records, schedules, activities, and event subscriptions.
Health and Status
The agent header displays status (Running/Stopped), CPU and memory usage, network I/O, and uptime. Telemetry auto-refreshes every 10 seconds. Fleet-wide monitoring is available at GET /api/monitoring/fleet-health. Health levels: healthy, degraded, unhealthy, critical, unknown.
Resource Allocation
Configure per-agent memory and CPU limits in the Config tab. Execution timeout is configurable per agent (range: 60–7200 seconds, default: 900 seconds / 15 minutes).
Listing
The Agents page shows horizontal row tiles with success rate bars. Filter by name, status, or tags. The Dashboard offers a network graph view and a timeline view.
Agent Chat
The Chat tab in Agent Detail provides a bubble UI for conversing with agents, with persistent history and real-time status updates.
Key Concepts
/ in the chat input to trigger a dropdown of available playbooks with ghost text showing command syntax and argument hints.--resume flag.How It Works
Open an agent's detail page and click the Chat tab.
Select an existing session or click New Chat.
Type a message and press Enter. The status label updates in real-time.
The response appears as a chat bubble with cost and token tracking.
Voice Chat
Click the microphone button to start a voice session. Audio streams bidirectionally through the backend WebSocket proxy to Gemini 2.5 Flash Native Audio (~280ms latency). Transcripts are auto-saved to the chat session with source="voice" markers. Requires GEMINI_API_KEY configured on the platform.
Session Management
Sessions persist across container restarts. Context window tracking shows token usage (e.g., “45.5K / 200K”). Session cost tracking shows cumulative cost across the conversation.
Chat API Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /api/agents/{name}/chat | POST | Send chat message |
| /api/agents/{name}/chat/sessions | GET | List all sessions |
| /api/agents/{name}/chat/sessions/{id} | GET | Get session with messages |
| /api/agents/{name}/chat/sessions/{id}/close | POST | Close session |
Agent Terminal
Browser-based xterm.js terminal providing direct access to the agent's Claude Code TUI, with mode switching between Claude, Gemini, and Bash.
Open the agent detail page and click the Terminal tab.
The terminal connects via WebSocket to the agent container's PTY.
A mode toggle in the header switches between Claude (Claude Code interactive mode), Gemini (Gemini CLI, requires GEMINI_API_KEY), and Bash (raw shell access).
The terminal supports resize and adapts to the browser window dimensions.
SSH Access
Generate ephemeral SSH credentials via the API or MCP. ED25519 keys with configurable TTL. SSH ports: 2222–2262 (incrementing per agent). API: POST /api/agents/{name}/ssh-access. MCP: get_agent_ssh_access(name).
Agent Files
Two-panel file manager in the Agent Detail Files tab for browsing, previewing, and editing agent workspace files.
Open the agent detail page and click the Files tab.
The left panel displays a file tree with search; the right panel shows a preview of the selected file.
Supported previews: images, video, audio, PDF, and text files.
Click the edit button on any text file to modify and save inline. Delete files directly with protected path warnings for critical files.
Toggle Show hidden files to reveal dotfiles. The agent workspace root is /home/developer/.
Content Folder Convention
The content/ directory is gitignored by default. Use it for large generated assets such as images, audio, and video.
Shared Folders
Agents can expose their workspace folder for other agents to mount as a collaboration mechanism. Configure in the agent's Sharing tab using the Expose and Consume toggles. Permission-gated: only permitted agents can mount a shared folder.
Logs and Telemetry
Container Logs
Open the agent detail page and click the Logs tab. A fixed-height scrollable container displays Docker container stdout/stderr. Logs auto-refresh with smart auto-scroll: new content scrolls to the bottom automatically, but scrolling stops if you scroll up manually.
Live Telemetry
The agent header bar displays live resource metrics: CPU usage, memory (MB), network I/O (bytes in/out), and uptime. Metrics auto-refresh every 10 seconds.
Centralized Logging via Vector
All container logs are captured by the Vector log aggregator and written to structured JSON files:
Platform logs: /data/logs/platform.json
Agent logs: /data/logs/agents.json
OpenTelemetry
Claude Code agents export OTel metrics including cost, token usage, and productivity. These metrics are available on the Dashboard.
Agent Configuration
Per-agent settings for autonomy, read-only mode, resources, capabilities, execution timeout, and runtime.
Autonomy Mode
Master toggle that enables or disables all scheduled operations for an agent. Toggle from the Dashboard, Agents page, or Agent Detail view. When disabled, all schedules for that agent are paused.
Read-Only Mode
Prevents modification of source files (*.py, *.js, etc.) inside the agent container. Uses PreToolUse hooks to intercept Write, Edit, and NotebookEdit tool calls. Allowed patterns: output/*, content/* (generated files are permitted).
Execution Timeout
Configurable time limit for agent executions. Range: 60–7200 seconds (default: 900 seconds / 15 minutes). Applies to all trigger methods: task, chat, schedule, MCP, and paid endpoints.
Per-Agent API Key
Toggle between the platform API key and your own Claude subscription in the Terminal tab. The agent container is recreated when this setting changes.
Model Selection
Choose the Claude model used for tasks and scheduled executions. Available models: Opus 4.5/4.6, Sonnet 4.5/4.6, Haiku 4.5. Custom model input is supported. The model_used field is recorded in the execution audit trail.
