All pages

Docs · Start here

Platforms — what runs where

Availability: all hosts.

TRMNLY is no longer one application. It is one product with four hosts, and they do not have the same features. Every other page in this directory opens with an Availability line; this page is what that line points at.

Host What it is State
macOS app The full product — terminal, sidebar, agent, all 428 tools Ships — notarized DMG + Sparkle
GTK app The same source built for Linux and Windows: terminal, splits, tabs, and a four-pane sidebar Builds, starts, and now runs on 5 of 5 tested distributions; flatpak still the shipping answer
trmnlyd Headless daemon whose panes outlive the client that started them Builds and tests on macOS and Linux. Its Windows path is written and gated but has never been compiled
Cloud workspace A per-account Linux sandbox behind trmnly.dev, driven over MCP or the web terminal Live, gated on account access

The iOS app is a client, not a host: it pairs to trmnly.dev and drives the Mac over MCP-on-tunnel. See Remote control.

The rule the whole thing rests on

One implementation of the logic, several front-ends. No feature is ported by copying it. The agent loop, the providers, the tools and the MCP surface live in Swift (TrmnlyCore), and every non-macOS front-end is a client of that core rather than a second implementation of it. A Linux feature that is a copy of a macOS feature diverges permanently within a month, so the arrangement is enforced by a Linux build gate rather than by discipline.

That is why the GTK sidebar's Agent pane is an MCP console and not an agent: the pane spawns trmnly-core-mcp, holds the session open, and calls tools on it. See docs/LINUX-PORT.md for the argument in full.

Tool availability

Each of the 428 tools declares what it needs from its host (ToolPlatform), and a host advertises only the tools it can honor. The filter is on the schema, not the error message — a model that is never shown ax_dump never plans around it, where a model shown a tool that always fails will retry it and burn a turn.

Tier Tools Needs Advertised on
universal 140 A filesystem and a shell macOS app, GTK app, trmnlyd
terminalPane 46 A terminal pane macOS app, GTK app, trmnlyd
browserEngine 144 The in-app browser (WebKit, or Chrome driven over DevTools — Browser) macOS app
macOSDesktop 29 Accessibility, AppleScript, synthetic input, the pasteboard macOS app
macOSApp 69 The app's own UI or a macOS-only subsystem macOS app

So the macOS app offers all 428; the GTK app and trmnlyd each advertise 186. browserEngine joins the non-macOS hosts when the CDP backend lands, at which point Linux and Windows gain it together — they are the same build. macOSDesktop and macOSApp are dropped rather than ported.

The cloud workspace is not in this table. It is a separate JavaScript implementation that reuses the tool names deliberately, so it is not filtered by these tiers and its inventory is its own — see below.

Advertised is not the same as executed. The portable core advertises 186 tools and currently executes 89 of them. The rest answer with a structured "not implemented on this host yet" rather than a wrong result, and name the set that does work — so a model can tell a gap from a typo.

Those 89 arrive two ways, and the difference matters more than the number:

  • 13 written against Foundation here — read_file, write_file, list_dir, glob, grep, bash, git_status, git_diff, git_log, and worktree_list / _create / _remove / _adopt. These stay hand-written because they genuinely differ without an app.
  • 76 that are the macOS app's own implementation, running here — the notes_*, kanban_*, chat_*, lsp_* and dry_run_* families, the notebook and git tools, edit_file, apply_patch, symbol_search, the access_key_* vault, the gh_pr_* and ports_* families and friends, from the same files the Mac dispatches, symlinked into the package. This is the pattern the rest of the gap closes with: a tool group moves as a unit rather than being written a second time. See specs/linux-product-parity/.

The tier table above is the ceiling, not today's inventory.

Where the app and the core disagree, the app is right and the core is the subset. Tool names and argument shapes are deliberately identical, so a prompt written against the Mac works against the core, and the core advertises the same full descriptions and argument schemas as the Mac for the board, notes, chat, git, file, code-intelligence and port families — not just names — so an agent there plans a call the same way.

The GTK app (Linux and Windows)

One build, two targets. Since the route change on 2026-09-03, Windows is not a separate port: it is the GTK app cross-compiled, so a feature that lands in src/apprt/gtk/ lands on both at once.

