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

Security

Isolation, credential protection, admin gates and key scopes, guardrails, telemetry, audit log, hardening. Short, grounded answers with links to the full documentation.

54 questions

Can agents see each other's files?

No. Each agent runs in its own Docker container with its own workspace volume — there is no shared filesystem between agents by default. If you want two agents to exchange files, that is an explicit opt-in: an agent can expose a shared folder, and only agents you have granted permission to can mount it. Everything else in one agent's workspace, including its credentials, stays invisible to every other agent. See Agent Files.

Can someone I share an agent with read its .env or other credential files?

No. Credential files — .env, .mcp.json, key and certificate files, SSH and cloud credentials, the runtimes' login files — open, preview and download only for the agent's owner or an admin. Someone you share the agent with can still chat with it and run its tasks, and the agent keeps using its credentials for them; opening one of those files shows a message telling them to ask the owner or an admin. Agent, system and connector keys cannot read them either, and every refused read is recorded in the audit log. See Agent Files → Reading credential files.

Can someone I share an agent with get it to do what they can't do themselves?

No. An agent acts for whoever is chatting with it, and Trinity holds it to that person's limits for their turn, decided from the execution record. For a person the agent is shared with, the agent's file tools reach only the paths that person could open in the Files tab, it gets no shell, it cannot set up schedules, loops or reminders for them or create agents, and its key reads only their executions. Gemini CLI and Codex agents cannot enforce this inside the run, so they refuse a shared person's message outright. Channel and public-link visitors get the shell only while the owner's Channel and public visitors may run commands switch is on. See Agent Sharing.

Can an agent reach the platform database or Redis?

No — this is enforced at the network level, not by policy. Trinity runs two separate Docker networks: agents live on the agent network (172.28.0.0/16) while Redis, the scheduler, and the log aggregator live on the platform network (172.29.0.0/16). Agents have no route to the platform network, so they physically cannot connect to Redis or other internal services. Only the backend and MCP server bridge both networks, and every call through them is authenticated and access-checked.

Do Trinity containers run as root?

No. The backend, scheduler, and MCP server run as unprivileged UID 1000, the frontend as UID 101, and every agent as the non-root developer user. Agent containers additionally drop all Linux capabilities except network binding, run with no-new-privileges, and get a non-executable temporary filesystem. This limits what any compromised process can do to its own container.

Are my credentials stored in Trinity's database?

Never as plaintext. Agent credentials are injected as files (.env, .mcp.json, and other allow-listed credential files) directly into the agent's container and never land in the database at all. What the database does hold is always wrapped in AES-256-GCM encryption: channel bot tokens (Slack, Telegram, WhatsApp), shared subscription tokens, GitHub PATs, vault entries, and the platform's own credentials — the Anthropic API key, the platform GitHub PAT, the email-provider (Resend) key, the Gemini key, and the Slack app token, client secret, and signing secret — which are stored under <key>_encrypted names. The generic settings route refuses to store a secret in the clear (PUT /api/settings/{key} answers 422 for any credential-shaped key), and an install upgraded from an older release re-encrypts a leftover cleartext row on first read. Because backups taken before that upgrade still hold plaintext, rotate those platform tokens after upgrading. See Credential Management.

Is it safe to paste my Claude, GitHub, or Gemini key into the browser instead of .env?

Yes — that is the intended path. The platform keys (Claude, GitHub, the Resend email-provider key, and Gemini) are entered in first-run setup or under Settings → Integrations → API Keys, checked with their provider beforethey are saved, and stored encrypted with AES-256-GCM in the platform database — never in plain text. A key saved in Settings takes precedence over the same key in the server's .env and takes effect without a restart; .envis only the fallback when nothing is saved. The admin-only status endpoints never return a key — only whether one is set, where it comes from (settings or env), and its last four characters — and Remove reverts to the .env value, if any. See Platform Keys.

Can my API keys leak into logs?

Credential values are never logged — all credential operations use structured logging with values masked. On top of that, a guardrail hook scans agent command output for known credential patterns (API keys, GitHub tokens, cloud access keys) and records only the pattern name when it finds a match, never the value itself, so you can review potential leaks without the log becoming one. A value an agent fetches from the Credential Vault is additionally scrubbed out of everything Trinity persists from that turn — transcript, execution log, response, notifications — and replaced with ***REDACTED***. See Agent Guardrails.

Is the GitHub token stored in my agent's git remote?

