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

Agents

Creating agents, templates, runtimes, lifecycle and reboots, the Agent Detail page, config, files, logs. Short, grounded answers with links to the full documentation.

61 questions

What are the different ways to create an agent?

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.

Can I create an agent from a private GitHub repository or a specific branch?

Yes. Use the github:Org/repo template format, and append @branch to build from a specific branch: github:Org/repo@branch. A tag works the same way (github:Org/repo@v1.2.0) and pins the agent to that release: it never pulls, and moving it to another ref means recreating it. Private repositories require a GitHub personal access token configured before you use them as a template source. See Creating Agents and GitHub PAT Setup.

Can I create an agent from a public GitHub repository without a token?

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.

Do I need to write my own template to create an agent?

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. A github:owner/repo template doesn't even need a template.yaml: Trinity creates the agent from the repository as it is, and because the trinity plugin is pre-installed in every agent, that agent can make itself Trinity-compatible afterwards by running /trinity:onboard in its own chat. See Creating Agents and the Advanced Features FAQ.

What goes in template.yaml?

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.

How do I make sure my agent's Claude Code plugins survive a rebuild or a move?

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. One plugin you never have to declare is trinity@abilityai: the platform pre-installs it in the agent image and re-ensures it on every boot whether or not the template lists it (an omitted entry is never uninstalled). 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.

Why did creating my agent fail with an error about the base image?

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.