What it has today:

  • The terminal, splits, tabs, and the command palette — inherited from Ghostty's GTK apprt, which is a real GTK4/libadwaita application, not a stub.
  • The TRMNLY sidebar, open by default, toggled from the header bar button or win.toggle-trmnly-sidebar. Seven pages:
    • Agent — a persistent MCP session against trmnly-core-mcp, with a tool console. Reports the core offline if the binary isn't on PATH, and its status line says what is left of the account's allowance (read through usage_read, so it needs no Mac).
    • Files — a directory tree you can walk; activating a file opens a preview (Files).
    • Conn — the hosts in ~/.ssh/config; activating one opens a new tab running ssh <host>. This reads the SSH config directly, not TRMNLY's saved-host store, which is macOS-only.
    • Notes — a scratch pad, capped at 1 MiB, autosaved.
    • Tasks — the project's board, with a Free button for a card an agent left claimed (Kanban).
    • Review — notes on the working diff, handed to the agent as one message (Review).
    • Account — who is signed in, and the GitHub status (Account).
  • The floating pane — win.toggle-float-pane.
  • Quick Terminal — on Wayland, through gtk4-layer-shell, and on Windows, through an always-on-top toplevel. Not on X11, which says so in a warning at startup.
  • System-wide keybinds (global: in the config) — on Linux through the XDG desktop portal, on Windows through RegisterHotKey. A chord another application already holds is refused by name, and the rest still register.
  • The Claude Code integration — the per-project TRMNLY.md guide and the skill bundle. That installer is Foundation-only and lives in the core, so the same code serves the Mac app and trmnly-core-mcp rather than being written twice.

What it does not have: everything in the macOSApp and macOSDesktop tiers, and the browser sidebar. That is not a backlog — those are dropped by design. See LINUX-PORT.md § "Out of scope for the core".

Building it, from a Mac, with no Linux or Windows machine involved:

./scripts/linux-gui-build.sh      # Linux GUI, via Docker (fedora:43)
./scripts/windows-gui-build.sh    # the Windows app + its runtime, via MSYS2
./scripts/windows-core-build.sh   # libghostty DLLs for Windows
./scripts/core-swift-linux.sh     # TrmnlyCore under the Linux toolchain

windows-gui-build.sh leaves a directory at zig-out/windows-gui/dist that can be copied to a Windows machine and started from trmnly.cmd: the executable, the transitive closure of every DLL it imports, the compiled GSettings schemas, the Adwaita and hicolor icon themes, and the gdk-pixbuf loaders. It is a ReleaseSafe build.

That list is not padding — it is what the build produced nothing of until 2026-09-10, when the output was a bare ghostty.exe that could not start on any machine, because it links the GTK stack dynamically and Windows ships none of it. A build that cannot start reads as a broken port rather than as an unpackaged one.

There is no shippable artifact yet, and on Linux the gap is not a packaging chore. Two independent traps, both measured rather than assumed, and both specific to Linux — a Windows build brings its own GTK from the MSYS2 sysroot and never links layer-shell at all:

  1. The GTK you build against silently becomes the artifact's runtime floor, because gtk_version.atLeast compiles out to comptime-false against older headers. fedora:43 supplies GTK 4.20, so today's build has the highest possible floor and nothing in it says so.
  2. libgtk4-layer-shell.so.0 is a hard DT_NEEDED that almost no distribution packages, so the process fails to start even where the library is never called.

A CI-produced tarball measured against five distributions started on one. Flatpak (Linux) and MSIX (Windows) are the durable answer; a distro matrix is a pre-merge gate, not a distribution strategy.

On Windows the open question is different, and larger. The build now produces a complete, branded, ReleaseSafe layout — and nothing in it has ever been run. Whether GTK4 on Windows is usable — IME, per-monitor DPI, window decorations — is the assumption the whole route rests on, and neither compiling nor packaging says anything about any of it.

Three pieces of Windows behaviour are written and gated and have never met a compiler's opinion of Windows, let alone a running one: the winproto win32 arm (supportsQuickTerminal, always-on-top placement, FlashWindowEx), the RegisterHotKey path behind global shortcuts, and trmnlyd's ConPTY half. Treat all three as reviewed drafts. Full detail, and what a green build still does not prove, is in LINUX-PORT.md Tier 0 and WINDOWS-PORT.md.

trmnlyd — the headless daemon

The problem it solves: today every durable thing TRMNLY owns lives inside one macOS process on one machine. Agents die with the app, panes die with the app, and session restore replays layout, not live processes.