No. An agent's git remotes carry no credential: git asks Trinity's credential helper for the token on each fetch or push, over standard input, so the token is not written into .git/configand does not appear in the container's process list or logs. Existing agents are converted automatically after an upgrade, and a token is removed from a URL only once a replacement resolves. This does not hide the token from the agent itself — GITHUB_PAT stays in its .env and environment so git and gh keep working. To limit what one agent can reach, give it its own repo-scoped token on its Git tab. See GitHub PAT Setup → How Git Gets the Token.

Should I rotate the platform GitHub token after upgrading?

Yes. Taking the token out of agent remotes protects your install from the upgrade onward, but backups, log archives, and container logs taken before the upgrade can still contain it. Mint a replacement, save it under Settings → Integrations, confirm a fetch works on a couple of agents, then revoke the old token on GitHub; the new token reaches running agents without a restart. Rotation is mandatory if the cleanup reports a token in a committed .gitmodulesfile, since that token is already in the repository's history; the operator runbook, Git remote token scrub, has the verification commands. See Upgrading.

Is it safe to commit the .credentials.enc file to git?

Yes — that is what it exists for. It is an AES-256-GCM encrypted archive of the agent's full credential set, safe to store in version control as an encrypted backup. The platform restores a committed archive when the agent starts (not for an ephemeral agent, and not on an install with no encryption key), and the owner can restore it at once, signed in, with Import from Git under the agent's Settings › Credentials. The encryption key lives only in your platform's environment, and it can be rotated online without downtime or data loss. See Credential Management.

What is recorded in the audit log?

Administrative and security-relevant actions across the platform: agent lifecycle (create, start, stop, delete, rename, recover), logins and logouts, permission grants, uses and denials, settings changes, credential inject/export/import, git operations, and every MCP tool call. Each entry records who acted (user, agent, MCP client, or system), what was affected, when, and where the request originated. When the call was authenticated with an MCP API key, the entry also names the key — its id, name, and scope — beside the accountable owner, so “what did that leaked key touch?” is answered by filtering the list on the key id; a browser session records no key fields. Admins can search, filter, and export it from the dashboard. See Audit Trail.

Does a refused MCP tool call show up in the audit log?

Yes, and it is labelled as a refusal. When a tool turns a call away — for example an agent calling chat_with_agent, fan_out, or run_agent_loopon an agent it has no permission for — the caller gets an Access denied result, and the mcp_operation entry records success: false, denied: true, and the reason. A backend 403 that surfaces through a tool is marked denied too. Other errors carry no deniedflag, so a refused call is never mistaken for a permitted one or for a broken one. Where the caller only sees a generic "not found or not accessible", the admin-only entry keeps the specific reason. See Audit Trail → Refused MCP Calls.

Can audit log entries be edited or deleted?

No. The audit log is append-only at the database level: entries can never be modified, and a database trigger refuses deletion of any entry younger than the 365-day retention floor. You can also enable an optional SHA-256 hash chain, where each entry stores a hash linked to the previous one — the verify endpoint walks the chain and reports the first broken link, proving the log wasn't tampered with between two checkpoints. See Audit Trail.

How long does my login session last?

Login tokens (JWTs) are valid for 7 days, and all tokens are invalidated whenever the backend restarts, so you re-login after an upgrade. When a session ends while you are on a page, Trinity sends you to the login page and, once you sign in, back to that page. Logging out revokes your token immediately on the server side — a stolen token dies with your session instead of living out its remaining days. MCP API keys don't expire on restart; you revoke them explicitly from key management. See Authentication.

Does changing my password sign me out everywhere?

It signs out every other session of your account: a login token issued before the change is refused everywhere, and their open event streams and terminals close. The browser you changed it from stays signed in with a fresh token. MCP API keys are not sessions, so they keep working unless you tick Also revoke the MCP API keys I created in Settings → General → Password; the panel tells you how many still work. Your agents' own keys are never affected. See Authentication → Changing your password.

Why does my login script get a 403 even though the password is right?

Because the account requires a second factor, and a correct password alone does not complete the login. POST /api/token answers 403 with mfa_required and a short-lived challenge_token — there is no access_token and no session was issued; only completing the second-factor step returns the real token. A 401 means the credentials were rejected; 200 means a session was issued. Two-factor authentication (which requires an entitlement) can start applying the moment an administrator enables the role policy, before anyone has enrolled, so an unattended credential can begin receiving 403s without its own configuration changing. Scripts should check both the status code and the presence of the token, never echo the challenge body into logs, and for automation prefer an MCP API key (trinity_mcp_*), which is not subject to the second-factor flow. See Authentication.

