DuarteSantos8/agentdeck: Self-hosted browser terminal deck for long-running Claude Code and shell agents — every session is a tmux session, so it survives the closed tab, the dropped VPN and a service restart. · GitHub

Terminals that survive the closed tab, the dropped VPN and a restart of the service — because they are real tmux sessions.

Start a Claude agent · close the window · open it again — same session, still running.

Start a shell or a Claude Code agent on your server, close the tab, walk away, come back on your phone — it is still there, still running, still where you left it. Every session is a tmux session, so nothing dies with your browser. No account, no cloud, no build step: one Node process and a handful of static files.

Long-running agents do not fit the SSH-in-a-tab model. You start a Claude Code run, it works for twenty minutes, and meanwhile your laptop sleeps, the VPN blips, or you simply want to check on it from the couch. With a plain ssh that run is gone.

AgentDeck puts a thin browser layer on top of tmux instead. The browser is only a viewer: sessions live on the host, keep running when nothing is attached, and reattach instantly from any device on your network. Restarting the service does not kill them either.

AgentDeck has no login of its own. The only gate is an IP allowlist (ALLOW_PREFIXES). Anyone who reaches it from an allowed address can open a root shell on your host — which is to say, do anything.

• Never expose it to the internet. No port forwarding, no public reverse proxy without your own auth in front.
• Reach it over LAN or VPN only (WireGuard, Tailscale, …).
• Set ALLOW_PREFIXES as narrow as possible — your LAN and VPN subnet, nothing else. Unset means every private RFC-1918 range is allowed — that is the whole LAN, not just you.
• Sessions run as the user the service runs as. The shipped unit says User=root, so that is a root shell. Run it as a less privileged user if that is not what you want.
• If you do put a reverse proxy in front (Traefik, nginx, Caddy), pair it with real authentication (Authelia, Basic Auth, …) and keep it VPN-only.

This is deliberate: the tool exists to hand you a root shell quickly. Treat the network as the security boundary and it is a fine trade. Treat it carelessly and it is a remote-root hole.

• Persistent sessions — every terminal is a tmux session on a dedicated socket. Close the tab, reboot your laptop, lose the network: the agent keeps working and you reattach where it left off.
• Real terminals — xterm.js over a WebSocket into a PTY. Full colour, resizing, mouse, TUIs.
• A window manager, not a tab strip — drag, resize, maximise, snap, tile, cascade. Position, size and which windows were open are remembered, so a reload puts your deck back as it was.
• Command palette — Ctrl+Shift+K (⌘K on macOS) fuzzy-finds every session and every action: open, rename, snap, kill, files, accent, help. Nothing is buried in a menu.
• One click for a new Claude agent — spawns a shell and starts the Claude Code CLI in it. When Claude exits you still have the shell.
• Terminal-native copy & paste — drag to select and it is on your clipboard; Ctrl+V, right-click and middle-click paste. Ctrl+C stays SIGINT, always. On phones, where none of that exists, dedicated copy and paste dialogs take over.
• Actually usable on a phone — full-screen terminals, swipe to scroll, long-press to paste, and a key bar for Esc, Tab, Shift+Tab, Ctrl and the arrows, because a software keyboard has none of them. The dock and key bar stay above the keyboard instead of under it.
• File manager — browse, upload, download, rename, create and delete folders under one root. Drag a file onto a terminal and its path is typed into the session.
• Images straight into the agent — paste a screenshot from the clipboard and it is uploaded, with the path typed into the session, ready for Claude to read.
• Colour-coded agents, shared across devices — names, colours and folders live on the server, so your phone shows the same deck as your desktop.
• Themable — one accent colour drives the whole palette; CRT scanlines and glow are still in there for anyone who wants them, one switch away.

The deck — three named, colour-coded sessions, sized the way you left them.
Command palette — every session and every action, one keystroke away.	File manager — upload, download, rename, drag onto a session.
Appearance — accent, font, cursor, effects. Applies live.	Any accent — the whole palette is derived from one colour.
On a phone — the same sessions, plus the keys the keyboard is missing.

• Linux host with Node.js ≥ 18 and tmux
• Build tools for node-pty (native module): build-essential, python3
• Optional: the Claude Code CLI as claude in PATH, for the NEW CLAUDE AGENT button. Without it the regular shell sessions work exactly the same.

# 1) Dependencies
apt update && apt install -y nodejs npm tmux build-essential python3 git

# Node must be >= 18 — the version in older Debian/Ubuntu repos is not.
node -v || true
# If that prints < v18, install a current Node instead, e.g.:
#   curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt install -y nodejs

# 2) Get the code
git clone https://github.com/DuarteSantos8/agentdeck.git /opt/agentdeck
cd /opt/agentdeck

