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, andworktree_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_*anddry_run_*families, the notebook and git tools,edit_file,apply_patch,symbol_search, theaccess_key_*vault, thegh_pr_*andports_*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. Seespecs/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 onPATH, and its status line says what is left of the account's allowance (read throughusage_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 runningssh <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).
- Agent — a persistent MCP session against
- 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 throughRegisterHotKey. A chord another application already holds is refused by name, and the rest still register. - The Claude Code integration — the per-project
TRMNLY.mdguide and the skill bundle. That installer is Foundation-only and lives in the core, so the same code serves the Mac app andtrmnly-core-mcprather 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:
- The GTK you build against silently becomes the artifact's runtime floor,
because
gtk_version.atLeastcompiles out to comptime-false against older headers.fedora:43supplies GTK 4.20, so today's build has the highest possible floor and nothing in it says so. libgtk4-layer-shell.so.0is a hardDT_NEEDEDthat 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 byAgentToolPlatformTests - 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/