trmnlyd owns the PTYs instead, so panes outlive the client. A client attaches over a Unix socket using the frame protocol in specs/attach-protocol/, gets live output, encoded input and resize, and a re-attach shows the current screen rather than a blank pane. Both the macOS app and the daemon implement the same contract, so one client talks to either without knowing which it reached.

trmnlyd                        # serve on the default socket
trmnlyd --socket /path.sock    # serve elsewhere
trmnlyd --spawn <cmd...>       # serve, with one pane already running
trmnlyd --print-token          # print the device token and exit

Trust differs by platform, deliberately. On POSIX the socket's 0700 directory and 0600 mode are the boundary and no token is used. On Windows, AF_UNIX takes its protection from the directory ACL, which nothing sets — so the daemon authenticates its own local socket with a device token rather than claiming a mode bit it never applied. Advertising [.universal, .terminalPane], it is a host with real panes and no desktop.

The Windows half is a reviewed draft, not support. ConPTY instead of forkpty, AF_UNIX with WSAStartup, token auth — all written, all gated behind #if os(Windows), and none of it ever compiled, because no Swift Windows toolchain is reachable from a Mac. It was written from a working reference (src/pty.zig and src/Command.zig transliterated into C) so that whoever has a Windows box starts from a citation rather than from nothing. Details, including the three places a first run will most likely break, are in WINDOWS-PORT.md.

The cloud workspace

A per-account Linux sandbox behind trmnly.dev, reachable three ways: the web terminal, the desktop app's Settings, and a public MCP endpoint that needs no Mac at all.

claude mcp add --transport http trmnly-cloud https://trmnly.dev/mcp

It opens the browser to approve the connection; there's no token to paste.

It exposes the union of two halves: ~300 tools on the box (files, grep, bash, git, the browser, the pane family, chat, kanban, notes) and 15 control-plane tools at the edge (workspace_*, job_*, key_*, agent_credential_*, project_*_github) — the ones a sandbox cannot provide for itself, because a box can't start itself and quota is an account fact. A connected agent can launch Claude Code or Codex inside the box; see MCP server.

Names match the desktop's on purpose, but this is a separate implementation in JavaScript, not the Swift core, so the overlap with the tier table above is by convention rather than by construction. Where a name exists on both, treat the desktop as the reference shape.

Access is gated by canUseWorkspace() — open it with WORKSPACE_OPEN=true, an env var rather than a code change, because it decides who can spend money — and workspace minutes bill against credits. Full detail in MCP server.

Distribution

Host Install Updates
macOS Notarized DMG (dist/macos/release.sh) Sparkle, trmnly.dev/updates/{stable,tip} — see Updates
Linux ./scripts/linux-floor-build.sh --artifact — a tarball that starts on ubuntu 24.04/25.04, debian 13, fedora 41/43. Flatpak manifests exist (flatpak/) None yet
Windows Build locally — zig-out/windows-gui/dist, copy and run trmnly.cmd. No signing needed for that. MSIX packaging is written (dist/windows/package.ps1); publishing it needs the Store or Azure Trusted Signing — see WINDOWS-PORT.md App Installer channel written, nothing published
Cloud Nothing to install Redeploys with the site

The Linux and Windows release pipelines are blocked on CI: GitHub Actions is turned off for this repository, so the flatpak workflow cannot run. Until it is back on, those artifacts come from a local or Docker build.

What is deliberately not being ported

Named so nobody spends a week on one of them by accident:

  • The SwiftUI views. 600-plus files bound to AppKit types will not survive a binding layer; that path looks like reuse and delivers a rewrite with extra indirection.
  • The browser sidebar as it exists — WebKitGTK is a different API. The non-macOS answer is a CDP backend behind identical schemas.
  • The plugin engine — JavaScriptCore isn't on Linux. QuickJS, or plugins out-of-process under node/bun.
  • GhosttyKit — the embedded apprt C API. On the GTK side containment is inverted: GTK owns the window and the sidebar is a widget.
  • Agent features written in Zig. Every one of those is a second codebase.

Source pointers

  • Tier definitions — ToolPlatform.swift
  • Per-tool classification — AgentToolName+Platform.swift, pinned by AgentToolPlatformTests
  • What the core can execute — PortableToolExecutor.swift
  • The GTK sidebar — src/apprt/gtk/class/trmnly_sidebar.zig
  • The port plans — LINUX-PORT.md, WINDOWS-PORT.md
  • Specs — specs/linux-gui/, specs/windows-port/, specs/headless-daemon/, specs/attach-protocol/, specs/core-tool-executor/