Why doesn't Trinity put my login token in WebSocket URLs?

URLs end up in places you don't control — reverse-proxy logs, browser history, and intermediate systems — so a long-lived token in a URL is a leak waiting to happen. Instead, the UI first requests a single-use ticket over a normal authenticated call, then opens the WebSocket with that ticket. The ticket expires in about 30 seconds and is consumed on first use, so even if one is captured it is worthless moments later. See Authentication.

Can a user receive WebSocket events for agents they can't access?

No. The browser's /wsconnection is scoped to the agents its ticket's user can access: an event that names agents is delivered only when every agent it names is one that user may access, and both live delivery and the reconnect replay are filtered — admins see everything. An unknown or suspended account is closed with code 4001. The MCP-key endpoint /ws/eventsis scoped the same way to the key owner's agents, and only user, agent (non-ephemeral agents), and system keys may open it; ops, ops_write, connector, and portal_delegate keys are closed with code 4003. See Authentication.

If I change someone's role or suspend them, do their open connections keep the old access?

No. Open event streams and terminals follow the account. A role change, a password change or a revoked key closes the affected connections at once, and every worker re-checks its open connections about every 15 seconds, so a suspension or an email change reaches them within that time. The browser reconnects at the new scope on its own; a terminal says Your access changed. Open the terminal again to continue. and ends its shell session in the container. Revoking an MCP key closes only the event streams opened with that key. See Authentication → WebSocket Authentication.

Can a user read the event history of agents they can't access?

No. GET /api/events returns only events whose source agent is one you can access, the same set the live event streams use. The filter runs before the result limit, so a page is never padded or emptied by events you cannot see. Asking for one agent you cannot access returns a 403 that looks the same whether or not that agent exists. Admins see every event. See Event Subscriptions.

What do guardrails actually block?

Guardrails are deterministic hooks inside the agent's container that catch accidents. They are not the security boundary: the agent user has passwordless sudo in its own container, so a determined agent could get around them, and the limits that hold sit outside the container (the credentials the agent holds, the platform calls its key may make, the settings only a person can change). They block dangerous shell commands against a deny-list (recursive deletion of root or home, world-writable permissions, piping remote scripts to a shell, force pushes, filesystem formatting, writing to a raw block device with dd of=/dev/sd*, killing the init process with kill -9 1, fork bombs, host shutdown, sudo commands against the guardrail files or sudoers, root shells), block writes to credential files and hook configuration, scan output for leaked credentials, and cap the number of turns per execution to stop runaway loops — 200 turns by default for both chat and task/headless runs, adjustable per agent between 1 and 500. If a guardrail hook itself errors, the tool call is blocked — the system fails closed. Owners can tighten the baseline per agent but never loosen it. See Agent Guardrails, and How Trinity Keeps Agents in Bounds for the wider approach.

Can an agent — or a git push to its repository — remove its own guardrail hooks?

Not by accident, but a determined agent could. The hooks are there to catch accidents. They are not the security boundary. The agent user has passwordless sudo in its own container, so an agent that sets out to get around its hooks can. What holds is outside the container: the credentials the agent was given, the platform calls its key may make, and the settings only a person can change. See How Trinity Keeps Agents in Bounds.

Inside the container, the hooks are hard to remove by mistake. Hook registration lives in Claude Code's admin-controlled managed settings (/etc/claude-code/managed-settings.json). That file is root-owned and read-only, takes precedence over user and project settings, and sits outside the git-synced working tree. A push to the agent's repository cannot reach it, and neither can an ordinary edit inside the container. The hook scripts under /opt/trinity/ are root-owned too. The Bash deny-list refuses the obvious sudocommands against these paths, and both paths are on the guardrails' own write-protection list. On every boot the container checks that the registration is present and unwritable and logs GUARDRAILS: ERRORif it is not, so a broken registration shows up in the agent's logs rather than going silently missing. The agent's /health re-checks it on every request (guardrails_registration). See Agent Guardrails.

Can an agent change how its guardrail hooks run?

No. Each guardrail hook is registered in exec form: Claude Code runs the interpreter directly, with no shell in between, so a shell prefix setting cannot wrap or replace the hook. The hook runs under a cleared environment and an isolated Python interpreter, so inherited PYTHON* or LD_*variables and user site-packages cannot change what it loads. The shell-prefix variable is pinned empty by the managed settings and is a protected key an agent's .env cannot set. The image build runs every registered hook exactly as registered and fails if one does not work. See Agent Guardrails.

