Frequently Asked Questions
334 grounded answers to the questions users actually ask, organized into 14topics. Each answer links to the full documentation page. Use your browser's find (Ctrl/Cmd+F) on this page to search all questions.
Getting Started
What Trinity is, installing, first login, whitelist, templates
17 questions
Agents
Creating agents, templates, import intents, runtimes, lifecycle, config, files, logs
28 questions
Chat & Sessions
Chat tab, Workspace conversations, context windows, history, costs, background work, models
18 questions
Credentials & Subscriptions
Credential files & declarations, setup checklist, encryption, OAuth, subscriptions, PATs
23 questions
Scheduling & Automation
Cron schedules, webhooks, loops, self-reminders, fan-out, multi-source skills library
36 questions
Agent Collaboration
Agent-to-agent permissions, events, task-completion report-back, shared folders, systems, rooms
20 questions
Channels & Messaging
Slack, Telegram, WhatsApp, public links, progress indicators, proactive consent, voice, phone calls
28 questions
MCP & API
MCP server, API keys, inline email auth, agent keys, REST auth, idempotency, CLI
21 questions
Operations & Monitoring
Dashboard views, org overlay, reports, health, executions, approvals, costs, retention
29 questions
Sharing, Access & Monetization
Sharing, roles, access requests, quotas, paid agents
22 questions
Deployment & Upgrades
Sizing, ports, upgrading, base images, backups, retention, PostgreSQL, public exposure
28 questions
Security
Isolation, credential protection, principal gates, supply chain, audit log, hardening
24 questions
Advanced Features
Voice, images, avatars, dashboards, GitHub sync & repo binding, pipelines, abilities
20 questions
Troubleshooting
Symptom → cause → fix for the most common problems
20 questions
All questions
Getting Started
- •What is Trinity?
- •What do I need to run Trinity on my own machine?
- •How do I install Trinity?
- •Can I use Trinity without hosting it myself?
- •What happens the first time I open Trinity in my browser?
- •How do I log in to Trinity?
- •What is the email whitelist?
- •Why can't my teammate log in with their email?
- •Why didn't I receive my 6-digit login code?
- •Why does nothing load when I open http://localhost?
- •Where do I find the web UI, the API, and the interactive API docs?
- •How do I create my first agent?
- •What is the Cornelius agent that appeared on my fresh install?
- •What is a template?
- •Is Trinity free to use?
- •Are some features only available in an enterprise edition?
- •Where can I get help if I'm stuck?
Agents
- •What are the different ways to create an agent?
- •Can I create an agent from a private GitHub repository or a specific branch?
- •Can I create an agent from a public GitHub repository without a token?
- •Do I need to write my own template to create an agent?
- •What goes in template.yaml?
- •How do I make sure my agent's Claude Code plugins survive a rebuild or a move?
- •Why did creating my agent fail with an error about the base image?
- •What's the difference between the Claude Code, Codex, and Gemini runtimes?
- •How do I start and stop an agent?
- •What survives an agent restart, and what survives a recreate?
- •What happens when I delete an agent — is everything gone immediately?
- •Can I create a short-lived, disposable agent that cleans itself up?
- •What happens when I rename an agent?
- •How do I change an agent's friendly display name without renaming it?
- •What's the difference between renaming an agent and giving it a display label?
- •How do I limit how much CPU and memory an agent can use?
- •How long can an agent task run before it times out?
- •What does read-only mode do?
- •What does the autonomy toggle actually control?
- •How do I move an agent to another Trinity instance?
- •Can I get shell access to my agent's container?
- •How do I browse and edit the files inside my agent's workspace?
- •Where can I see my agent's logs?
- •What is the compatibility report on the Overview tab, and can Trinity fix what it finds?
- •I already have a GitHub repo — how do I turn it into an agent?
- •My agent was created from a public template and can't push anywhere. Can I fix that without recreating it?
- •Where do I see which credentials an agent still needs?
- •Where does the list of GitHub templates come from?
Chat & Sessions
- •How do I start chatting with an agent?
- •What's the difference between the Workspace and the Chat tab?
- •What does the agent actually remember between turns in the Workspace?
- •Why doesn't my agent seem to remember anything between turns?
- •Why does a long conversation suddenly take much longer on one turn?
- •Is the context window always 200K tokens?
- •How do I make the agent forget the conversation and start fresh?
- •Who can see my chat history?
- •Where can I see what a chat message cost?
- •Can several chats run on the same agent at once?
- •Why am I told the conversation is already handling a message?
- •How do I stop a turn that's stuck or running too long?
- •Can the agent keep working on something in the background while I chat?
- •What happens if I close my browser while the agent is still working?
- •Can I pick a different model for a chat?
- •What are the Fable 5 and Sonnet 5 models?
- •Does chat render markdown, and can I attach files?
- •Can I talk to my agent with voice?
Credentials & Subscriptions
- •How do credentials work inside a Trinity agent?
- •How do I add or edit credentials on an agent?
- •Can I change credentials on a running agent without restarting it?
- •What is the .credentials.enc file, and is it safe to commit to git?
- •Do I need to re-enter credentials every time an agent restarts?
- •What kinds of credential files can I inject into an agent?
- •Why does Trinity reject some files when I try to inject them?
- •Can I inject binary credentials like certificates or keystores?
- •Can I connect an agent to Google, Slack, GitHub, or Notion without pasting API keys?
- •What are subscription credentials?
- •Do I have to assign a subscription to every new agent manually?
- •What happens when my agent hits a rate limit on its Claude subscription?
- •If I rotate a subscription token, will it interrupt agents mid-task?
- •Should I use a per-agent GitHub PAT or the platform-wide one?
- •Can I use my own GitHub token instead of the platform-wide one?
- •Do I need a GitHub token to build an agent from a public repo?
- •Are my credentials ever stored in Trinity's database?
- •How do I rotate the platform encryption key?
- •Why is the Register Subscription button disabled in Settings?
- •How do I move an agent's credentials to another Trinity instance?
- •How do I know which credentials an agent actually needs?
- •How does a template declare the credentials it needs?
- •I rotated the platform GitHub token — do I need to restart my agents?
Scheduling & Automation
- •How do I schedule a recurring task for an agent?
- •Can I set a timezone for my schedule?
- •Why didn't my schedule fire even though it's enabled?
- •What's the difference between disabling a schedule and turning off autonomy?
- •Can I run a schedule right now without waiting for the next cron tick?
- •What happens when a schedule fires while the agent is already busy?
- •How long can a scheduled task run before it times out?
- •Do failed scheduled runs retry automatically?
- •What happens to the execution history if I delete a schedule?
- •Can my agent skip a scheduled run when there's nothing to do?
- •Can an agent schedule itself to run again later?
- •How is an agent self-reminder different from a cron schedule?
- •How do I see or cancel the reminders an agent set for itself?
- •How do I trigger a schedule from an external system like CI/CD?
- •What should I do if my webhook URL leaks?
- •Why are my webhook calls getting rejected with 429?
- •What is an agent loop and when should I use one instead of a schedule?
- •Can each loop iteration see the previous iteration's result?
- •How do I keep a loop from running forever or burning my budget?
- •What happens to a loop when one iteration fails — does it stop or keep going?
- •How do I run many tasks in parallel on one agent?
- •What are skills and playbooks, and how do I run one?
- •How do I find out which agents already have a given skill?
- •Can I assign a skill from the Library page?
- •Can a skill be a whole folder of files instead of a single markdown file?
- •How do I assign skills to an agent, and do I need to restart it?
- •How can I see whether a schedule is actually performing well?
- •Can the skills library sync from more than one repository?
- •Where do skills have to live inside a source repository?
- •Will a skills-library update reach my running agents automatically?
- •What happens when I unassign a skill — do the files stay on the agent?
- •Why is the community skills source pinned to a tag instead of tracking a branch?
- •My template declares schedules — will Trinity create them?
- •What should a schedule's message contain?
- •My scheduled skill hangs every run and burns its whole timeout — why?
- •Can I use a legacy timezone name like `US/Eastern` in a schedule?
Agent Collaboration
- •How do agents talk to each other in Trinity?
- •Why can't my agent call another agent?
- •How do I let one agent call another?
- •What does granting permission actually let an agent do?
- •Can one agent hand off a long-running task to another without waiting?
- •How do I share files between two agents?
- •Why doesn't the shared folder show up in my consuming agent?
- •How do event subscriptions between agents work?
- •Why isn't my agent receiving events it subscribed to?
- •Can an agent be notified the moment another agent's task finishes, instead of polling?
- •Can a worker agent report back to its caller automatically when it's done or fails?
- •Can several of my agents hold a conversation together in one shared session?
- •How can I watch agents collaborating on the Dashboard?
- •Can I deploy a whole team of agents in one step?
- •How do I restart all agents in a system at once?
- •Can external orchestrators discover and call my Trinity agents?
- •Can my agents call an external A2A agent?
- •An outbound A2A call timed out — should I just try again?
- •Can my agent message me proactively instead of waiting for me to ask?
- •What's the difference between an agent loop and agent collaboration?
Channels & Messaging
- •How do I connect my Trinity instance to Slack?
- •What is the difference between Socket Mode and webhook mode for Slack?
- •Can multiple agents share one Slack workspace?
- •Can each agent have its own Slack bot identity instead of sharing one?
- •Can I control whether an agent posts to a Slack channel on its own?
- •Which agent answers when someone DMs the Slack bot?
- •Why does my agent keep replying in a Slack thread without being @mentioned?
- •How does my agent show its own name and avatar in Slack?
- •How do I connect an agent to Telegram?
- •Why doesn't my Telegram bot see every message in a group?
- •Can users send voice messages to my Telegram bot?
- •How do I connect an agent to WhatsApp?
- •Should I use the Twilio sandbox or a production WhatsApp sender?
- •Can my agent join WhatsApp group chats?
- •How do users verify their email from Telegram or WhatsApp?
- •How do I let people chat with my agent without a Trinity account?
- •Does a public chat link remember returning users?
- •Can I use a different model for public and channel conversations?
- •Can I give my agent extra instructions that only apply to strangers?
- •Can my agent speak its replies as voice notes?
- •Why did my agent's voice reply arrive as plain text?
- •Can my agent place real phone calls?
- •What limits apply to agent phone calls, and what happens after a call?
- •How does Trinity know who is messaging my agent from a channel?
- •Can I change how many proactive messages my agent can send?
- •Does Telegram show anything while a long task is running?
- •An agent delegated my Telegram request to another agent — will I hear back?
- •A file someone sent my agent in Slack never arrived. Why?
MCP & API
- •What is the Trinity MCP server?
- •How do I create an MCP API key?
- •What is the difference between user, agent, and system key scopes?
- •How do I connect Claude Code to Trinity?
- •How many MCP tools are there, and what can they do?
- •Can I expose one of my agents as its own MCP tool?
- •Why can't my agent call another agent over MCP?
- •How do I revoke an MCP API key?
- •How do I authenticate against the REST API?
- •Can I use an MCP key instead of a JWT on the REST API?
- •Why did my API calls start returning 401 after I restarted Trinity?
- •What is the Idempotency-Key header for?
- •What happens when a chat call from an MCP client takes too long?
- •How do I run a long task via the API and check its result later?
- •Is there a command-line tool for Trinity?
- •Where can I browse the full REST API?
- •Why doesn't my MCP client see Trinity's tools after a backend restart?
- •Can I connect an MCP client to Trinity without creating an API key first?
- •What is the MCP key panel on an agent's Settings tab for?
- •Why does my automation get a 403 on an endpoint my account is admin on?
- •Can I ask Trinity questions about Trinity from my MCP client?
Operations & Monitoring
- •How do I see what all my agents are doing at once?
- •What's the difference between the Timeline, Grid, and List dashboard views?
- •Where did the Agents page go?
- •Can I put fleet-level readouts on the Dashboard Grid?
- •Why doesn't the Recent failures tile just say zero when there are no failures?
- •Can I show my fleet as an org chart?
- •How do I see structured results an agent produced, without reading its chat?
- •Does a green "completion" number mean the work was good?
- •What is the Operations page and what do its tabs show?
- •What does the badge on the Operations entry in the navigation bar mean?
- •How do I turn on fleet health monitoring?
- •Why is my agent shown as unhealthy?
- •Why is my new GitHub-template agent unhealthy even though its container is running?
- •What does an alert about missed agent heartbeats mean?
- •How do agents ask me questions or request approval before doing something risky?
- •Can I clear or cancel a pile of pending operator-queue items at once?
- •How do I see notifications my agents send me?
- •How do I see every task my agents have run?
- •Can I watch a running execution live?
- •How do I stop an execution that's running too long?
- •How does Trinity track what my agents cost?
- •Can I set a daily spending limit or get cost alerts?
- •What does the "circuit open" badge on my agent mean?
- •How do I turn the circuit breaker on for an agent, or reset one that's open?
- •What are agent reports and where do I find them?
- •What does the Overview tab on an agent's page show?
- •Where can I see the CPU, memory, and disk usage of the host machine?
- •Will Trinity ever automatically delete my execution history, logs, or deleted agents?
- •Why was a data cleanup blocked until I approved it?
Sharing, Access & Monetization
- •How do I share an agent with a teammate?
- •What can my teammate do with an agent I've shared with them?
- •Why can't my teammate see my past conversations with a shared agent?
- •What's the difference between the Access tab and the Sharing tab?
- •What user roles does Trinity have and what can each one do?
- •Who can create agents?
- •Why am I getting an agent quota error when I create an agent?
- •What role does a new user get the first time they log in?
- •Can people sign up for my Trinity instance on their own?
- •How does someone request access to my agent, and what happens when I approve it?
- •What's the difference between Restricted and Open access on an agent?
- •What's the difference between sharing an agent and creating a public link?
- •What is the Workspace?
- •How do I bring a second agent into a conversation?
- •What can a client see on an agent's page?
- •What's the difference between a public link, sharing, and the Workspace?
- •How do I keep a growing fleet of agents organized?
- •Can I manage Trinity from my phone?
- •Can I charge people to chat with my agent?
- •How do I set the price for my paid agent, and can I test payments without real money?
- •How can I see the payments my agent has received?
- •How does my agent share a file with someone outside Trinity, and how do I revoke the link?
Deployment & Upgrades
- •What hardware and operating system do I need to run Trinity?
- •How many agents can I run on one machine?
- •Should I deploy Trinity locally, on a single server, or with public access?
- •Can I run Trinity on a cheap VPS?
- •What ports does Trinity use?
- •How do I change the port the web UI runs on?
- •Which environment variables do I have to set myself, and which does start.sh generate?
- •Can I have an AI agent install Trinity for me, or run a no-prompt install?
- •What happens if I lose or change my credential encryption key?
- •How do I upgrade Trinity safely?
- •Why should I use docker compose restart instead of down and up?
- •Why can't I start any agents after running docker compose down?
- •When do I need to rebuild the agent base image?
- •How do I back up my Trinity instance?
- •How often should I back up, and how long should I keep backups?
- •How do I restore from a backup?
- •Where does Trinity actually store my data?
- •How long does Trinity keep my data, and is there a minimum I can't accidentally drop below?
- •Should I use SQLite or PostgreSQL?
- •How do I expose Trinity to the internet for webhooks and public chat links?
- •Does the whole platform need to be exposed publicly?
- •What is the Trinity Ops Agent, and when should I use it instead of raw Docker commands?
- •How do I verify my deployment is healthy after an upgrade or restart?
- •Why is Docker using so much CPU when I run Trinity locally on Docker Desktop?
- •Why do I have to log in again after restarting the backend?
- •After rebuilding the base image, how do agents pick it up?
- •How do I confirm the running deployment is actually the build I just shipped?
- •Can a container log fill my disk?
Security
- •Can agents see each other's files?
- •Can an agent reach the platform database or Redis?
- •Do Trinity containers run as root?
- •Are my credentials stored in Trinity's database?
- •Can my API keys leak into logs?
- •Is it safe to commit the `.credentials.enc` file to git?
- •What is recorded in the audit log?
- •Can audit log entries be edited or deleted?
- •How long does my login session last?
- •Why doesn't Trinity put my login token in WebSocket URLs?
- •What do guardrails actually block?
- •What is read-only mode?
- •Is it safe to expose a fresh Trinity install to the internet before setup?
- •Is a webhook URL secure enough on its own?
- •How do agents and the backend authenticate to each other?
- •Does Trinity phone home?
- •What does Trinity record about my usage, and does any of it leave my server?
- •How do I turn usage-data sharing on or off?
- •What should I do before exposing Trinity to the internet?
- •Who controls which users can access an agent?
- •An admin API key can do anything an admin can — is that a problem?
- •How do I know my agent is authenticating to Trinity as itself?
- •Can a skills repository push executable code to my whole fleet without me noticing?
- •Is anything stopping a retention setting from wiping my history?
Advanced Features
- •Can I talk to my agent by voice in the browser?
- •Why don't I see the microphone button in my agent's chat?
- •Can I change my agent's voice or how it speaks?
- •What is Workspace Mode?
- •Can Trinity generate images?
- •How do agent avatars work?
- •Why did my agent's avatar generation fail?
- •Can my agent build its own dashboard?
- •What's the difference between Source mode and Working Branch mode in GitHub sync?
- •Does my agent push its changes to GitHub automatically?
- •What is a fork-to-own template?
- •What is the A2A agent card?
- •Can my agent run a long multi-stage pipeline, and can I watch its progress?
- •What are agent reports?
- •What is the abilities plugin marketplace?
- •How do I deploy an agent I built with Claude Code to Trinity?
- •I created an agent straight from a bare GitHub repo — how do I make it Trinity-compatible?
- •How do I keep a deployed agent's schedules and plugins in sync with its template.yaml?
- •What files does my own agent template need?
- •What is the Brain Orb?
Troubleshooting
- •Why did everything log me out all of a sudden?
- •My new agent shows as unhealthy right after I created it
- •My agent won't start
- •The Workspace says the conversation is already handling a message
- •My scheduled task didn't run
- •An execution has been stuck in "queued" for a long time
- •My execution failed with a timeout
- •The git sync indicator is red / sync keeps failing
- •My webhook suddenly returns 404 or 401
- •Credentials I updated aren't taking effect
- •My agent's context is at 90%+ / it hit the context limit
- •I'm getting rate-limit or auth errors from Claude mid-run
- •Docker Desktop pegs my CPU and my fans won't stop
- •I see "database is locked" errors in the backend logs
- •Port 80 or 8000 is already in use when I start Trinity
- •Where do I find the logs for X?
- •My disk keeps filling up
- •My loop stopped before finishing all its runs
- •My agent can't reach another agent
- •I deleted an agent by accident