From clone to couch in eight steps.

1 · Check the requirements

• Node.js 22.12 or newer within the 22.x line, or 24.x. Node 22.12 specifically needs NODE_OPTIONS=--experimental-sqlite; 22.13+ and 24 do not.
• pnpm 10.15 or newer, through Corepack.
• tmux 3.x, which is what makes the workspaces durable. Helioterm manages it for you.
• macOS for the v0.1 candidate. Linux, Docker, and standalone binaries are later packaging tracks.
• Tailscale CLI, only if you want private phone or laptop access through your tailnet.

2 · Build and serve

From the repository root, build everything and start the daemon. It serves the browser UI and the API from one localhost port.

$ corepack enable
$ pnpm install
$ pnpm build
$ CMUXD_REMOTE_PATH=/path/to/verified/cmuxd-remote \
  CMUX_WEB_AUTH_TOKEN="$(openssl rand -hex 24)" \
  pnpm helioterm serve

Then open http://127.0.0.1:4020. The daemon binds literal 127.0.0.1 and nothing else; there is no flag that opens it to your LAN or the internet.

3 · Log in

On first run the daemon creates a local signing secret on disk. The CMUX_WEB_AUTH_TOKEN you exported above is a bootstrap secret: paste it into the login screen once, and the browser gets an opaque, HttpOnly, SameSite=Strict cookie session. The browser never holds a JWT, and the token is never stored by the browser app or put in a URL.

Additional devices pair with short-lived, single-use codes instead of the raw token, and any paired device can be revoked later. Revocation closes that device's live sockets immediately.

Auth state, meaning the signing secret and the paired-device records, lives under ~/.cmux-web by default; set CMUX_WEB_STATE_DIR to move it.

4 · Understand the terminal sidecar

Live terminal bytes flow through an external cmuxd-remote process that you install separately and point at with CMUXD_REMOTE_PATH. Helioterm does not bundle, download, or patch it; it stays a separate external process under CMUX's own license terms.

Without the sidecar configured, the daemon still serves the control plane and the UI. Attaching a terminal simply returns 503 until a verified sidecar path is provided, so you can explore the workspace before wiring up the data plane.

$ helioterm doctor
# reports runtime, tmux, auth, and sidecar status

5 · Go remote, privately

Keep the daemon on loopback and let Tailscale Serve proxy the port to your tailnet, encrypted in transit over your tailnet. Helioterm will print the exact command rather than touching your Tailscale config for you.

$ helioterm tailscale setup
$ tailscale serve --bg http://127.0.0.1:4020

For browser access under your MagicDNS hostname, start the daemon with --allow-tailscale-hosts. That resolves this machine's exact tailnet hostname and allow-lists it, never a *.ts.net wildcard. App auth still applies: being on the tailnet or carrying Tailscale identity headers never creates a session.

Two things stay deliberately manual. Funnel, which is public internet exposure, fails with a warning unless you pass an explicitly dangerous flag. And helioterm tailscale status shows what is currently exposed.

Got several machines? Run a daemon on each and reach every one at its own tailnet name. There is no cross-machine pane.

6 · Browse files, read-only

The Files view is a WinSCP-style explorer for the workspace: browse directories, create folders, rename, and delete, with deletes jailed to the workspace root. Viewers for code, markdown, and git history open files up to 512 KiB.

The built-in viewers are read-only. You can optionally configure a separately installed Druk terminal editor with --druk-path or HELIOTERM_DRUK_PATH. It opens in a managed tmux tab; Helioterm does not download or bundle it. Editing there changes the workspace file.

7 · Install it as an app

The web app ships a PWA manifest with standalone display, so once you can reach it from a device you can install it like an app:

• iOS Safari: open your Serve URL, share sheet, then Add to Home Screen.
• Android Chrome: open the URL, browser menu, then Install app.
• Desktop Chrome: the install icon in the address bar.

On a touch screen you get quick keys for Ctrl, Esc, Tab, and arrows; on desktop they stay out of the way unless you turn them on. Mobile behavior is built and tested for mobile browsers with automated checks emulating Pixel 7, iPhone 13, and iPad Mini.

Note the deliberate boundary: the app registers no service worker, so nothing about your terminals is cached for offline use. The install is a window, not a copy.

8 · Daily commands

$ helioterm serve
$ helioterm doctor
$ helioterm --version
$ helioterm tailscale status
$ helioterm tailscale setup
$ helioterm tmux migrate-legacy --dry-run

That last one inspects pre-Helioterm tmux sessions for adoption without changing anything. Sessions the app creates are stamped @helioterm_managed; destructive operations refuse anything without the stamp, so your hand-made tmux stays yours.

Agent sessions need no setup at all: anything running claude, codex, opencode, or openclaw is typed automatically and flagged when it waits on you.