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 single event: message on a text/event-stream.
  • GET /sse — a long-lived event stream (resource updates, approvals); send Last-Event-ID on 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 as trmnly://tab/<uuid>/dom, /screenshot, /console and /network. resources/subscribe pushes notifications/resources/updated over SSE when one changes.
  • prompts/* — verify_pr_preview, a scripted navigate → wait → screenshot → console-drain pass over a preview URL.

Turn it on

  1. 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-bridge launcher 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.

  2. 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 bash or send_keys comes 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:

  1. the tool call's own project_id / project_name
  2. the client's working directory, when it is inside a project TRMNLY knows (a worktree folder binds the worktree too)
  3. 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
  4. 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 the read_secrets capability.
  • 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 npx or node looked up in /opt/homebrew/bin, /usr/local/bin, /usr/bin and /bin — never your shell's PATH, which a project's node_modules/.bin could put first. The command's own folder leads the child's PATH, so npx finds the node beside it. The child gets only PATH, HOME, locale and TMPDIR from TRMNLY's environment, plus the env you give it.
  • URL — a hosted server over Streamable HTTP (one endpoint, POSTed JSON-RPC, replies as JSON or SSE, Mcp-Session-Id kept and renewed when the server drops it). HTTPS only, except http://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.dev hands 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_capabilities reports the verdict per tool before you try.
  • $TRMNLY_SOCKET_TOKEN and _meta.trmnlyCwd are 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_ROOT or its working directory. --socket PATH serves a Unix socket instead, which is what the GTK app starts so every pane's trmnly reaches it through $TRMNLY_SOCKET_PATH; --exit-with-parent [PID] stops it when the app is gone. --host gtk changes only how an unavailable tool explains itself.
  • On start it installs the same skills into ~/.claude/skills, less the macOS-only trmnly-desktop (skip with --no-skills), and --setup-project DIR writes TRMNLY.md and the @TRMNLY.md line into CLAUDE.local.md, then exits. $TRMNLY_MCP_SERVER_NAME retargets the mcp__<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_generate is 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, and agent_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 needed terminal_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 as CLAUDE_CODE_OAUTH_TOKEN, unless the vault has its own CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.
  • Codex installs itself the first time codex runs on a box. It's ~370 MB, too much to pay on every cold boot. Its credential is the vault's OPENAI_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, ping and tools/list itself, so an editor that connects at startup never boots a sandbox. The box's half of the list comes from site/lib/box-tool-manifest.json, generated from the agent's own table by site/scripts/box-tool-manifest.mjs and 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_status reports agentAnswering and agentReady separately, and workspace_start upgrades.
  • 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 isError rather 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.mcpBridge in TrmnlyCLIClient.swift
  • HTTP / SSE / attach / LAN listener — AgentMCPSSEServer.swift
  • Client folder → project — AgentMCPConnectionScope.swift
  • Settings pane — MCPClientsSection.swift; client registration in AgentExternalClientRegistry.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 / MCPSocketServer in TrmnlyCore
  • Claude Code skills — claude-skill/ (the markdown itself ships in the app bundle; AgentSkillInstaller.swift copies it into ~/.claude/skills/)
  • Approval policy — AgentMCPApprovalPolicy.swift
  • Schema versioning — AgentMCPSchemaValidator.swift
  • Cloud endpoint — site/app/api/mcp/route.ts, transport rules in site/lib/mcp-http.ts, control-plane tools in site/lib/mcp-edge-manifest.ts
  • Cloud sandbox tools — site/workspace-agent/tools.mjs