Can an agent send its model traffic to another server or through its own proxy?

Not through any file it can write. Where a runtime sends its requests, and with them the API key or login token they carry, is set by the platform or the container, never by a file the agent can write. An agent's .env cannot set proxy or TLS-trust variables (HTTPS_PROXY, NO_PROXY and their lowercase forms, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, …) on any runtime, or its own runtime's endpoint variables (ANTHROPIC_BASE_URL and the other Anthropic base URLs on Claude Code, the Codex URL overrides on Codex, GOOGLE_GEMINI_BASE_URLon Gemini). Such a line is ignored and the agent log names the variable, never its value. The same values are pinned against each runtime's own files: Claude Code's settings env, Codex's config.toml and its .env, and the .envthe Gemini CLI loads itself. A proxy or CA set on the container itself, for example through Docker's proxy configuration, keeps working. Variables another runtime reads stay available, so a Claude agent can still give OPENAI_BASE_URLto its own MCP servers. This protects against the agent's own files, not against an agent that uses its passwordless sudo: root can rewrite the pinned settings, the same limit the guardrail hooks have, and the Bash deny-list refuses the obvious sudo commands against those paths. After upgrading, rebuild the base image and recreate agents for this to apply. See Agent Runtimes.

Why are some Claude Code tools missing during a scheduled or headless run?

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 — a scheduled wake-up, a cron entry, a workflow or task-output notification, a message to another local session, a push notification, a remote trigger — would let the agent plan around an event that will never arrive, so Trinity withholds that whole tool family from headless runs, platform-wide, merged with any per-agent disallowed tools. The agent is told so in its platform prompt and pointed at Trinity's own mechanisms instead: run_agent_loop for repetition, set_reminder for a deferred self-trigger, and chat_with_agent for talking to another agent. Subagents are unaffected, and a background shell command still running when the turn ends is killed with the execution recording that it was. See Agent Runtimes.

What is read-only mode?

A per-agent mode that prevents the agent from modifying source files (*.py, *.js, and similar) inside its own container, while still allowing writes to designated output folders like output/ and content/. It is part of the agent's tool access profile under Settings › Guardrails › Tool access: Read-only + report and Strict read-only turn it on, and the Read-only toggle in the agent header and on the Dashboard list is a shortcut to Strict read-only. On Claude Code it works through the same hook mechanism as guardrails, intercepting file-editing tool calls before they run; Codex enforces it through its sandbox, and Gemini CLI does not enforce it. The platform writes the read-only switch as a root-owned, read-only file under /opt/trinity/, so the agent cannot delete or rewrite it to turn the mode off; a copy in the agent's home folder decides only while that file is missing, and the guardrails protect it too. Use it for agents that should analyze and report but never change their own code. See Agent Guardrails → Tool Access.

Is it safe to expose a fresh Trinity install to the internet before setup?

Only an install with no admin account has an open window. On a normal install start.sh refuses to start while ADMIN_PASSWORD is blank, so the admin exists before you ever open a browser and the first-run form never appears. The unauthenticated Create your admin account form at /setup shows only when the backend came up with no admin: a bare docker compose up, a hand-rolled backend, or a DigitalOcean droplet created without a password (the 1-Click or the trinity-do-create.sh installer) — which boots with ADMIN_PASSWORD blank and ADMIN_PASSWORD_SOURCE=browser on purpose, so the first browser visitor claims the admin with no terminal. That claim window is the accepted risk of the path: anyone who finds the IP first can claim the instance, so open its URL right after creating the droplet (first boot takes about ninety seconds) or restrict port 443 to your own IP with a cloud firewall until you have claimed it, and keep any other admin-less install behind a VPN, tunnel, or firewall until the account exists. If a droplet you have never opened shows the loginpage instead of the form, someone else got there first — it holds nothing yet, so destroy it and create another. Choosing the password before first boot (cloud-init user-data on the 1-Click) closes the window entirely; that password stays in the droplet's user-data for the droplet's life. The form's endpoint refuses with 403 whenever a usable admin already exists, whatever the setup flag says, so it cannot be used to take over an install that is already configured. See Setup and Single Server → Claim the Admin Account.

Can I delete or overwrite an agent's protected files from the file manager?

