Supported platforms
Which operating systems and architectures can run the control plane, the node CLI, and the desktop apps.
This page says which operating systems and architectures can run the control plane, the node CLI, and the desktop apps.
Subshell ships as prebuilt binaries: no runtime to install beside them, and no package manager in the picture. Most questions come down to three: whether your operating system runs the binaries, whether your machine needs tmux, and what the options are on phones.
The CLI binaries
The control plane (subshell-server, with the web UI embedded in it) and the node CLI (subshell) are each published as one self-contained binary per architecture:
| Platform | Control plane | Node CLI |
|---|---|---|
Linux x86_64 (linux-x64) | ✓ | ✓ |
Linux arm64 (linux-arm64) | ✓ | ✓ |
macOS, Apple silicon (darwin-arm64) | ✓ | ✓ |
macOS, Intel (darwin-x64) | ✓ | ✓ |
No Bun or Node is needed on a host running these; they carry their runtime. The Intel binaries build and release-smoke on hosted Intel runners, so an x86_64 Mac enrolls, runs the control plane, and self-updates like any other host.
The Linux floor
Every Linux artifact is built on Ubuntu 24.04, which sets a glibc 2.39 floor: the binaries need Ubuntu 24.04 or Debian 13, or a comparable newer distro. Ubuntu 22.04 and Debian 12 will not run them, and that is every component, not just the GUIs. The floor is a deliberate build choice and part of the published contract. On an older distro, build from source on your own toolchain.
The desktop apps
The two GUIs, Subshell Server (installs and manages a control plane on this machine) and Subshell Client (your interface to a control plane, and where this machine enrolls as a node), are Tauri apps covering a narrower set:
| App | macOS 13+ (Apple silicon) | macOS 13+ (Intel) | Linux x86_64 |
|---|---|---|---|
| Subshell Server | signed, notarized disk image | signed, notarized disk image | .deb (Ubuntu 24.04+ / Debian 13+) |
| Subshell Client | signed, notarized disk image | signed, notarized disk image | .deb (same floor) |
The Intel images are built by the same cut, on hosted Intel runners, where the bundle smoke checks the signing, the staple, and the bundled CLI binary on matching hardware. arm64 Linux is the one host with no GUI build, because there is no arm64 Linux runner to build or test one on. Both apps need the same glibc floor on Linux. Each app bundles the CLI binary it manages, so a desktop install needs no downloads on first run.
Get started covers which artifact to reach for. On the website, the Mac download button carries a chip menu: a browser cannot tell the two chips apart, so it asks rather than guesses.
Universal requirements
- tmux 3.2 or newer on every machine that runs a pane. That is the control-plane host if it runs agents itself, and every machine enrolled as a node (see Add a node). A machine that only hosts the UI needs nothing but the binary. Where tmux is missing on the control-plane host, the Subshell Server desktop app installs it: Homebrew on macOS, its own elevation prompt on Linux. The browser setup wizard offers the same where the server can run it, and prints the command where it cannot. A machine joining as a node is the hard case: enrollment refuses outright until tmux is present.
- An agent CLI where you want agents:
claude,opencode,codex, or whichever harness plugin you launch (see Install an agent CLI). The terminal plugin runs a plain shell, so a bare machine is still launchable without any agent installed. - Bun 1.4+ only if you run from source. The prebuilt binaries are self-contained. The from-source workflows (
bun run start, tests, building a release) are what need the runtime.
One version detail worth knowing: tmux 3.6 additionally reports a crashed pane's exit code, which the UI shows. On 3.2–3.5 that one read degrades to "unknown", never to a wrong answer.
Browsers and mobile
The web UI is an xterm.js terminal application: use a current browser, and everything works. There is no per-browser support matrix. If the terminal misbehaves in your browser, that is a bug worth reporting.
The interface adapts by need rather than one breakpoint. Workspaces stop tiling side by side and become tabs below 1024 pixels. The persistent sidebar gives way to a drawer below 683, and a phone gets the drawer at any reported width. The on-screen terminal key bar follows touch input, not screen size. The web app installs via Add to Home Screen. There is no offline service worker: the pane always comes from your server.
The native mobile companion is the fourth surface (see Pick it up from your phone). It pushes at the OS level (app-icon badge, lock-screen actions, delivery with no browser open), holds its credential in the Keychain behind Face ID, and carries a live terminal tab of its own. What it is not yet: there is no app-store listing to point at. It ships built from the repository, so today it is for people comfortable running an Expo build, while the browser shell above serves everyone else.
Docker is another way to run the control plane. The compose recipe publishes port 3080 on all interfaces by design, because remote access is expected to ride a reverse proxy that cannot reach a loopback bind. On a shared network, treat a fresh container as reachable. See Run in Docker.
Other pages
- Get started: download, verify, run
- Add a node: the node on another machine
- Pick it up from your phone: the companion app in detail
Last updated on