Agent Runtimes
Trinity is model-agnostic: each agent runs on a pluggable runtime — the CLI harness that executes the agent inside its container. Trinity supports three runtimes: Claude Code (the default), Gemini CLI, and OpenAI Codex.
Concepts
How It Works
A template selects the runtime in template.yaml:
runtime:
type: codex # claude-code (default) | gemini-cli | codex
model: gpt-5.6-sol # optional model overrideThe runtime is fixed when the agent is created. To change it, recreate the agent from a template that declares a different runtime — there is no post-creation switch.
On the Agent Detail page, a runtime badge shows which runtime the agent is using. Chat works on all three runtimes, and each continues its own chat session from turn to turn. Only Claude Code resumes a session in the Workspace: a Codex agent's Workspace turns replay the visible history as text instead, and Gemini's headless turns never resume (see Limitations).
Runtime Comparison
| Claude Code (default) | Gemini CLI | OpenAI Codex | |
|---|---|---|---|
| Auth model | Claude subscription / OAuth, or platform API key | The platform Gemini key (Settings, or GEMINI_API_KEY / GOOGLE_API_KEY on the backend) | OPENAI_API_KEY in .env (or a ChatGPT-plan login; Codex skips Claude-subscription auto-assign) |
| System-prompt file | CLAUDE.md | CLAUDE.md | AGENTS.md |
| Chat continuity (own session) | Yes | Yes | Yes |
| Workspace session resume | Yes | No (headless turns never resume) | No (history replayed as text) |
| MCP support | Yes | Yes | Yes |
| Cost reporting | Reported by the CLI | Estimated from tokens | Estimated from tokens |
| CLI version | Pinned in the base image | Pinned in the base image | Pinned in the base image |
Safety controls are not the same on every runtime. Platform controls (which credentials the agent holds, which agents and platform calls its key may reach) apply to all three, and so does credential redaction of stored results: the backend scrubs execution output whichever CLI produced it. The in-container controls differ:
| In-container control | Claude Code | Gemini CLI | OpenAI Codex |
|---|---|---|---|
| Guardrail hooks (Bash deny-list, credential-file protection, leak scan) | Yes | No | No |
| Read-only mode | Yes, through a hook | No | Yes, through Codex's own read-only sandbox (--sandbox read-only) |
| Credential redaction of output | Yes, inside the container | No; only the platform's pattern-based scrub when results are stored | Yes, inside the container |
| Turn limit | Yes | No; the execution timeout bounds the run | No; the execution timeout bounds the run |
| Per-agent disallowed tools | Yes | No | No |
See How Trinity Keeps Agents in Bounds for where the boundary sits.
Endpoints and proxies
Every runtime talks to its provider's own API. The endpoint, proxy and TLS trust come from the platform or the container, never from the agent's files:
.env cannot set proxy or TLS-trust variables on any runtime, or the endpoint variables its own runtime reads. The agent log names each ignored variable.settings.json env block cannot change them.openai provider and its default URLs, whatever config.toml says, and Trinity removes proxy, TLS and other protected lines from Codex's own .env before each turn..env the Gemini CLI loads itself cannot set them.A proxy or CA configured on the container (for example by Docker's proxy settings) still applies to every runtime. Behind such a proxy, list the platform's internal hosts (mcp-server, backend, localhost) in the container's NO_PROXY, or Trinity MCP calls go through the proxy too. Using a self-hosted model or an alternative endpoint is not supported.
Claude Code's usage telemetry, error reporting and update and feedback checks are off. Trinity sets CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY and DISABLE_ERROR_REPORTING to 1 in Claude Code's managed settings in the agent image, so Claude Code sends no usage events or error reports to Anthropic or its third-party log intake, and makes no update, release-notes or feedback checks. An agent's settings.json env block and its .env cannot turn them back on; like the endpoint pins above, this protects against the agent's own files, not against an agent that uses its passwordless sudo. Two side effects: features that Claude Code's documentation lists as depending on its feature-flag fetch are unavailable (for example Remote Control, and claude.ai skills and plugins synced to the CLI), and Claude Code no longer updates plugins in the background, so a plugin from the official marketplace stays at its installed version until it is reinstalled. Trinity's own plugin is installed by the platform and is not affected. Still on: the model API calls, Claude Code's own settings and policy-limit reads, the WebFetch domain check, the official marketplace auto-install, and the OpenTelemetry metrics Trinity's own cost and token reporting reads, which go to your Trinity's collector, not to Anthropic. An existing agent picks this up when its container is recreated on the new base image: restart it (a stop and start, not just a start) after upgrading. A new ephemeral agent is created on the current image anyway, and a running system agent is recreated the next time it is stopped and started.
Codex authentication
A Codex agent authenticates in one of two ways, and Trinity handles the file the CLI reads its credential from:
OPENAI_API_KEY (or CODEX_API_KEY) as a credential. Trinity logs the CLI in with that key before the agent's first turn, so an API-key Codex agent works out of the box. If you rotate the key in .env, the next turn re-logs in with the new one.codex login yourself from the agent's terminal. Trinity never overwrites a plan login with an API key.Codex keeps its login and MCP configuration in ~/.tmp/codex/. The Files tab cannot edit or delete them (nor the .tmp folder that holds them); use codex login in the terminal as above.
Gemini authentication
A Gemini agent uses the platform's Gemini key. Trinity reads the key saved in Settings first, then GEMINI_API_KEY or GOOGLE_API_KEY on the backend, and passes it to the container as GEMINI_API_KEY when the container is created. Settings accepts Google AI Studio keys that start with AIza or AQ. — see Platform Keys. With no key configured, the agent is still created, but its turns fail with “GEMINI_API_KEY not configured”.
Gemini CLI turns
Trinity pins gemini-cliin the base image, and the image build checks that the pinned CLI accepts every argument Trinity passes. A new CLI release that drops a flag therefore fails the image build instead of every turn. Gemini CLI has no system-prompt flag, so Trinity puts the platform instructions in front of each turn's input. The execution log still shows only your message as the user turn.
Gemini CLI sends Google usage statistics by default. Trinity turns them off: it writes privacy.usageStatisticsEnabled: false to the agent's ~/.gemini/settings.json at startup and again before every turn, keeping the rest of the file. An agent's own setting cannot turn them back on. The settings file holds the agent's Trinity MCP key, so it is never committed by Git sync, like .mcp.json.
A chat turn resumes only the agent's own chat session, never the newest session on disk, so a scheduled or headless run never leaks into the chat. Changing the model or resetting the chat history starts a fresh session. If the saved session is gone, the turn retries once from a fresh session.
How failures are reported
429 status. A bare 429 inside a timestamp, port or process id is not misread as a rate limit.Headless runs on Claude Code
A task, schedule, loop, or MCP call runs the agent as a one-shot turn: nothing the agent starts survives the end of that turn. Claude Code's built-in tools that promise a later event — 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 tool family from headless runs (ScheduleWakeup, Workflow, Monitor, TaskOutput, CronCreate/CronList/CronDelete, SendMessage, ListAgents, PushNotification, RemoteTrigger). The agent is told the same thing in its platform prompt and pointed at the platform'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 — see Agent Loops and Agent Reminders. Subagents are unaffected: the turn waits for them. A background shell command that is still running when the turn ends is killed, and the execution records that it was, instead of reporting a clean success.
For Agents
Set the runtime in the template's template.yaml:
| Field | Values | Default | Notes |
|---|---|---|---|
| runtime.type | claude-code, gemini-cli, codex | claude-code | Selects the harness |
| runtime.model | runtime-specific model id (e.g. gpt-5.6-sol) | runtime default | Optional override — pin it, so recorded cost is attributable. On a Claude Code agent it is also saved as the agent's own model at creation, so turns the platform starts run on it too (see Model Selection) |
A Codex agent reads its identity and instructions from AGENTS.md. At startup Trinity copies the template's CLAUDE.md to AGENTS.md when the workspace has none, so a single instruction file works across runtimes; an AGENTS.md you ship yourself is left as it is.
Trinity's MCP tools are available to Codex agents. Codex references tools by their bare name (no mcp__trinity__ prefix); Trinity adjusts the platform prompt automatically so the agent calls them correctly. The prompt's protected-paths sentence is adjusted per runtime too: only Claude Code runs the file guardrail hook on its Write and Edit tools, so a Codex or Gemini agent is told plainly that nothing in its runtime blocks writes to credential and platform paths and that the rule is its own to keep (see Recommended Trinity Prompt).
The platform prompt also tells every agent not to run a coding-agent CLI (claude, codex, gemini or similar) as a subprocess, because a nested run escapes Trinity's execution ledger (see Recommended Trinity Prompt). That sentence is adjusted per runtime as well. A Claude Code agent is pointed to its Agent subagent tool (also named Task) for work inside the turn, when the agent has that tool. A Codex or Gemini agent has no such tool and is pointed to its own tools. Every runtime is pointed to chat_with_agent with parallel=true (which can target the agent itself and take a model) or fan_out for delegated, batch or second-model work.
There is no API or MCP endpoint to switch an agent's runtime after creation. See the full API reference at http://localhost:8000/docs.
Limitations
max_turns settings are logged but not enforced there. The execution timeout bounds the run.execution_timeout_sec guardrail (default 1,800 seconds, the same cap as a Claude Code chat) and answers 504 Chat execution timed out after N seconds; a Gemini task stops at its timeout with 504 Task exceeded Ns timeout. A timer ends the run even when the CLI has gone silent, so a hung Gemini turn no longer holds a slot forever.model_unsupported rather than an auth error (see Model Selection). Rebuild the base image after upgrading Trinity so agents pick up the newer CLIs.See Also
disallowed_tools, merged with the platform's headless denials