No. The file routes refuse to write, create a folder at, or delete a protected path: credential files (.env, .env.*, .mcp.json, .mcp.json.template, .credentials.enc), .ssh, .aws, .gcp, Claude Code's settings files, .trinity, .git and .gitignore, and system paths such as /opt/trinity, /etc and /proc. Deleting a folder that holds one of those paths is refused as well, so you cannot remove .ssh or the whole home folder to get around the rule; the refusal is 403 Cannot delete protected path. Paths are normalised before the check, so extra leading slashes (//home/developer/.ssh/...) or .. segments do not slip past it, and the agent acts on exactly the path that was checked. The in-agent guardrail hooks apply the same normalisation. See Agent Files.

Can an event payload inject instructions into the agent that receives it?

Trinity makes that hard. An event's payload comes from whichever agent emitted it, so every {{payload.*}}value placed into a subscriber's task message is scrubbed for credentials, capped at 4,000 characters, and wrapped in ⟦ ⟧markers (marker characters inside the value are stripped, so it cannot close the frame early). The message also gets a line telling the subscriber that the marked text is event data, not instructions. The subscription's own template text, which the owner wrote, stays unframed. Payloads larger than 64 KiB are refused when the event is emitted. See Event Subscriptions.

Can a crafted Host header get a restricted key past its route limits?

No. Bounded keys (ops, connector, portal delegate) are fenced to specific routes, and those fences compare the path the request was actually routed to, not a URL rebuilt from the Host header. On top of that, the backend refuses any request whose Host header contains /, ?, #, \, @, whitespace or a control character, with 400 Invalid Host header (WebSocket handshakes are closed with code 1008). See Authentication → MCP key scopes.

Why do I need a code to change my sign-in email?

Because your sign-in email is your identity. Every sign-in path finds the account by its email, so whoever holds an address on an account can sign in as it. Changing it therefore takes a 6-digit code sent to the new address, the code completes only your own change and never signs anyone in, and an address another account already holds is refused (409 email_in_use). Each email belongs to at most one account, compared case-insensitively. On an install with no email provider, only an admin can bind an email without a code, and that is recorded in the audit log as unverified. See Authentication → Changing your sign-in email.

Can an agent publish one of its canvases to the open internet on its own?

No. An agent can write a canvas and mark it for its roster, but it cannot create, list, or revoke a share link — the share routes refuse an agent's own key outright, the same way the pin route does, and there is deliberately no MCP tool for them. Deciding who outsidethe platform may read a canvas is a person's call: only the agent's owner or an admin can click Share, the narrower People who already have access option is preselected, and Anyone with the link says plainly that it needs no sign-in. Links stay live until Revoke, and creating or revoking one is recorded in the audit log, as are canvas deletes and pins. Everything on a canvas is sanitised before it renders — scripts never execute, <style>tags are stripped — so a shared page cannot restyle or script the browser that opens it. See Agent Canvas.

Can an agent turn on its own wake-on-answer?

No. Wake this agent when an ask it raised endsmeans each answer, cancellation or expiry can start a turn the owner pays for, so the switch belongs to people. An agent's key acts for its owner, but PUT /api/agents/{name}/operator-resume refuses it with 403before anything changes. Only the agent's owner or an admin can turn the switch on or off, from Settings → Reliability. An agent can still read the setting, so it can tell whether an answer will wake it. See Agent Configuration.

Can an agent change its own autonomy, resources, or guardrails?

Not on its own say-so. Autonomy, capabilities, parallel capacity and the API-key setting accept only a person: a browser session or the person's own userAPI key. An agent's key acts for its owner, but those routes refuse it with 403 (person_required) even when the owner is an admin, and so do the system key and every other scope. Read-only mode, resources, timeout, the public-channel model and guardrails accept an agent key only when an admin has granted that agent Manage other agents, and even then an agent can never lift its own read-only mode or guardrails. Autonomy matters most here: it decides whether the agent's schedules fire unattended. An agent's own key can still create, enable and disable its own schedules. See Authentication → What a Key Is Not.

How do I let an orchestrator agent create agents or change another agent's schedules?

Grant it the permission. Open the orchestrator's Settings › Guardrails pane and, as an instance admin, turn on the matching toggle under Permissions to change itself: Change skills, Change other agents' schedules, Change instructions, Manage other agents or Start projects. No agent holds any of them by default, and only an admin signed in to the UI can grant one; an API key cannot. Even with a permission, the agent reaches only agents its owner owns and cannot lift its own read-only mode or guardrails. Without it, the agent is refused with a named 403 (for example schedule_management_not_permitted) and told to ask; its open requests show on the same card. See Agent Configuration → Permissions to Change Itself.

