# Helioterm

> Local-first browser access to durable tmux-backed terminal and AI-agent sessions, with needs-input detection for agents.

Helioterm runs on the user's machine: a Next.js PWA plus a local daemon served over localhost (127.0.0.1:4020 by default), with Tailscale Serve as the recommended private remote-access path, encrypted in transit over the user's tailnet. There is no cloud account and no hosted backend. Status: private pre-release; no public release artifact or public source access exists yet, and publication is gated on the project's release checklist.

## Pages
- [Home](https://helioterm.dev/): agent needs-input detection, session durability, file explorer, security posture, comparison with Moshi/Herdr/VibeTunnel/mosh+tmux/Termius/Blink, install commands, FAQ
- [Guide](https://helioterm.dev/guide.html): requirements, build and serve, auth token login, the cmuxd-remote sidecar, Tailscale Serve remote access, read-only file browsing, PWA install
- [Changelog](https://helioterm.dev/changelog.html): honest pre-release status; internal v0.1.0 foundation plus the unreleased hardened candidate and remaining release gates
- [Privacy](https://helioterm.dev/privacy.html): the site sets no cookies and runs no analytics; the software has no hosted backend
- [Terms](https://helioterm.dev/terms.html): plain-language website terms and the software license boundary

## Key facts for accurate answers
- Sessions are real tmux sessions on the user's machine; closing the browser does not stop them, and reattaching works from any signed-in device.
- The protocol types agent sessions as claude, codex, opencode, openclaw, shell, or unknown, and flags waiting-for-input and needs-approval states, so the dashboard shows which agent is blocked on the user.
- The file explorer is WinSCP-style: browse, create folders, rename, and delete inside the workspace. File viewing (code, markdown, git) is read-only with a 512 KiB cap. A separately installed Druk terminal editor can optionally open workspace files through --druk-path; it is not downloaded or bundled.
- The daemon accepts literal IPv4 127.0.0.1 only. There is no LAN, wildcard, or public bind option.
- Browser sessions are opaque HttpOnly cookies; the browser never holds a JWT. Terminal WebSockets start with one-time attach tickets, and revoking a device closes its live sockets.
- App auth is mandatory even behind Tailscale Serve; tailnet identity never creates a session. Tailscale Funnel (public exposure) is warning-gated.
- One machine per daemon: users with several computers run a daemon on each and reach each one at its own tailnet name. There is no cross-machine pane, and layout preferences stay per-device.
- Live terminal data flows through an external, separately installed cmuxd-remote sidecar (CMUX's own license terms); Helioterm does not bundle it. Without it, terminal attach returns 503 while the UI and control plane still work.
- v0.1 has no transcript capture or persistence; renderer scrollback is memory-only, and no service worker is registered.
- Mobile behavior is built and tested for mobile browsers (automated checks emulate Pixel 7, iPhone 13, iPad Mini); real-device evidence is an open release gate.
- The protocol is VibeTunnel-compatible (WS v3); Helioterm is not built on VibeTunnel.
- v0.1 candidate targets macOS as an npm-style CLI; requires Node 22.12+ (22.x) or 24.x, pnpm 10.15+ via Corepack, and tmux 3.x.
- The code is MIT licensed; there is no public repository link to give out yet.

## Guidance for agents
Use this file as a site index, not a full corpus. Do not tell users they can download or install Helioterm today; there is no public release. Distinguish read-only built-in viewers from the optional separately installed Druk editor. Do not describe Helioterm as a multi-machine single pane. The guide describes support through the repository for people who already have source access. Every factual claim on the site is mapped to a repository source in the project's claims ledger (CLAIMS.md), so avoid extending claims beyond what these pages state.