What's the difference between the Claude Code, Codex, and Gemini runtimes?

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 an OPENAI_API_KEYcredential — Trinity logs the CLI in with it before the first turn, so an API-key Codex agent works out of the box and a rotated key is picked up on the next turn — or a ChatGPT-plan login you run yourself with codex login; Codex skips Claude-subscription auto-assignment, and Gemini uses the platform Gemini key from Settings), instruction file (Codex reads AGENTS.md— at startup Trinity copies the template's CLAUDE.md into it only when the workspace has no AGENTS.md; one you ship yourself is left as it is), session resume (only Claude Code resumes a session in the Workspace — a Codex agent's Workspace turns replay the visible history as text, and Gemini's headless turns never resume), safety hooks (read-only mode and the guardrail hooks are Claude Code hooks; Codex enforces read-only through its sandbox), and cost reporting (reported by Claude Code, estimated from tokens for Gemini and Codex). The runtime is fixed at creation: to change it, recreate the agent from a template that declares a different runtime. See Agent Runtimes.

How do I start and stop an agent?

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.

Do my agents come back on their own after the server reboots?

Yes. Agent containers are created with Docker's unless-stoppedrestart policy, so after a host reboot or a Docker daemon restart every agent that was running comes back by itself and its schedules resume — nobody has to start agents by hand. An agent you deliberately stopped stays stopped, because the policy honours Docker's manual-stop flag, so a quarantined agent is never resurrected by a reboot. Agents may briefly show as stopped while Docker brings them back. The policy is set when the container is created, so agents created before it shipped adopt it on their next recreate (a resource, runtime, or base-image change), not on a plain restart; an upgrading install can sweep its existing fleet once. See Managing Agents and the restart-policy migration guide.

What survives an agent restart, and what survives a recreate?

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 reset to the template's main branch overwrites tracked files except those listed in .trinity/persistent-state.yaml, and never wipes untracked files. A force-replace pull (offered when a pull conflicts, and through the MCP git_pull tool) is different: it resets to the remote and deletes untracked files that are not gitignored, so keep work you need committed or in a gitignored folder. An ordinary pull rebases onto the remote and resets nothing. Only files written outside the home volume are lost on recreate. See Agent Data & Portability.

How should I organise my agent's workspace?

Think in three zones. A few folders are owned by the platform, which reads or writes them by path: data/, public/, uploads/, shared-out/, shared-in/, content/ and .trinity/; leave their names and places alone. Everything you version goes in the committed zone: identity and config files at the root, .claude/ skills, memory/, docs/, dated reports/<kind>/ files and project_files/<slug>/. Everything else lives only on the durable volume and is never committed: runtime state, scratch work in $TMPDIR (~/.tmp/, not /tmp), and side clones of other repos, each in its own gitignored folder. See Directory Structure in the Trinity-compatible agent guide.

What happens when I delete an agent — is everything gone immediately?

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.

Why can't I create a new agent with the same name as one I deleted?

Because deletion is a soft delete, the old agent's record still exists and reserves the name until the retention sweep purges it (default: 180 days). Pick a different name, or ask an admin to recover the soft-deleted agent if you actually want it back. See Managing Agents.

Why is my agent's name different from what I typed?

The name you type is the agent's display label; its permanent ID— the slug used in URLs, container names and MCP tools — is derived from it: spaces and any character other than ASCII letters, digits, -, _ and . become hyphens, repeated hyphens collapse, leading symbols are dropped, and everything is lowercased. The Create Agent dialog previews the ID under the Name field while you type, so you can check it before creating, and Edit lets you choose a different ID. A name with no ASCII letter or digit would format to nothing, so Create agent stays disabled until you add one. A name over 120 characters is still accepted, but the agent then renders under its ID instead of the name. See Creating Agents.

Why does the Create Agent dialog look different?

It was redesigned as a fixed two-pane picker. The left pane lists the sources — Blank agent, Import a GitHub repository, then Featured, Local templates and GitHub templates — with a Search templates box; the right pane shows the selected source, one Name field with the derived ID underneath, a read-only Runtime row, and the repository, import-intent and fork options when the source needs them. The dialog keeps one size whatever you pick and each pane scrolls on its own, so nothing jumps as options appear. The old separate Slug / Identifier and Display name fields are gone: type the name you want to see, and edit the ID only if you want a different one. Nothing changed in what gets created or in the API. See Creating Agents.

What happens when I rename an agent?

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. Open Settings › General › Identity › Agent id and click Rename… (the editor warns what the rename re-keys), 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.

How do I change an agent's friendly display name without renaming it?

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.

What's the difference between renaming an agent and giving it a display label?

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.

How is the Agent Detail page organized?

It lands on Overview(a live strip with CPU, memory and spend, then trends, health and recent activity) and puts everything else in tabs — Tasks, Chat, Reports, Canvas, Schedules, Loops, Skills, Payments, Files, plus the owner-only Channels and Permissions tabs and, pinned at the end of the strip, Settings, the one configuration home (General, Credentials, Guardrails, People, Channels, Integrations, Storage); Dashboard, Brain, Git, and A2A appear only when the agent supports them, and tabs that don't fit the window collapse into a More ▾menu — Settings never does. Every tab is deep-linkable with ?tab= (and a Settings pane with ?section=), and the URL follows the tab you pick, so a reload stays on it and Back steps through the tabs you visited. The header above the tabs holds the agent's identity, its running state, the Running and Autonomy switches, the bound GitHub repository with what is waiting to push or pull, the agent's tags, and a small ring showing how full its context window is. The Workspace and voice calls are reached from the navigation bar. The Chat tab runs each message as a new agent session, with the last 20 messages included for context, and carries a Continue in Workspace → link that opens the Workspace in its own browser tab when you want a conversation that keeps its memory. There is no browser Terminal tab any more (see the SSH question below), and ?tab=session redirects to the Workspace. See Managing Agents.

What's in an agent's Settings tab?

It's the owner-only home for everything about one agent, pinned at the end of the tab strip, with a left rail of panes that each answer one question. General— what the agent is: display name, id, avatar, description, tags, runtime, model and funding, execution timeout, parallel capacity, memory and CPU, the template's technical details, and a danger zone (reset to main, delete). Credentials— what secrets it runs with: the credential checklist, inject, upload, and encrypted export and import. Guardrails— what it may do: tool access (read-only mode is its Strict read-only profile), the turn-limit rules behind Manage rules, permissions to change itself, how many skills need approval, autonomy (read-only there), cross-model validation when the instance is entitled to it, and reliability (the dispatch circuit breaker and Wake this agent when an ask it raised ends). People — who it is shared with. Channels— voice replies, with a row to the Channels tab. Integrations — Expose via MCP and the agent's Trinity access key, with rows to Permissions, A2A and Payments. Storage— repository binding, GitHub token, auto-sync, shared folders and file sharing. A search box filters the rail, and one bar at the top lists every change waiting for a restart. The Running and Autonomy switches stay in the header and on the Dashboard. See Agent Configuration.

Where did the Info, Credentials, Access and Folders tabs go?

Into the Settings tab, which is now the one place an agent is configured: a left rail of panes, each answering one question, with the pane in the URL as ?section=. Template details and the description are under General; credentials have their own Credentials pane; shared folders are under Storage, next to the repository binding, the GitHub token and file sharing; the access roster is People, unchanged. Old links keep working — ?tab=info, ?tab=credentials, ?tab=folders and ?tab=accessland on the right pane — and Settings itself is pinned at the end of the tab strip, never inside the More ▾ menu. The header kept only identity, the running state, the Autonomy chip and the Workspace, Talk and Start/Stop controls; live CPU, memory and spend moved to the top of Overview. See Agent Configuration.

What does the bar at the top of Settings mean, and when does it clear?

It lists every change that is saved but waiting for the agent to restart, by name — File sharing, Shared folders, Memory and CPU, Guardrail rules, GitHub token, Funding — with one Restart now button (Start now when the agent is stopped). When nothing is waiting it reads Every change here is live. The list clears when the agent actually comes back up, not when you press the button: a stop and start from the header clears it too, and a restart that fails to bring the agent up leaves every entry listed, because nothing was applied. After the restart each row re-checks with the backend and lists itself again if its change still has not taken. See Agent Configuration.

How do I change an agent's execution timeout, and why was my new value refused?

Open Settings › General › Execution › Execution timeout and click Edit. The field takes whole minutes from 1 to 120 (default 60); an empty, fractional or out-of-range value is refused on the spot with a message that names the range, before anything is sent. If a valid value is refused after you save, an active schedule on that agent runs for longer than the new cap — the agent's timeout is the ceiling for every one of its schedules. The row says how many schedules and how long the longest runs, and offers Open Schedules: shorten that schedule first, or keep the cap at or above its timeout. A saved timeout applies to new runs. See Agent Configuration.

How do I find a setting on the agent's Settings tab?

Type what you are looking for into Find a setting, above the rail. It filters the panes by the words people use for each control, not just the pane names — timeout keeps General, secrets keeps Credentials, token or folders keep Storage, mcp keeps Integrations— and tells you when nothing matches, with a few words to try. If you know the pane, link straight to it: ?tab=settings&section=storage, for example. On a narrow window the rail is a Section select instead. See Agent Configuration.

How do I limit how much CPU and memory an agent can use?

Open Settings › General › Execution › Memory and CPU and click Edit. 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, which names the platform default it inherits. Limits are enforced at the container level via Linux cgroups. The change is saved at once and applied on the next restart — the row carries a restart badge and the bar at the top of Settings lists Memory and CPU with a Restart nowbutton; nothing restarts on save. Admins set the fleet-wide defaults for new agents under Settings. If you pick more cores than the Docker host has, the container gets the host's CPU count instead of failing to start. See Agent Configuration.

How long can an agent task run before it times out?

Each agent has an execution timeout — edited in minutes, 1 to 120, under Settings › General › Execution, and stored as 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.

What does read-only mode do?

Read-only mode prevents the agent from modifying source and config files (*.py, *.js, *.yaml, CLAUDE.md, .env, and so on) inside its container by intercepting Write, Edit, MultiEdit, and NotebookEdit tool calls with a hook. Generated output is still allowed under content/*, output/*, reports/* and exports/*, plus *.log and *.txt files. Choose the Strict read-only profile under Settings › Guardrails › Tool access, or use the Read-only toggle in the agent header or on the Dashboard as a shortcut (see Agent Guardrails). The configuration lives in a root-owned file the agent cannot edit. Codex agents enforce the same restriction through the Codex sandbox (--sandbox read-only) instead of tool hooks; Gemini CLI turns are not covered. See Agent Configuration.

What does the autonomy toggle actually control?

Autonomy is the master gate for an agent's scheduled operations: turning it off means none of that agent's schedules fire, and turning it back on lets them resume. It doesn't touch each schedule's own on/off switch — a schedule you disabled individually stays disabled when autonomy comes back on, and one you left enabled resumes automatically. You can flip it from the Dashboard (Grid or List), the Autonomy chip in the Agent Detail header, or via PUT /api/agents/{name}/autonomy; Settings › Guardrailsshows the switch read-only. It only affects schedules — it is not a general on/off switch for the agent itself. See Agent Configuration and Scheduling.

Which model do schedules, reminders and wakes run on?

The agent's own model, unless the run names one. On a Claude Code agent, the model you pick under Settings › General › Modelis saved as the agent's own model, and so is the model its template declares (runtime.model) at creation. Turns the platform starts without a model — wakes, ask endings, event tasks, and schedules, loops and reminders with no model of their own — run on it, and it survives a restart. A model this instance cannot run is skipped and those turns use the platform default; GET /api/agents/{name}/model shows which model they run on and why. See Model Selection.

Why can't my agent schedule its own wake-up or run a cron job from inside a task?

Because a task, schedule, loop, or MCP call runs the agent as a one-shot turn, and nothing it starts survives the end of that turn. Claude Code's built-in tools that promise a laterevent — scheduled wake-ups, cron entries, workflow and task-output notifications, messages to other local sessions, push notifications, remote triggers — would let the agent plan around an event that never arrives, so Trinity withholds that whole tool family from headless runs and points the agent at the platform's own mechanisms instead: run_agent_loop for repetition, set_reminder for a deferred self-trigger, and chat_with_agent to reach another agent. Subagents are unaffected (the turn waits for them). A background shell command still running when the turn ends is killed, and the execution records that it was, instead of reporting a clean success. The tool denial reaches an agent on its next recreate after the base image is rebuilt; the prompt guidance applies as soon as the platform is updated. See Agent Runtimes.

How do I move an agent to another Trinity instance?

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. Two size caps apply: the export itself is refused with 413 above AGENT_DATA_EXPORT_MAX_BYTES (default 5 GB), and the inline ?format=base64 variant that the MCP tool uses has its own smaller cap (AGENT_DATA_INLINE_MAX_BYTES, default 10 MB) — above it the response directs you to the streaming download instead. See Agent Data & Portability.

Can I get shell access to my agent's container?

Yes, over SSH with a key you supply — the browser terminal tab that used to live on the agent page has been retired. Access is admin-only and off by default: an admin switches on Enable SSH Access under Settings → Access, then requests credentials for a running agent with POST /api/agents/{name}/ssh-access (or the MCP tool get_agent_ssh_access), passing a public key (ssh-keygen -t ed25519) and a ttl_hours (default 4, maximum 24). Trinity injects the key into the container's authorized_keys and returns a ready-to-run sshcommand with the host and the agent's own port from the 2222–2262 range; the key is removed when the TTL expires. Password authentication is not supported, and the server never generates or sees a private key. See Agent Terminal.

How do I browse and edit the files inside my agent's workspace?

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. Tick Hidden to reveal dotfiles like .env and .claude/— as the agent's owner or an admin; for anyone else the box is disabled and hidden files are not listed. A lock beside a file means it is read-only for you. Downloads are supported up to 100 MB per file. See Agent Files.

What can someone I shared my agent with do in the Files tab?

A share grants one flat level: the person can chat with the agent, see their own conversations, and browse and edit its files except credentials, runtime config and its instructions. In the Files tab that means they see no hidden files (the Hidden box is disabled), cannot open credential files such as .env or .mcp.json, and cannot change or delete CLAUDE.md, AGENTS.md, GEMINI.md, anything under .claude/ (skills included), or shell and git startup files like .bashrc and .gitconfig. Those nodes carry a lock marked Read-only for you, and the note under a selected file says Only the agent's owner or an admin can change this. Everything else — the agent's working files, data/, memory/, uploads/— they can read, edit, create folders in and delete as before. The Settings › People pane states the same grant in one sentence. See Agent Files.

Why was my file write refused?

Read the code in the 403 response. owner_tier_pathmeans the file is one only the agent's owner or an admin may change (instructions, .claude/, startup files) and you hold a share — ask the owner. Cannot edit protected path or protected_path means nobody can change it through the Files tab, owner included: credentials, runtime login files, .trinity/, .git/, .gitignore and system paths; an agent key also gets protected_path on startup files. resolved_path_mismatchmeans the path goes through a link that changes what it points at, and Trinity does not follow it — open the real file instead. agent_restart_requiredmeans the agent still runs an image from before this rule; stop and start it from Trinity. An agent's own key is additionally refused with skill_management_not_permitted or instruction_management_not_permitted when it writes under .claude/skills/ or to an instruction file without the matching permission. See Agent Files.

How do I get a file into my agent's container, and can I send a ZIP?

Attach it to a message. On the Agent Detail Chattab, images reach the agent as vision content and everything else — plain text, CSV, JSON, and ZIP — is written to /home/developer/uploads/inside the container, readable by name; a ZIP is stored as-is, not extracted (3 files per message, 5 MB each). In the Workspace, files you attach or drop on the conversation land in the agent's inbox and appear under Files you sent in the rail (up to 20 per drop, 25 MB each). For bulk runtime data, use the data import endpoint, which restores a tar archive into data/. See Agent Chat and Agent Data & Portability.

Where can I see my agent's logs?

The Logstab on the Agent Detail page shows the container's stdout/stderr in a fixed-height scrollable panel: Auto-refresh (10s) is a toggle, a line-count selector sets how many lines are fetched, a refresh button fetches on demand, and auto-scroll is smart (new content scrolls to the bottom until you scroll up yourself). The same log is 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.

What is the compatibility report on the Overview tab, and can Trinity fix what it finds?

Once an agent is running, Trinity checks its workspace against a catalogue of best-practice conventions — a valid template.yaml, a non-gitignored .claude/ directory, defined playbooks, accidentally committed secrets, and more — and shows the findings in the Agent Detail Overview tab, ranked HARD / SOFT / INFO. It also reports whether the platform-provided Trinity plugin is present and, if not, why it was withheld. 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 Fix button 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. The headline counts only must-fix findings, and a template with no resources block passes because the agent inherits the fleet-wide default. See Creating Agents.

Is there a limit on how many canvases an agent can hold?

Yes: each agent can hold 100 canvases (CANVAS_MAX_PER_AGENT in .env, default 100), and the Canvas tab shows the count as you approach it. At the limit the agent can still update every canvas it has, but creating a newone is refused with a message telling it to retire one first — nothing is ever deleted automatically to make room. An agent that hits this is usually writing a new canvas per run instead of keeping one per topic current; ask it to reuse a canvas, or clear the finished ones from the Canvas tab on Agent Detail (Delete, or Manage to select several). Deleting the default maincanvas is fine — the agent recreates it the next time it writes. Pinning, deleting and sharing canvases from the Workspace are covered in the Chat & Sessions FAQ. See Agent Canvas.

I already have a GitHub repo — how do I turn it into an agent?

Create an agent from it and pick an import intent. Clone (the default) keeps the agent wired to that remote; it pushes back on its own working branch when the repository is yours, and is pull-only otherwise. 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.

I already run several Claude Code agents on my own machine. How do I move them onto Trinity?

Start with the agent-dev plugin from the abilities marketplace. /agent-dev:agent-fleet-analysis audits a folder of agents (Claude Code or other frameworks), scores how ready each one is and writes a report plus a work order. /agent-dev:agent-fleet-migrate then carries out that work order into a separate fleet-migrated/ folder and leaves your original sources untouched. To deploy each agent, push it to a GitHub repository and run /trinity:onboard in its folder. Trinity creates the agent from that repository, so the same repo can still be run locally with Claude Code, and changes move between the two through git and /trinity:sync. See agent-dev plugin and the Advanced Features FAQ.

Why was my new agent created pull-only instead of getting its own working branch?

An agent gets a working branch, auto-sync, and paused schedules while sync fails only when the repository is yours: not a shared catalog template, owned by the GitHub account your token belongs to, reached with your own token rather than the platform-wide one, and a push check passes. An organization's repository stays pull-only by default, even when your token can write to it. The create response's git_mode.reasonnames which condition failed and how to fix it — usually "add your own GitHub token" or "fork it to your own repository". A kind: "deployment" create, including trinity deploy --repo, is always pull-only. See GitHub Sync.

How do I turn my agent's auto-sync on or off?

Open Settings › Storage and use the Sync rows under Repository: Auto-sync to GitHub every 15 minutes, Pull changes from GitHub on every sync cycle, and Pause schedules while sync is failing. All three apply on the next cycle with no restart. The same switches are PUT /api/agents/{name}/git/auto-sync, PUT /api/agents/{name}/git/pull-sync and PUT /api/agents/{name}/git/freeze-schedules-if-failing. An agent with no repository shows Not connected to a repository instead, and the switches are absent. See GitHub Sync.

My agent was created from a public template and can't push anywhere. Can I fix that without recreating it?

Yes — use Bind to your own repounder the agent's Settings › Storage › Repository. 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.

Why did a Push untrack some of my agent's files, and where do I see what changed?

Before every push Trinity rebuilds the agent's .gitignorearound its own rules — managed defaults (caches, virtualenvs, local databases, generated content) above your rules, and a non-overridable protected floor (credential files, the agent's .trinity/state) below them — and then untracks anything the rules now cover. Because git is last-match-wins, a !negation you wrote keeps winning over the defaults, so a file you chose to keep is never silently dropped; the one exception is a negation beneath a directory-form pattern such as node_modules/, which git never descends into — those are reported as shadowed rather than fixed. The push then tells you what it did: the sync response and the git_sync MCP result carry removed_paths, unignored_paths, and shadowed_negations, the Git tab's toast and the commit message state the counts and paths, and when the tracked set actually changed Trinity also files an operator-queue notice, so an unattended scheduled sync can't untrack files for weeks unnoticed. A newly un-ignored path that was a secret is already in the remote's history — rotate it and remove the rule. See GitHub Sync.

Does my agent's .claude/settings.json get committed to its repository?

Yes, normally. It is not gitignored, so a template's project settings and the hooks a plugin registers travel with the repository. Trinity checks the content on every commit it makes and keeps the file out when the staged copy registers hooks under /opt/trinity/, carries a credential-bearing key such as env or apiKeyHelper, or is not valid JSON. It then keeps the last committed copy (or untracks the file when there is no usable one) and never touches the copy on the agent's disk. See GitHub Sync.

Why does my agent's .gitignore contain rules I never wrote, right after creation?

Because Trinity merges its canonical .gitignoreinto every auto-syncing GitHub agent immediately after creation, before the first sync cycle can commit runtime state or credential files — the same rules the bundled templates already ship with, so an agent created from any GitHub repository never auto-commits caches, virtualenvs, local databases, or its .env back to your repo. Your own rules stay in place beneath the managed defaults, and a !negation you write keeps winning (see the push question above for how the rules are ordered). Declaring data_paths in template.yaml appends those globs to the same file. See Creating Agents and Agent Data & Portability.

Can my agent disable or edit its own guardrails?

No. The hook scripts live in root-owned /opt/trinity/, and the registration that makes Claude Code run them lives in its admin-controlled managed settings (/etc/claude-code/managed-settings.json) — root-owned, read-only, taking precedence over user and project settings, and outside the git-synced working tree — so neither an edit inside the container nor a push to the agent's repository can remove it. The credential-file protection hook refuses writes to those paths as well, and the Bash deny-list refuses the obvious sudo commands against them. Each hook runs as a fixed command with an empty environment under an isolated interpreter, so a shell prefix or startup file the agent sets cannot run ahead of it. On every boot the container checks that the registration is present and unwritable and logs GUARDRAILS: ERRORif not, and the agent's /health re-checks the registration on every request. Owners can tighten guardrails per agent (turn limits in the Settings tab; deny lists and disallowed tools via the API) but never loosen the baseline. See Agent Guardrails.

Where do I see which credentials an agent still needs?

The Settings › Credentialspane 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.

Where does the list of GitHub templates come from?

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.

What does "What is this repository?" mean when I create an agent from my own repo?

It tells Trinity how to bind the agent to git. An agent means the repository isthe agent — its memory, skills and state — so it saves its work to its own branch. A deployment of a codebase means the repository is a product the agent runs, so it only pulls updates and never pushes. The question appears only for a custom repository with the Cloneintent; list templates are always pull-only, and copy, fork and fork-to-own don't need it. After creation the dialog shows what Trinity decided and warns plainly when an agent was created pull-only, and the Git tab shows Agent · own branch, Agent · own repo, or Pull-only. See Creating Agents.

I asked for 8 CPUs but the server only has 4 — will my agent fail to start?

No. Docker refuses a CPU limit above the host's CPU count, so Trinity caps the request at the number of CPUs the host has and logs a warning. The agent's setting keeps the value you chose, so the agent is not recreated on every start. See Agent Configuration.

Does a Gemini agent remember earlier turns?

In chat, yes: each chat turn resumes the agent's own Gemini session, never another run's, and a model change or a history reset starts fresh. Headless turns — tasks, schedules, and Workspace turns — never resume a Gemini session, so they run without the previous turn's working memory. If you need a conversation that carries working memory forward in the Workspace, use a Claude Code agent. See Agent Runtimes.

Why did my agent's chat reply show up as a failure even though it wrote some text?

Because the Claude Code CLI reported that the turn ended in an error. Trinity records such a turn as failed, with the real cause, rather than presenting partial text or an error message as the agent's answer. The one exception is when the session transcript on disk proves the turn actually finished; then the answer is kept and marked as recovered. See Agent Runtimes.

Do guardrails and read-only mode protect agents on every runtime?

Not equally. The guardrail hooks and read-only mode are Claude Code tool hooks. Codex enforces read-only mode through its own sandbox, and Gemini CLI turns pass through neither. Credential redaction applies to every runtime, because the backend scrubs execution output whatever produced it. The turn limit is enforced only on Claude Code; on Gemini and Codex the execution timeout bounds the run. See Agent Guardrails.

Why did the Canvas tab jump to a different canvas while I was reading?

Because the agent created a new canvas, and the panel follows a newly created canvas so you see what was just made. It waits while you are in Manage, searching, or sharing, and picking a canvas yourself in the meantime cancels the switch. A rewrite of a canvas that already exists never moves you. See Agent Canvas.

How do I give every agent on my instance the same rules?

Write them in the Trinity Prompt(Settings → General, admin only). Trinity adds it after the platform instructions on every chat and task turn, for every agent and every runtime, so a saved change reaches running agents from their next turn with no restart. Add fleet rules only, keep it short, and never copy the platform's own instructions into it. A system manifest with a top-level prompt: replaces it. See Recommended Trinity Prompt.

Where should my fleet's shared knowledge, the "company brain", live?

In git, in layers. Each agent's own instructions, skills and memory stay in its own repository. Rules that every agent must follow go in the Trinity Prompt. Knowledge that several agents read and cite (protocols, facts, cross-agent policies) fits a shared canon repository, which /agent-dev:add-canonsets up: each agent publishes to its own folder and reads the others' folders at a pinned version, with a lint pass that keeps the shared facts consistent. A second-brain agent such as Cornelius, which a fresh install seeds, is a separate layer: an agent you talk to that builds up a knowledge base. For handing files between running agents, use shared folders. See agent-dev plugin → Fleet-scale skills and Agent Network → Shared Folder Configuration.

Should every agent get its own email address and accounts?

It doesn't have to, and usually shouldn't. Trinity has no built-in email channel, so an agent reaches a mailbox through credentials and an MCP server you give it, one agent at a time. A simpler pattern is one entry-point agent that owns the outside mailbox and hands work to the others. Mail from outside is untrusted input, so have that agent sort and filter messages before passing their content on, and give it no more tools than it needs. Your own team doesn't need email to reach agents: they work with them in the Workspace. See Agent Network and Workspace.

My agent started a background task on itself and heard nothing back. Should it send the task again?

No. The execution_id it got back is a receipt: the task arrived and is queued, running or done. Re-sending, especially a reworded version, can run the work twice. Read the outcome with get_execution_result(agent_name, execution_id) — runningdoes not mean stuck — or turn on result injection so the answer lands in the chat when it finishes. See Self-Execute.