Can an agent use its own API key to reach another agent directly through the backend?

Only an agent it is allowed to reach. An agent key carries its owner's role, but on the backend's own routes it reaches itself, the agents it is permitted to call, and the agents it spawned — the same rule the MCP tools apply. Any other agent is refused as if it did not exist, so an agent cannot chat with, task, or read the history and logs of a sibling just because the same person owns both. Permission to call an agent never lets it manage that agent; managing needs a permission an admin grants. See Authentication → What an agent key reaches.

Is a webhook URL secure enough on its own?

The URL's embedded token is the whole credential, so anyone who obtains the URL can trigger that schedule (rate-limited, and every call is audit-logged). For anything sensitive, enable signature authentication: Trinity issues a signing secret exactly once (stored only encrypted after that), and every request must then carry an HMAC-SHA256 signature of the request body. Requests with a missing or invalid signature are rejected, so a leaked URL alone is no longer enough. You can rotate the secret or the URL at any time. See Webhook Triggers.

How do agents and the backend authenticate to each other?

In both directions, with per-agent credentials. Every backend call into an agent container carries a token derived specifically for that agent from a master secret that never leaves the backend — so even a fully compromised agent cannot compute a sibling's token or impersonate it. In the other direction, each agent authenticates to the platform with its own agent-scoped API key, which is restricted to that agent's identity and revocable independently. See Authentication.

Does Trinity phone home?

