Agentboard: a tmux web GUI built for agent TUIs, not general terminals
Web GUI for tmux optimized for AI agent TUIs, with support for iOS safari and mac w/ keyboard shortcuts
At a glance
- What is it?
- Agentboard puts a React and xterm.js front end in front of tmux, then adds agent-specific plumbing: JSONL log parsing, status inference, hibernation and an iOS Safari input layer. It is a single-user remote control for coding agents, not a general terminal replacement.
- Who is it for?
- Adopt Agentboard if you already run Claude, Codex or Pi inside tmux on a machine you can reach over Tailscale or LAN, and you want to check on or drive those sessions from an iPhone without installing a terminal app. Do not adopt it as a general SSH client, as a multi-user service, or if you cannot run tmux on the host.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Agentboard targets: agents that outlive the terminal you started them in
Agent TUIs such as claude and codex are long-running interactive processes. You start one in a tmux window, walk away, and later want to know whether it is still working, waiting for input, or blocked on a permission prompt. A plain SSH client answers none of those questions without attaching and reading the screen. Agentboard's answer is a server that polls tmux, reads agent logs, infers a status per session, and streams the pane over a WebSocket to a browser. The README describes it as a lighter-weight, agent-optimized alternative to Blink and Termux, which places it in the mobile-terminal category rather than the terminal-multiplexer category. The intended user is one person with a desktop or server running agents and a phone or laptop they want to check in from. The shared workspace across devices is the point: the same tmux session is visible and drivable from either device.
How the pieces fit: tmux CLI, agent JSONL logs, and a WebSocket terminal
The architecture diagram in the README shows three input paths feeding an Agentboard server, which then talks to a React and xterm.js browser client over a WebSocket. The first path is the local tmux CLI, used to discover sessions and windows. The second is SSH to remote hosts, used for the same discovery when the agents run elsewhere. The third is reading agent logs directly from disk, shown in the diagram as ~/.claude/. Status inference then combines two signals: pane content and Claude or Codex JSONL logs. The README states the output is a classification of working, waiting for input, or asking for permission. That is a heuristic, not a protocol. Anything that changes the shape of those logs or the on-screen prompts can degrade the classification, and the README does not describe a stable contract with the agents it parses. Log tracking is listed as out-of-the-box for Claude, Codex and Pi, with automatic matching of sessions to active tmux windows. The sidebar also surfaces the last user prompt per session, which is a small feature that matters more than it sounds: it is the difference between a list of opaque window names and a list you can triage at a glance.
Install paths: Homebrew, npm, or Bun from source
Three install routes are documented. Homebrew uses brew tap gbasin/tap, brew install agentboard, then agentboard. npm uses npm install -g @gbasin/agentboard followed by agentboard, or npx @gbasin/agentboard to run it without a global install. Both land on http://localhost:4040, or http://<your-machine>:4040 from another device. Building from source requires Bun 1.3.14 or newer, per the README, and the flow is bun install, bun run dev, then opening http://<your-machine>:5173 for the Vite dev server. Production builds use bun run build followed by bun run start, and the README notes that in production the UI is served from the backend port, default 4040. Persistent deployment is documented separately in systemd/README.md for Linux and launchd/README.md for macOS. tmux is a hard requirement, installed via brew install tmux or apt install tmux, and Tailscale is recommended but not mandatory since any network path to the machine works. The environment block is where most configuration lives. PORT and HOSTNAME control the listener; the README states HOSTNAME defaults to 127.0.0.1 for localhost-only, that Tailscale detection causes the server to also bind to the Tailscale IP automatically, and that 0.0.0.0 listens on all interfaces. It also warns that a HOSTNAME equal to the machine hostname is treated as auto-exported by the environment and ignored. TMUX_SESSION selects the tmux session name, REFRESH_INTERVAL_MS defaults to 5000, and AGENTBOARD_REMOTE_HOSTS takes a comma-separated list such as mba,carbon,worm with its own poll, timeout and stale thresholds. AGENTBOARD_REMOTE_ALLOW_ATTACH and AGENTBOARD_REMOTE_ALLOW_CONTROL both default to false, which means remote hosts are read-only until you opt in.
Hibernation, history, and the database file
Hibernating sessions are a distinct concept here. The README says hibernating closes a session's tmux window while keeping it visible across restarts for manual Wake, and that startup does not auto-wake dormant sessions. That is a deliberate choice: restarting the Agentboard server will not spawn a fleet of agent processes you had parked. The one-click Wake for Hibernating and History sessions is the recovery path. State lives in AGENTBOARD_DB_PATH, defaulting to ~/.agentboard/agentboard.db, and AGENTBOARD_INACTIVE_MAX_AGE_HOURS defaults to 24, which governs how long inactive entries persist. PRUNE_WS_SESSIONS defaults to true. The trade-off is that hibernation is a manual lifecycle. There is no documented scheduler that wakes a session at a given time or on a given event, so if you hibernate something you intend to resume, you are the trigger. For a single operator that is fine. For anything resembling a queue of background jobs, it is a gap.
The iOS Safari layer is the actual differentiator, and the hardest part to verify
Most of the feature list is about mobile input rather than terminal rendering. The README claims paste support including images, touch scrolling, tap-to-click, and long-press selection inside fullscreen Claude Code sessions, plus mobile-friendly copy prompts when browser clipboard writes need a user gesture. It also documents virtual arrow keys and a d-pad, and a quick keys toolbar for ctrl, esc and similar. On the desktop side there are keyboard shortcuts: Ctrl+Option+[ and Ctrl+Option+] for previous and next session on Mac, Ctrl+Shift+[ and Ctrl+Shift+] on Windows and Linux, with Ctrl+Option+1..9 or Ctrl+Shift+1..9 to jump to a session, Ctrl+Option+N or Ctrl+Shift+N for a new session, and Ctrl+Option+X or Ctrl+Shift+X to kill one. Two settings hint at the friction underneath: AGENTBOARD_CLAUDE_NO_FLICKER and AGENTBOARD_TMUX_SYNC, both defaulting to true, and TERMINAL_MODE defaulting to pty. Clipboard integration has its own flag, AGENTBOARD_TMUX_SET_CLIPBOARD, and image pastes are capped by AGENTBOARD_PASTE_IMAGE_MAX_BYTES at 41943040 (about 40 MB). These are the kind of switches you add after fighting a specific browser behaviour. Whether the current build handles your particular iOS version and your particular agent TUI is not something the README can settle. It is the first thing to test.
Where Agentboard is the wrong tool
The status inference is the weakest link and the README is candid about its inputs rather than its accuracy. It reads pane content and JSONL logs from Claude, Codex and Pi. If you run a different agent, or a wrapper that changes the prompt format, the working, waiting and permission states may be wrong or absent. A wrong status is worse than no status, because you will stop checking. Remote host support has a similar shape: AGENTBOARD_REMOTE_ALLOW_ATTACH and AGENTBOARD_REMOTE_ALLOW_CONTROL default to false, so out of the box you can see remote sessions but not drive them, and the SSH options default to -o BatchMode=yes -o ConnectTimeout=3, which fails fast rather than prompting. If your remote hosts need interactive authentication or a jump host, that default will not work and you will be editing AGENTBOARD_REMOTE_SSH_OPTS. There is also no user model described anywhere in the material. The server binds to localhost by default and to a Tailscale IP when detected, which is a single-operator posture. Putting it behind 0.0.0.0 on a shared network means anyone who reaches the port reaches your tmux sessions, your agent logs, and whatever those agents can do. Finally, the dependency risk scanner is a project-internal tool, not a feature of the product: bun run deps:risk reports security findings from bun audit --json aggregated by severity and maintenance lag from bun outdated classified as major, minor or patch, with a local default threshold of high and CI enforcing critical only. It tells you about Agentboard's own dependency tree, which is useful if you vendor or fork it, and irrelevant if you install from npm.
Compared with ttyd, Wetty or just SSH in a terminal app
The obvious alternative is a general web terminal such as ttyd or Wetty, or a native mobile SSH client. Those expose a shell or a tmux attach and stop there. The difference in approach is where the state lives. A general web terminal is stateless from the browser's perspective: it renders whatever the process emits and knows nothing about which pane is an agent, what that agent is doing, or what its last prompt was. Agentboard maintains a server-side model of sessions, matched to log files, with a status and a last prompt, plus a hibernation state that survives restarts. That model is what makes the phone experience usable, and it is also what makes the project fragile in a way ttyd is not, because every agent update is a potential parsing change. The second real alternative is attaching over SSH and using tmux's own client, which requires no extra server but gives you none of the mobile input affordances: no d-pad, no quick keys toolbar, no image paste handling, no clipboard prompting. If your only goal is to run commands from a phone, a general web terminal is simpler and has fewer moving parts. If your goal is to supervise several agents across a day, the session model is the reason to accept the extra surface.
Maintenance cost and licence
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication; anything beyond it depends on your own legal review, including what your agents' log files contain and whether shipping them to a browser is acceptable in your context. On maintenance, the release cadence visible in the material is three releases in the four days before the last push, v0.5.0 through v0.5.2, which suggests active development but also a version number below 1.0 and therefore no stability promise. The upgrade path is the same command you installed with, brew upgrade agentboard or npm install -g @gbasin/agentboard, and the state file at ~/.agentboard/agentboard.db is the thing to back up before a jump, since hibernating and history entries live there. There is no documented migration tooling for that database. If you deploy from source with bun run build and bun run start or through the provided systemd and launchd units, you own the rebuild cycle. The realistic ongoing cost is not the install, it is re-checking status inference and iOS input after agent updates, because those are the parts coupled to software you do not control.
Editorial conclusion
Adopt Agentboard if you already run Claude, Codex or Pi inside tmux on a machine you can reach over Tailscale or LAN, and you want to check on or drive those sessions from an iPhone without installing a terminal app. Do not adopt it as a general SSH client, as a multi-user service, or if you cannot run tmux on the host. Before committing, verify three things on your own machine: that a fullscreen Claude Code session renders and scrolls correctly in iOS Safari, that log matching actually pairs your sessions with the right tmux windows (the README notes AGENTBOARD_PREFER_WINDOW_NAME exists as a fallback, which implies matching can misfire), and that the default HOSTNAME=127.0.0.1 binding plus Tailscale auto-detection gives you the network exposure you actually want.
Community notes