All pages
Docs · AI features
MCP server (drive TRMNLY from another agent)
Availability: macOS · Linux · Windows · cloud workspace. Each host advertises a different tool set — see Platforms.
TRMNLY's in-app agent has access to 428 tools — terminal, browser sidebar, file system, git, SSH, ports, automation, and so on. The MCP server bridge exposes that same surface to external Claude clients over the Model Context Protocol, so a Claude Code session running in another terminal — or any MCP-compatible tool — can drive TRMNLY just like the agent sidebar can.
This is the right surface to reach for when you want to:
- Run a long-form refactor from a separate Claude Code session while still using TRMNLY as your terminal.
- Let a CI- or cron-triggered Claude Agent SDK script read terminal output, drive the in-app browser, or queue commands.
- Share a single set of project-aware tools across multiple agents — both the in-app agent and any clients you wire up.
How it works
┌──────────────────┐ stdio ┌──────────────┐ ┌───────────────────────────┐
│ Claude Code, │ ─────────▶ │ trmnly │──▶│ TRMNLY app │
│ Cursor, Claude │ │ mcp-bridge │ │ mcp-server.sock │
│ Desktop, Codex │ └──────────────┘ │ (AgentMCPServerBridge) │
└──────────────────┘ │ │ │
┌──────────────────┐ HTTP/SSE 127.0.0.1:47823 │ AgentMCPSSEServer │
│ HTTP-only client │ ─────────────────────────────▶ │ (optional, + tunnel/LAN) │
└──────────────────┘ │ │ │
┌──────────────────┐ socket + $TRMNLY_SOCKET_TOKEN │ ▼ │
│ `trmnly` CLI in │ ─────────────────────────────▶ │ AgentTools (428 built- │
│ a TRMNLY pane │ │ ins + plugins + inbound │
└──────────────────┘ │ MCP servers) │
└───────────────────────────┘
Every transport ends in the same dispatcher, which routes each call to the tool implementation the in-app agent uses, applies the approval policy and the command rules, writes the audit log, and scrubs results.
| Transport | Where | Who uses it |
|---|---|---|
| Unix socket | ~/Library/Application Support/TRMNLY/mcp-server.sock, mode 0600. A build with another bundle id (Debug) gets mcp-server-<suffix>.sock so two copies never share one; a path too long for a socket address falls back to a short one. |
Everything below, ultimately |
trmnly mcp-bridge |
The launcher ~/Library/Application Support/TRMNLY/mcp-bridge, a two-line sh script that runs TRMNLY's own binary as trmnly mcp-bridge --socket <path> |
Any stdio MCP client — this is what claude mcp add trmnly … runs |
| HTTP + SSE | http://127.0.0.1:47823 (off by default) |
Clients that can't spawn a process |
| Tunnel / LAN | The same HTTP listener, reached through cloudflared, Tailscale or the TLS LAN listener |
Paired devices — see Remote over the tunnel |
In-pane trmnly CLI |
The socket, via $TRMNLY_SOCKET_PATH |
Shells inside TRMNLY panes — see Pane manifests |
The socket always listens while TRMNLY runs (since 0.1.65), whether or not
external clients are turned on — the in-pane trmnly command, the surface
manifest, the task board and the pane mesh all speak to it. Every pane gets a
per-launch $TRMNLY_SOCKET_TOKEN (held in memory, never written to disk). A
call that presents it is treated as the user's own shell and skips the
external-client approval tier; anything else on the socket, including
trmnly mcp-bridge, is an ordinary local client and is held to the tier.
trmnly mcp-bridge needs no Node, so GUI clients such as Claude Desktop,
which start servers without your shell's PATH, find it too. Its first line to
the app announces the working directory it was started in (that is how the
client's project is chosen, below) and, with --holder NAME or
$TRMNLY_MCP_HOLDER, a holder name for kanban claims and chat. If TRMNLY isn't
answering yet — mid-relaunch, say — it waits up to 25 seconds before giving up,
rather than leaving the client's session with no tools. The older
mcp-bridge.js (run with node) is still written for entries registered
before the launcher existed. Those rows read Connected · needs node; press
Update to move one over.
HTTP + SSE is Settings → AI Agent → External MCP clients → Also listen on localhost HTTP / SSE. The port defaults to 47823 and hops up to 12 ports on if that one is taken. Endpoints:
POST /mcp— one JSON-RPC message; the reply comes back as a singleevent: messageon atext/event-stream.GET /sse— a long-lived event stream (resource updates, approvals); sendLast-Event-IDon reconnect.GET /attach— a live pane over WebSocket (paired devices).GET /health—{ok: true}, unauthenticated.
The listener binds loopback only, and a request carrying a browser Origin
that isn't itself loopback is refused (403), so a web page can't drive it.
Until Remote Control has been paired there is no bearer, and local requests
are let in without one. Pairing gives the listener a bearer of its own (kept in
the keychain, not shown in Settings), and from then on every request needs a
token, local ones included: Authorization: Bearer, ?token= (local only), or
the WebSocket subprotocol. Copy HTTP config writes no header, so on a Mac
that has been paired, use the stdio bridge for local clients.
Tools — tools/list returns every built-in in
AgentToolName.swift
that this host can run, plus tools contributed by plugins and
inbound MCP servers, plus
one the bridge answers itself: remote_capabilities, which tells the caller
which tools it may use and which will ask for approval. Browser tools carry
_meta.schemaVersion. Beyond tools, the server answers:
resources/*— every open browser tab astrmnly://tab/<uuid>/dom,/screenshot,/consoleand/network.resources/subscribepushesnotifications/resources/updatedover SSE when one changes.prompts/*—verify_pr_preview, a scripted navigate → wait → screenshot → console-drain pass over a preview URL.
Turn it on
Settings → AI Agent → External MCP clients → Expose TRMNLY's tools to other apps. (The Plugins sidebar tab carries the same switch, Expose tools to other clients, plus a Manage clients… button that opens this pane.) What the switch governs is the foreign-facing half: the
mcp-bridgelauncher and the Claude Code skills under~/.claude/skills/. Turning it off deletes both, which cuts off every client registered with the launcher; the socket itself keeps listening for TRMNLY's own panes. The setting is persistent: quitting TRMNLY drops the socket but does not turn exposure off, and the bridge comes back on the next launch.Pick an Approvals tier:
- No approval — external clients run any tool without prompting.
- Approval for writes — read-only tools auto-run; writes and dangerous tools need approval.
- Approval for dangerous (default) — reads and writes auto-run;
dangerous tools need approval. "Dangerous" is a fixed list
(
dangerousToolNames): running shell commands (bash,run_command,spawn_and_read,run_background_job), typing into panes (send_keys,terminal_press_key,queue_command,pane_type), file writes and edits,ssh_exec/container_exec/sftp_*, runbooks and schedules, desktop input and AppleScript, eval-js, cookies and storage, key-vault and credential reads, and allowlist edits. - Approval for everything — every call needs approval.
With nobody to ask — no paired phone listening, and the client isn't TRMNLY's own sidebar — a call that needs approval is refused with an error that names the fix. So under the default tier, an external Claude Code can read the terminal and drive the browser, but its first
bashorsend_keyscomes back refused until you tick Trusted on its row or lower the tier.
The tier governs the bridge directly. (Before 0.1.48 it didn't: the gate read a legacy internal flag that no control wrote, so approval-gated tools were refused to external clients no matter what the picker said.)
Approving a prompted call can also record a time-boxed grant ("approve
for session") scoped to that client, tool, or origin. Grants auto-expire on
idle (default timeout is configurable) and are listed — and revocable — under
Client access. To stop being asked about a client at all, tick its
Trusted checkbox: that writes a * grant with no timeout, revocable from
the same row. The agent_mcp_server tool can start/stop exposure (the
launcher and skills, as the switch does) and report status, but
deliberately cannot change the approval tier — it has no action for that,
and an old-style set_approval call is refused. That only happens in
Settings → AI Agent → External MCP clients → Approvals.
Per-client project binding
A tool call that names no project_id has to run against some project, and
the client's own working directory is what decides which. The bridge a client
launches is a child of that client, so it knows the directory, announces it on
connect, and TRMNLY matches it against every project folder and worktree folder
it knows — deepest first. A Claude Code session started in
~/Workspace/kavanah files kanban_add against Kavanah's board, and its
bash runs in ~/Workspace/kavanah, whatever window you are looking at.
The order, highest first:
- the tool call's own
project_id/project_name - the client's working directory, when it is inside a project TRMNLY knows (a worktree folder binds the worktree too)
- the Project column in Client access — pick a project and that client's calls run against it wherever it is started, applied live without reconnecting
- the project of whichever window was focused at this connection's first tool call, frozen there so a later focus change can't move a running client
Rung 2 beats rung 3 because the Settings column is keyed on a client name
that every session of that client shares — every Claude Code session on the
machine announces Claude Code — while the directory is evidence about the one
session making the call. Leave the column on Follow client folder unless you
want a specific client pinned somewhere regardless.
A client whose directory is outside every project (~/Downloads, a repo with
no project) falls through to rungs 3 and 4. Nothing is created behind your back.
Two refinements. A worktree_switch made on a connection moves that
connection's binding to the worktree it switched to, ahead of the folder it
announced. And an HTTP client has no launching process to report a folder, so
it lands on rung 3 or 4 unless it says where it is per call: _meta.trmnlyCwd
(a local path, ignored from the tunnel) or _meta.trmnlyProjectId (a project
id, honoured from anywhere; what the phone sends).
get_context reports the binding and where it came from (project source: client folder (…) / configured pin / focused window), and project_list
marks the bound project [bound: client folder] / [bound: configured pin] /
[bound: focused window] — so an agent can tell a project it chose from a
project that was chosen for it, and pass project_id explicitly when the
default isn't what it meant.
The in-pane trmnly CLI says the same thing per call, so trmnly task add
from a project folder lands on that project's board.
Per-client tool access
⋯ → Edit tool access… on a client row opens allow/deny glob lists
(browser_*, *_navigate, *), a default-allow/block switch, and per-client
rate limits. Deny patterns are checked first, so a deny carves a hole in an
allow-everything policy. Reset to preset drops the record and returns the
client to its built-in default (Cursor ships read-only browser access; Claude
Code ships the full surface; everything else is allow-all).
Wire up Claude Code (and Cursor, Claude Desktop, VS Code)
Settings → AI Agent → External MCP clients → Apps lists the MCP clients found on this machine, whether TRMNLY is in each one's config, and a Connect button that puts it there. Status is read back from the client's own config file, so the row reflects what the client will actually load.
Claude Code registers at user scope — visible from every project. A row
reading Connected · ~/some/repo only means the entry is in that one
directory's local scope (what TRMNLY wrote before 0.1.48, from the app's own
working directory); press Fix to re-register at user scope.
By hand, if you prefer:
claude mcp add --scope user trmnly -- "$HOME/Library/Application Support/TRMNLY/mcp-bridge"
Omitting --scope user takes the CLI's local default, which only applies to
the directory you ran it in.
The server name (trmnly above) determines the tool prefix Claude Code uses
(mcp__trmnly__read_terminal, mcp__trmnly__browser_state, …) and must match
what the skill bundles reference — TRMNLY ships six skill files under
~/.claude/skills/trmnly-*/SKILL.md that hint Claude Code about when to
reach for the MCP tools (see Claude Code skill bundle).
The in-app agent can do the same:
mcp__trmnly__agent_mcp_server {
action: "register_with_claude_code",
name: "trmnly", // server name
scope: "user" // default; or "project" / "local"
}
If the claude CLI isn't found, you get the exact command to paste wherever
Claude Code lives.
Any other client: Copy stdio config / Copy HTTP config produce a ready-to-paste block. TRMNLY writes JSON configs (Claude Desktop, Cursor, VS Code) in place, preserving everything already in them, and refuses rather than overwriting a config it can't parse. Codex CLI is copy-only — its config is TOML.
The six tool families
Conceptually grouped, with a short pointer for each. The full list lives in
AgentToolName.swift; the skill bundle in claude-skill/
documents the most useful subset for an external Claude.
| Family | Lives in | Examples |
|---|---|---|
| Terminal | trmnly-terminal | read_terminal, run_command, queue_command, split_pane, watch_terminal, run_background_job |
| Browser | trmnly-browser | browser_navigate, browser_click, browser_eval_js, browser_screenshot, browser_har_record_start, browser_session_bucket_create |
| Connections | trmnly-connections | ssh_exec, sftp_read, port_forward_apply, container_exec, docker_compose_up |
| Automation | trmnly-automation | list_prompts, schedule_create, save_runbook, add_tab_monitor_rule, list_write_snapshots, awake_acquire, post_notification |
| Worktrees | trmnly-worktrees | project_list, worktree_list, worktree_create, worktree_switch, worktree_adopt, worktree_merge_cleanup |
| Desktop (macOS) | trmnly-desktop | ax_find, ax_action, ax_menu_invoke, ax_wait_for, mouse_click, key_type, screen_capture_region, osa_exec |
There's also a "file system + git + LSP" family (read_file, edit_file,
grep, git_status, lsp_diagnostics, …) that's available but not bound to
a single SKILL.md — Claude Code's own built-in skills cover that kind of
work, and external agents can pick whichever surface fits.
Two bits of plumbing external sessions lean on: every client is bound to the
project its working directory sits in (so project-scoped tools land in the
right place without being told — project_list shows the options and says why
this one is bound, and worktree_create can spin up a git worktree to work in;
see Worktrees), and
conversation_save / conversation_list / conversation_get let an
external agent persist its transcript into TRMNLY's sidebar, badged as
imported and idempotent on its external id. conversation_send posts a
message into one of the agent's own conversations and runs a turn (see
Agent); it is
approval-gated like bash. conversation_archive and conversation_delete
archive (or bring back) and permanently delete one; delete asks first.
Safety guarantees
The bridge is built on the same approval and audit infrastructure as the in-app agent. Worth knowing:
- Approval-gated tools are refused for headless clients. A call the tier gates is denied with an explanatory error — unless the user issued a grant covering it, or a paired remote approver (e.g. the phone app) is listening, in which case the call waits on an Approve / Deny prompt surfaced as a macOS banner and in-app sheet.
- Secrets stay in the vault. Tool arguments that look like live
credentials are denied (use
{{key:…}}placeholders instead), and secret-looking values in tool results are scrubbed unless the user granted that client theread_secretscapability. - The destructive-verb gate still applies (see
Agent safety).
rm -rf,git push --force, etc. are refused or require an explicit confirmation tool call from the client. - Browser egress allowlist still applies. If the user has the browser sidebar in Allowlist mode, external clients see the same 403-style rejection on un-approved hosts.
- Audit log. Every tool call from an MCP client is recorded with the client's session id in the audit log. Open the Agent audit log panel to inspect.
- Per-client policy. Each connecting client can carry its own tool allow/deny globs, rate limit, and cost budget, evaluated on every call.
Plugins vs MCP
Both surfaces let outside code contribute tools to the in-app agent, but they answer different questions:
- Plugins — JavaScript modules TRMNLY loads at launch. Best for adding new tools to the in-app agent, surfacing status pills, or contributing sidebar views. They run in-process and have direct access to the agent's host APIs.
- MCP server bridge (this doc) — TRMNLY exposes its tools to outside agents. Best for letting another Claude session, an SDK script, or any MCP-compatible host drive TRMNLY.
If you want a tool inside the in-app sidebar, build a plugin. If you want another agent to drive what's already there, use MCP.
Inbound MCP (TRMNLY connecting to other servers)
The bridge can also work in the opposite direction: TRMNLY's agent can
consume tools from other MCP servers (Notion, Linear, Postgres, etc.) and
fold them into the in-app agent's tool list. Configure servers in the
Plugins tab → MCP servers (external) section → + Add, which
saves to ~/Library/Application Support/TRMNLY/mcp.json. A server is
reached one of two ways:
- Command — a stdio subprocess on this Mac (command + args + env).
The command is an absolute path, or a plain name like
npxornodelooked up in/opt/homebrew/bin,/usr/local/bin,/usr/binand/bin— never your shell'sPATH, which a project'snode_modules/.bincould put first. The command's own folder leads the child'sPATH, sonpxfinds thenodebeside it. The child gets onlyPATH,HOME, locale andTMPDIRfrom TRMNLY's environment, plus theenvyou give it. - URL — a hosted server over Streamable HTTP (one endpoint, POSTed
JSON-RPC, replies as JSON or SSE,
Mcp-Session-Idkept and renewed when the server drops it). HTTPS only, excepthttp://localhost. Add the headers the service wants, usually its API key. Redirects to another host are refused so the key doesn't follow them.
Values in env and headers can be written as {{key:NAME}}: the key is
read from the Keys vault each time the server starts, so
mcp.json never holds the secret. A reference that doesn't resolve keeps
that server from starting (logged under agent.mcp) rather than sending
the placeholder as a credential.
{
"servers": [
{ "name": "kavanah",
"command": "/opt/homebrew/bin/node",
"args": ["/path/to/Kavanah-New/mcp/dist/index.js"],
"env": { "KAVANAH_BASE_URL": "https://kavanah.ai",
"KAVANAH_API_KEY": "{{key:KAVANAH_API_KEY}}" } },
{ "name": "angelsend",
"url": "https://<project>.supabase.co/functions/v1/mcp-server",
"headers": { "x-api-key": "{{key:ANGELSEND_API_KEY}}" } }
]
}
Tools appear as mcp__<server>__<tool>, and every one asks for approval
before it runs unless toolApprovals opts it out ("*": false for the
whole server, or per tool name). They reach a CLI harness agent (Claude
Code in the sidebar) too, through TRMNLY's own bridge. Press Reload
after editing mcp.json by hand.
Each server's row in the list has a status dot and a one-line state:
Starting…, Connected · N tools (or Connected, no tools), Not
started. Reload starts it now., or — in red — why it failed to start: a
{{key:NAME}} missing from the vault, a command that couldn't be found or
exited (with its last line of stderr, secrets scrubbed), or a URL that was
refused or answered with an error. The text is selectable, so it can be
pasted into a bug report or the agent chat.
Remote: the Mac over the tunnel
With Settings → AI Agent → Remote Control paired, the HTTP listener above
is also reachable from outside the Mac — through a cloudflared tunnel,
Tailscale, or the optional TLS LAN listener (preferred port 47843, Bonjour
_trmnly._tcp). The protocol is the same (POST <tunnel>/mcp, GET /sse,
/attach); what changes is who may call:
- Nothing remote is anonymous. A caller presents its own device token (or a
15-minute access token bound to this Mac), and the Mac checks its hash
against the roster
trmnly.devhands back on every heartbeat. A revoked device is out within one heartbeat, and its open sockets are closed. - Each device's scopes decide which tools it may call. A remote call to a
dangerous tool asks for approval on the paired phone whatever the tier, and
an "allow for N minutes" answer is bound to that device and project.
remote_capabilitiesreports the verdict per tool before you try. $TRMNLY_SOCKET_TOKENand_meta.trmnlyCwdare ignored from the tunnel: the far side is neither a TRMNLY pane nor on this filesystem.
Remote control has pairing, transports, scopes and the trusted
phone in full. Note that a connection made by signing in at trmnly.dev/mcp
(next section) is cloud-only and never reaches the Mac.
Linux and Windows: trmnly-core-mcp
On Linux and Windows the server is the portable core's
trmnly-core-mcp. There is
no launcher script; register the binary itself:
claude mcp add --scope user trmnly -- trmnly-core-mcp
- Bare, it serves MCP on stdio, rooted at
$TRMNLY_ROOTor its working directory.--socket PATHserves a Unix socket instead, which is what the GTK app starts so every pane'strmnlyreaches it through$TRMNLY_SOCKET_PATH;--exit-with-parent [PID]stops it when the app is gone.--host gtkchanges only how an unavailable tool explains itself. - On start it installs the same skills into
~/.claude/skills, less the macOS-onlytrmnly-desktop(skip with--no-skills), and--setup-project DIRwritesTRMNLY.mdand the@TRMNLY.mdline intoCLAUDE.local.md, then exits.$TRMNLY_MCP_SERVER_NAMEretargets themcp__<name>__prefix in both. - It advertises only the tools its host can honour (no browser, no macOS desktop or app UI), and executes a subset of those; the rest answer "not implemented on this host yet" rather than a wrong result. Platforms has the tiers and the counts.
There is no HTTP listener, tunnel, approval tier or per-client policy on the core yet; it trusts whoever spawned it, the way a shell does.
The cloud workspace over MCP (no Mac required)
Everything above drives the Mac app. The cloud workspace — the per-account
Linux sandbox behind trmnly.dev — speaks the same protocol at a public
endpoint, so an MCP client can drive it with no Mac in the picture at all:
claude mcp add --transport http trmnly-cloud https://trmnly.dev/mcp
codex mcp add trmnly-cloud --url https://trmnly.dev/mcp
The name is trmnly-cloud, not trmnly: TRMNLY for macOS registers a
stdio MCP server called trmnly, and a client's project-scoped server of
the same name hides it — following the old instruction on a Mac running
TRMNLY swapped that project's desktop tools for the cloud's, silently.
That's all: no token. The first time the client connects it gets a 401 naming
where to sign in, registers itself, and opens the browser at a trmnly.dev page
asking "Connect Claude Code?". Allow sends a token back to the client. This is
the MCP authorization spec (OAuth 2.1 with PKCE and dynamic client
registration, site/lib/mcp-oauth.ts), the same flow hosted MCP servers like
Linear's and Notion's use. The workspace's rail (⇄) and the dashboard's
Connections list both show these commands. /api/mcp still works, and is
the same endpoint. To sign in again later (after a Disconnect, say), Claude
Code's /mcp menu has Authenticate, and Codex has codex mcp login trmnly-cloud.
A connection made this way reaches the cloud workspace only. Its token is a
devices row with platform = "cloud-agent". resolveCaller refuses it
everywhere except /mcp and /api/mcp, and the Mac tunnel's roster leaves it
out. It shows under Connections on the dashboard ("Claude Code · signed in"),
where Disconnect revokes it. There is no expiry and no refresh token: a
connection lasts until it is revoked.
For a script that can't open a browser, Generate token under Connections
still mints a trmnly_… token to send as Authorization: Bearer. Unlike a
sign-in, it also opens every Mac paired to the account.
What it exposes is the union of two halves, the same way the Mac's server re-exports the whole app rather than a subset:
- The sandbox's own tools — 313 of them, generated from the agent's
own table. Cloud workspace groups the families
a caller plans around: waiting on output, background work, command history,
editing, undo of the agent's own writes, page assertions, and replay.
image_generateis among them, and is paid in credits. - The control plane — 16 tools:
workspace_status/_start/_stop/_quota,job_*for scheduled jobs,key_*for the credentials injected into the box, andagent_credential_*. These live at the edge because the box can't provide them: a sandbox can't start itself, and quota is an account fact. Credentials are write-and-name-only — nothing reads a secret back out.
Running Claude Code or Codex inside the box is what most callers come for, and it has its own tools:
agent_start {agent: "claude" | "codex", prompt, cwd}opens a pane running the agent with the prompt already submitted (it goes on the command line, single-quoted), and returns the screen once it settles.agent_send {pane_id, message}types a follow-up and presses Enter as a separate keystroke. In those programs a newline typed with the text inserts a line instead of submitting, which is why the old recipe neededterminal_press_enter. An empty message just presses Enter.agent_read {pane_id, wait_s}checks on it, optionally waiting until it has finished.
agent_start says signed_in: false, and names the fix, when the agent has no
credential here. It reports a folder-trust question (waiting_for: "trust")
without answering it, because trusting a folder lets its own settings and hooks
run. Panes it opens are labelled "via Claude Code" (the connection's name) in
the workspace sidebar. For one-shot work, spawn_and_read or
run_background_job with claude -p "…" / codex exec "…" still work.
Signing the agents in is one place: the Agents card at the top of the
workspace's Keys tab (and in the Connect dialog), or agent_credential_set.
- Claude Code is installed when the box boots. The Claude credential
(
claude setup-token's output) is the one scheduled jobs and the Agent tab use, and it is also pushed into panes asCLAUDE_CODE_OAUTH_TOKEN, unless the vault has its ownCLAUDE_CODE_OAUTH_TOKENorANTHROPIC_API_KEY. - Codex installs itself the first time
codexruns on a box. It's ~370 MB, too much to pay on every cold boot. Its credential is the vault'sOPENAI_API_KEY: with that and no~/.codex/auth.json, it logs in with the key. An existing login (a ChatGPT device-auth one, say) is left alone. - Changes reach a running box straight away. Panes opened afterwards see them; panes already open keep the environment they started with.
What the endpoint costs, and when:
- Connecting costs nothing. The edge answers
initialize,pingandtools/listitself, so an editor that connects at startup never boots a sandbox. The box's half of the list comes fromsite/lib/box-tool-manifest.json, generated from the agent's own table bysite/scripts/box-tool-manifest.mjsand held to it by a test. It used to be fetched from the box, and on a stopped box that returned the control plane alone, which the client then kept for its whole session. - The first box tool call starts the workspace if it's stopped: the same
gate, meter and key push as
workspace_start, about a minute from cold. A box that is already running is used as it is, even if its agent is an older build. Upgrading would restart every pane on it.workspace_statusreportsagentAnsweringandagentReadyseparately, andworkspace_startupgrades. - Using it keeps it alive. Box calls count as the heartbeat an open tab
sends (at most once a minute): minutes accrue and the box's idle
deadline is pushed out. After the last call it stops on its own within
about 10 minutes. A call that fails, including an out-of-credits start, comes
back as a tool result with
isErrorrather than a protocol error, so the model can read why.
Access is gated by canUseWorkspace(), which the WORKSPACE_OPEN=true
environment variable opens — an env var rather than a code change, because
this decides who can spend money. Admins keep access regardless.
Minutes bill against Cred credits, and with
WORKSPACE_BILLING_ENFORCE=true the credit balance is the ceiling: a start
is refused only when the balance is empty. The older monthly minute cap
(WORKSPACE_MINUTES, default 600/month/account) applies when billing is not
enforced, or when the variable is set explicitly as a hard stop.
Source pointers
- Tool catalog —
AgentToolName.swift - Tool schemas —
AgentToolDefinitions*.swift(split by family) - Socket, launcher and dispatcher —
AgentMCPServerBridge.swift(++Dispatch,+ToolExecution,+Clients) trmnly mcp-bridge—TrmnlyCLIClient.mcpBridgeinTrmnlyCLIClient.swift- HTTP / SSE / attach / LAN listener —
AgentMCPSSEServer.swift - Client folder → project —
AgentMCPConnectionScope.swift - Settings pane —
MCPClientsSection.swift; client registration inAgentExternalClientRegistry.swift - Resources and prompts —
AgentMCPResources.swift,AgentMCPPrompts.swift - Inbound servers —
AgentMCPProvider.swift,AgentMCPHTTPServer.swift(URL servers) - Portable core server —
trmnly-core-mcp/main.swift,MCPStdioServer/MCPSocketServerinTrmnlyCore - Claude Code skills —
claude-skill/(the markdown itself ships in the app bundle;AgentSkillInstaller.swiftcopies it into~/.claude/skills/) - Approval policy —
AgentMCPApprovalPolicy.swift - Schema versioning —
AgentMCPSchemaValidator.swift - Cloud endpoint —
site/app/api/mcp/route.ts, transport rules insite/lib/mcp-http.ts, control-plane tools insite/lib/mcp-edge-manifest.ts - Cloud sandbox tools —
site/workspace-agent/tools.mjs