Nothing leaves your server without an explicit, admin-level opt-in — and never silently. By default Trinity records only anonymous product events (a small fixed set of onboarding/setup steps) locally, in its own database, with zero network egress. There are exactly two outbound paths, both opt-in and independent of each other: the Security & product updates contact form (Settings → General, or the optional checkbox on the first-run form), which sends exactly the details you typed at most once per install and can be disabled outright with OPERATOR_INTAKE_ENABLED=false; and anonymous Usage sharing, a reversible admin toggle that sends coarse aggregates (never PII, message content, emails, or agent names) under a random share id that is never your install id. The standard DO_NOT_TRACK=1convention hard-disables both, and a blocked or failed send never affects the platform. This covers Trinity itself: an agent still calls its model vendor's API on every turn, because that is how it runs. Trinity turns off the Gemini CLI's own usage statistics (privacy.usageStatisticsEnabled: falsein the agent's ~/.gemini/settings.json, re-applied before every turn), so a Gemini agent does not send Google an install id or host details. It also turns off Claude Code's usage telemetry, error reporting and update and feedback checks (CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY and DISABLE_ERROR_REPORTING, set in the agent image's managed settings), so a Claude Code agent sends no usage events or error reports to Anthropic or its third-party log intake; the agent's own settings and .envcannot turn them back on (as with the routing pins, that protects against the agent's files, not against an agent that uses its passwordless sudo). What Claude Code still sends goes to Anthropic, which the agent already calls: the model requests, its own settings and policy-limit reads, and a domain check before each web fetch. Codex agents are not covered yet: Trinity does not yet turn off the Codex CLI's own usage analytics. See Product Telemetry. Two more requests go to a vendor-hosted service only when someone asks for them: the help widget (a question typed into its Ask tab, or a report filed from its Bug, Feature or Feedback tab) and the ask_trinity tool, with which an agent asks the hosted docs service a question about Trinity. BUG_REPORTING_ENABLED=false and ASK_TRINITY_ENABLED=false switch them off, and DO_NOT_TRACK=1 switches off every path named here at once, with no rebuild.

What does Trinity record about my usage, and does any of it leave my server?

By default Trinity records only anonymous local product events — a small fixed allow-list of onboarding and setup step events, stored in its own database — and they never leave your server; there is no toggle and nothing to configure. Separately, an admin can opt in to share coarse anonymized aggregates (release version, edition, install lane, counts of agents, executions and funnel steps, and an outcome mix of how runs ended) with a hosted benchmark service in exchange for fleet benchmarks; this is off by default, keyed by a random share id that is never your install id, and validated against a documented schema before every send. The shared aggregates never include PII, message content or prompts, emails, or agent names, and they can't be used to reconstruct individual activity. See Product Telemetry.

How do I turn usage-data sharing on or off?

Two admin-only surfaces, both off by default. The ask is the Usage sharingstep of first-run setup — the overlay that opens over the Dashboard for an admin who has not yet decided — headed Help improve Trinity with an Off by default badge; it offers Share anonymous usage, Don't ask again (a once-per-install marker that silences it on every browser and device; audit-logged), and Skip — later in Settings → General (undecided in this browser only; nothing is sent). A closed setup is never reopened by the ask itself — re-run it from Settings → General → First-run setup → Re-run setup. The permanent home is Settings → General → Usage sharing: the reversible toggle, the backfill choice (7, 30, or 90 days of local history, or none), the share id, an “Exactly what would be shared” preview of the exact payload, and Recent sends— the last five attempts with the receiver each went to and its status. Egress needs two independent gates — your stored consent and the TELEMETRY_SHARING_ENABLED config switch, which honors DO_NOT_TRACK— so if either is off nothing leaves the box; opting out deletes the share id locally and the next heartbeat stops sending. Consent is a human-only decision: an API key of any scope cannot toggle it or dismiss the ask. See Product Telemetry.

What should I do before exposing Trinity to the internet?

Make sure the admin account exists and complete first-run setup while still behind a VPN or firewall, with a strong admin password (on a provisioned DigitalOcean droplet, the Secure this instancestep of first-run setup walks you through a domain and then a tunnel). Prefer the Cloudflare Tunnel approach — it opens no inbound firewall ports and only forwards the path prefixes you list, so unlisted routes are rejected at the edge before reaching your server. Then harden the surfaces you actually expose: enable signature authentication on webhooks, review the email whitelist so only intended addresses can log in, and keep the tunnel token in your gitignored .env. If everyone who needs access can reach the server over a private network like Tailscale, you may not need public exposure at all. See Public Access.

My instance came from a cloud marketplace and answers on a bare IP — how do I lock it down?

Three stages, in order: add a domain, then either a Cloudflare Tunnel or a private network, then close ports 80 and 443 with a cloud firewall. A one-click droplet is reachable from the moment it boots because no provider in that channel can attach a private network at create time, so the default is fine for evaluation and not for an instance holding real work. Choose the tunnel if anything outside has to call in — Telegram, WhatsApp, VoIP, public links, webhook triggers — and a private network only if nothing does. See Hardening a Marketplace Install.

Who controls which users can access an agent?

Access is governed by Trinity's role and sharing model: owners share agents with specific users, admins see everything, and roles gate who can create agents at all. That model is covered in its own documentation rather than here. See Roles and Permissions and Access Control.

An admin API key can do anything an admin can — is that a problem?

Not any more — the admin gate is an allowlist over key scopes, not a list of known exceptions. An MCP key resolves to the user who created it, carrying that user's role, so on a default admin-owned install an agent's own injected key would otherwise pass any plain “is this caller an admin?” check. Admin-only endpoints now admit only a browser session, a standard userkey, and the system agent's key: an agent-scoped key never satisfies an admin gate, and neither does a connector, portal_delegate, ops or ops_write key or any scope invented later (the individual ops read routes opt the ops scope in explicitly). On top of that, endpoints whose blast radius is operator-scale require a humancaller and reject keys of any scope: approving an oversized retention deletion, turning usage sharing on or off, restarting or reinitializing the system agent, reading or rotating an agent's MCP key, minting an ops, ops-write or portal-delegate key, binding an agent to a GitHub repository, writing an evaluation, and editing organizational tags. A 403 from an automation on one of those is the gate working as intended. Managing skill sources is the exception in the other direction: an admin's standard user key and the system agent can do it, over REST or the skill-source MCP tools. See Authentication.

Can my admin API key act on behalf of one of my agents?

Yes, for the tools that act as the calling agent itself: raising or withdrawing an ask, filing a report, recording metrics, reading objectives, and the canvas tools. The Workspace project tools are not included. Pass agent_nameto the tool from an MCP client using an admin's own userkey, and the request is made and recorded as that agent. Only an admin's user key may do this; any other key or a browser session that tries gets 403 act_as_not_permitted. Every such request writes an acted_as_agent audit entry naming you and the agent, and credentials stay out of it: ask_for_credentialstill needs the agent's own key. See Authentication → An admin's key acting for an agent.

Why can't my script create or list MCP API keys using another API key?

Creating or listing keys requires a signed-in session. POST /api/mcp/keys, POST /api/mcp/keys/ensure-default and GET /api/mcp/keys accept only a login (JWT) token and refuse every MCP key with a 403, your own user key included, so a leaked key can neither mint more keys nor enumerate the existing ones. Sign in first (POST /api/token, or the email code flow) and send that token instead, or create the key under Settings → MCP Keys. The same rule protects changing your sign-in email and your personal GitHub token. Every created key is recorded in the audit log. See Authentication → MCP key scopes.

What is an Ops (read-only) API key, and when should I use one?

It is the bounded machine credential for a monitoring integration — a status dashboard or an ops agent — that must keep working when two-factor authentication is enforced, since key validation never passes through the second-factor flow. An ops key reaches a fixed set of read endpoints (version, fleet status, health, schedules, alerts and costs, monitoring status, host and container telemetry, the agent roster, execution stats, history and the live log stream, subscription usage) and nothing else: every write is refused, it gets no MCP tools, and it cannot open the event stream. Only an admin in an interactive browser session can mint one (Settings → MCP Keys, the Ops (read-only)scope choice); no key of any scope can. It remains a narrowing of its owner — if that admin is demoted or suspended the key stops working — so mint it under a dedicated service admin account and re-mint any ops key held by a departing admin. Every call it makes is attributed to the key in the audit log. Its write sibling, ops_write (the Ops (operational writes)choice), reaches four writes — circuit-breaker reset, agent start, agent stop and execution terminate — and nothing else, not even the reads; mint it the same way and hold both keys if an integration reads and writes. The other admin-minted bounded scope, portal_delegate, reaches exactly one route (exchanging an end-user email for a Workspace session, which requires an entitlement) and refuses everything else. See Authentication.

How do I know my agent is authenticating to Trinity as itself?

Check the Trinity access keypanel under the agent's Settings › Integrations. It reports a health state and offers a Verify action that probes the container's actual configuration and tells you whether it is carrying its own key, a foreign user key, another agent's key, an unknown key, or a duplicate entry. This matters because the agent-to-agent permission matrix only applies to agent-scoped keys — a container holding a user-scoped key operates with the owner's identity and bypasses the matrix. If something is wrong, Regeneraterotates and delivers a fresh key; Trinity also self-heals a missing or mismatched key on the agent's next start. See MCP Server.

What does turning on AAuth publish, and who can call my agents afterwards?

It publishes one public key and three small discovery documents under /.well-known/aauth-*.json, so that other Trinity instances can verify calls your agents sign — never a secret, and nothing at all until an admin sets the issuer and flips Sign and accept agent-to-agent calls in Settings › Integrations. Being on does not open any agent: a signed call is accepted only for an agent that is exposed over A2A and has the caller's exact aauth:<agent>@<host>identity on its inbound allow-list, which fails closed (an empty list admits nobody, and Trinity refuses to even fetch a caller's keys unless its host is already listed). An admitted caller never becomes a Trinity user and carries no role. What you are trusting when you list an identity is whoever controls that domain and the key set it publishes — one key signs for every agent on an instance — and revoking is deleting the entry. See A2A Protocol → AAuth agent identity.

Who can change the AAuth settings, and can an agent do it?

Only an admin signed in to the browser. Reading GET /api/settings/aauth is admin-only; writing it is admin andinteractive, so an MCP key of any scope — agent, user or system — is refused, because turning AAuth on publishes the instance's key and changing the issuer renames every agent's identity for every peer. The generic settings routes refuse every aauth_*key, so there is no second door, and each change is written to the audit log with the before and after values. The instance's signing key itself cannot be set or replaced through the API at all. See A2A Protocol → Turn it on.

Can a skills repository push executable code to my whole fleet without me noticing?

Only if you enable fleet re-inject, and even then the supply chain is pinned. Skills carry executable scripts, so the bundled community source — which accepts public contributions — is pinned to a tag, not a branch head, and a tag that later resolves to a different commit is refused rather than adopted. Custom sources, whose write access you control, track a branch. Both automation settings (auto-sync, fleet re-inject) default to off, source URLs are locked to github.com, and registering or syncing a source is admin-and-human-only because it decides which repository your fleet executes code from. See Skills and Playbooks.

Is anything stopping a retention setting from wiping my history?

Yes, two independent controls. Retention windows have exactly one write path, which type- and range-validates every value all-or-nothing and audit-logs the change; the generic settings endpoint refuses those keys. And any sweep that would delete more than a fixed safety threshold (1,000 rows) of a single table refusesto run, logs an error, and raises an operator alarm — an admin must then approve it explicitly, bound to the exact window in force and single-use. Note the counter-intuitive part: garbage input always failed safe (retain forever); a small valid numberis the dangerous input, which is why the approval gate, not the validation, is what actually protects you. “Reset to defaults” deliberately skips retention windows. See Monitoring.