# 3) Install (compiles node-pty natively)
npm install --omit=dev

# 4) Configure — at minimum, narrow the allowlist
cp .env.example .env
$EDITOR .env

# 5) Try it
node server.js
# → "AgentDeck on :7700"  →  http://<host-ip>:7700

cp agentdeck.service /etc/systemd/system/agentdeck.service
$EDITOR /etc/systemd/system/agentdeck.service   # adjust WorkingDirectory; the .env next to
                                                # server.js is picked up automatically
systemctl daemon-reload
systemctl enable --now agentdeck

The unit runs with KillMode=process on purpose: when you restart the service, only the Node process is replaced. Your tmux agents survive and the fresh process reattaches to them.

Everything is environment variables — see .env.example. A .env file next to server.js is read on start; anything already set in the real environment (Environment= or EnvironmentFile= in the systemd unit) wins over it.

browser ──WebSocket──> node ──PTY──> tmux attach ──> agent-1 (bash, claude, …)
   xterm.js                            socket: $TMUX_SOCKET

• Sessions are named agent-1, agent-2, … on a dedicated tmux socket, so they never collide with tmux sessions you started by hand.
• The server spawns tmux attach inside a PTY and pipes it over a WebSocket. Closing the tab is a detach, nothing more.
• You are never locked in: tmux -L agentconsole attach -t agent-1 over SSH gets you the exact same session.
• Static assets (xterm.js) are served straight from node_modules — no bundler, no build.
• Agent metadata lives in DATA_DIR/meta.json and is written atomically, so every device sees the same names, colours and folders.
• The socket is pinged every 25 s. An attached but idle agent sends nothing for minutes, which a reverse proxy or a mobile network is happy to call a dead connection and cut.

Ctrl+K is deliberately left alone: it kills the line in every shell. That is why the palette sits on Ctrl+Shift+K everywhere except macOS, where ⌘K is free.

The title bar gains ⧉ (copy) and ⇪ (paste) buttons, a long press on the terminal opens the paste dialog — camera and gallery included — and a key bar appears above the dock with the keys a software keyboard does not have:

server.js                  Entry point — HTTP server + WebSocket, ~15 lines

src/config.js              Environment configuration and constants
src/allowlist.js           The IP allowlist, as a function and as middleware
src/app.js                 Express app assembly
src/tmux.js                Every tmux call the app makes (list, create, kill, capture)
src/attach.js              WebSocket ↔ PTY ↔ "tmux attach", with the keepalive
src/meta-store.js          Shared agent metadata, sanitised and written atomically
src/uploads.js             Path guards and the streaming upload
src/routes/                sessions.js · meta.js · files.js

public/index.html          Shell of the page
public/style.css           The whole interface, derived from one accent colour

public/js/main.js          Bootstrap: toolbar, polling, global paste, viewport insets
public/js/deck.js          Window manager — open, focus, drag, snap, geometry, restore
public/js/terminal.js      xterm.js + WebSocket + copy/paste, mouse and touch handling
public/js/taskbar.js       Session chips, groups, chip menu, hover preview
public/js/palette.js       Command palette: fuzzy search over sessions and actions
public/js/keybar.js        The on-screen Esc/Tab/Ctrl/arrow keys for phones
public/js/file-manager.js  The file browser
public/js/store.js         Agent metadata with server sync
public/js/settings.js      Accent colour maths, fonts, effects
public/js/ui.js            Ask/confirm sheets and the popover menu
public/js/modal.js         One dialog primitive: stacking, focus trap, Escape
public/js/icons.js         The inline SVG icon set
public/js/dialogs/         paste.js · copy.js · help.js · settings.js
public/js/{api,bus,clipboard,dom,toast,uploads}.js
                           Small shared pieces

agentdeck.service          systemd unit template

The frontend is plain ES modules loaded straight by the browser — no bundler, no transpiler, no npm run build. Edit a file, reload the page.

• Linux only. It shells out to tmux and spawns a PTY; macOS is untested, Windows is out.
• Native install, no Docker image. node-pty is compiled on the host, and the point of the tool is to reach that host's shell — containerising it mostly gets in the way.
• Mainly tested on Chromium. Firefox and Safari work in normal use, but the clipboard paths differ per browser and get the least testing.
• Single user, no accounts. There is no login, no per-user separation and no audit log — see the Security section above.
• No TLS of its own. Plain HTTP; put it behind a reverse proxy if you want HTTPS.

Issues and pull requests are welcome — see CONTRIBUTING.md. The project is deliberately small and dependency-light; changes that keep it that way have the easiest path in.

MIT — see LICENSE.