Show HN: Persistent Claude Code sessions you drive as a terminal or a chat

Agentpeek, a free self-hosted browser control panel for Claude Code, allows users to start persistent AI agent sessions on Linux/WSL2 that continue running even after closing a laptop, accessible from any browser over a tailnet. The tool uses tmux sessions and a FastAPI backend to manage session lifecycles, enabling users to drive AI agents for generating content like code, docs, and reports. It includes a companion viewer, filepeek, for rendering generated files.

agentpeek is the free, self-hosted browser control panel for Claude Code . Start a session on your Linux/WSL2 box, drive it as a terminal or a chat, and reach it from any browser over your tailnet — it keeps working when you close the laptop. You start Claude Code or any shell in a session, close the laptop, and it keeps working. Open the same browser tab from another machine and you're right back in it — the session never stopped. Sessions are plain named tmux sessions, so the exact same ones are reachable over SSH with tmux attach . agentpeek is where the work happens: you drive the AI agents that generate your content — docs, code, reports, sites. Its companion filepeek is the downstream viewer that renders the .md / .html / .xlsx files those agents leave behind. See Companion tool companion-tool . Browser ──► uvicorn/FastAPI :8090 127.0.0.1 ├── / static frontend sidebar + iframe ├── /api/... session lifecycle REST API → tmux app/multiplexer.py └── /term/... reverse proxy HTTP + WebSocket → ttyd :7681 ttyd runs bin/agentpeek-attach <name = replay history + tmux attach Everything binds to 127.0.0.1 and is served from one port, so exposing it on the tailnet is a single command see below . The terminal iframe is same-origin, which keeps clipboard access and tailscale serve simple. app/multiplexer.py — the only module that knows about tmux swap point for another multiplexer . bin/agentpeek-attach — ttyd entrypoint; validates the session name, replays pane history tmux capture-pane -S - so browser scrollback covers output from before the attach, then exec tmux attach .- Switching sessions in the sidebar swaps the iframe URL; the old iframe's WebSocket closes, ttyd reaps that tmux attach client, and tmux detaches it cleanly — the browser is never attached to two sessions. On a fresh Debian/Ubuntu incl. WSL2 , setup.sh installs everything it needs for you — the OS packages tmux , curl , python3-venv via sudo apt , plus ttyd , Claude Code , and the Python deps — so it's one command. One thing it can't do for you: systemd must be enabled — the services run under it. On WSL2, add this to /etc/wsl.conf , then run wsl --shutdown in Windows PowerShell and reopen your terminal:Ubuntu 24.04 on recent WSL enables systemd by default; boot systemd=true setup.sh checks and tells you if it's missing. Claude Code is installed via the official native installer a standalone binary in ~/.local/bin , no Node/npm . After setup, sign in from agentpeek's Claude chip or run claude once — needed for UI chat mode ; shell mode needs no sign-in. Also: you need git to clone the repo and Python 3.10+ already on Ubuntu 22.04/24.04 ; the bundled ttyd binary is x86 64 . For remote/mobile access you need Tailscale — setup.sh offers to install it for you or set AGENTPEEK INSTALL TAILSCALE=1 / 0 to skip the prompt . — the downstream viewer that renders the filepeek https://github.com/thrinz/filepeek recommended companion .md / .html / .xlsx /code files your agents generate, so you can browse them in the browser. setup.sh offers to clone and install it next to agentpeek or set AGENTPEEK INSTALL FILEPEEK=1 / 0 to skip the prompt . See Companion tool companion-tool . Clone into your Linux home, not a Windows drive — a repo under /mnt/c/... is slow and lacks real Unix permissions, so setup.sh refuses to run there. cd ~ && git clone https://github.com/thrinz/agentpeek.git && cd agentpeek ./setup.sh It installs the apt prerequisites tmux / curl / python3-venv and ttyd if missing, installs Claude Code, creates .venv and installs the Python deps including claude-agent-sdk , sources conf/agentpeek.tmux.conf from ~/.tmux.conf , installs and enables three systemd user services agentpeek-tmux , agentpeek-ttyd , agentpeek , and enables linger so everything starts at WSL2 boot. At the end it prompts you to set a browser login password hashed into ~/.config/agentpeek/agentpeek.env and prints the URL — http://localhost:8090 . It's idempotent — safe to re-run — and offers to install Tailscale if it isn't already present. Custom ports. agentpeek uses 8090 web and 7681 ttyd by default. To run it alongside another service — or another WSL distro that already holds those ports on a shared localhost — pass different ports at setup: AGENTPEEK PORT=9090 AGENTPEEK TTYD PORT=9091 ./setup.sh setup bakes them into the systemd units the app's reverse proxy follows the ttyd port automatically , so re-running with the same values is all it takes. Headless / cloud Linode, DigitalOcean, … . setup.sh runs non-interactively when there's no TTY — every prompt has an env override, so nothing blocks: AGENTPEEK INSTALL TAILSCALE=1 ./setup.sh For a one-shot deploy, paste deploy/cloud-init.sh /thrinz/agentpeek/blob/main/deploy/cloud-init.sh into a Linode/DO droplet's User Data field — it clones, installs, joins your tailnet with a Tailscale auth key , and serves agentpeek over HTTPS. See for the StackScript and the Linode / DigitalOcean Marketplace submission steps. /thrinz/agentpeek/blob/main/deploy/MARKETPLACE.md deploy/MARKETPLACE.md Password — with no TTY and none set, setup generates a strong temporary one , prints it, and saves it to ~/.config/agentpeek/initial-password.txt 0600 . It's one-time : your first login is forced through a change password screen, after which the temp password and that file are discarded. Override with AGENTPEEK PASSWORD=… final, no forced change , or AGENTPEEK NO PASSWORD=1 to rely on tailnet ACLs only. Claude sign-in — not done at setup no host browser . After install, sign in from the Claude chip in the web UI, or claude auth login over SSH. Reach it over Tailscale only — agentpeek binds 127.0.0.1 ; never expose 8090 / 7681 on the public interface. tailscale serve is the intended door.- Cloud VMs are often root — setup sets IS SANDBOX=1 so UI mode and cds work the agent then acts as root without per-tool prompts . Expose on the tailnet HTTPS, tailnet-only — never the public internet : pick any free https port; 9443 here because 443 was already in use on my host tailscale serve --bg --https=9443 http://127.0.0.1:8090 → https://<your-host .<your-tailnet .ts.net:9443 The app is the same on macOS; only the installer differs Homebrew + launchd instead of apt + systemd . Use setup-macos.sh rather than setup.sh : prerequisite: Homebrew https://brew.sh and Python 3.10+ git clone https://github.com/thrinz/agentpeek.git && cd agentpeek ./setup-macos.sh → open http://localhost:8090 It brew install s tmux and ttyd , installs Claude Code, creates the venv, and renders the templates in launchd/ /thrinz/agentpeek/blob/main/launchd into ~/Library/LaunchAgents dev.agentpeek.tmux , dev.agentpeek.ttyd , dev.agentpeek.app . The agents start at login launchd RunAtLoad , no linger needed . Same port overrides apply AGENTPEEK PORT=… AGENTPEEK TTYD PORT=… ./setup-macos.sh . Manage it with: launchctl kickstart -k gui/$ id -u /dev.agentpeek.app restart launchctl print gui/$ id -u /dev.agentpeek.app status tail -f ~/Library/Logs/agentpeek/app.log live logs launchctl bootout gui/$ id -u /dev.agentpeek.app stop Tailscale on macOS installs from the App Store / standalone app https://tailscale.com/download , then tailscale serve works exactly as above. A prebuilt multi-arch image linux/amd64 + linux/arm64 is published to GitHub Container Registry, so you can run agentpeek anywhere Docker runs — Linux, macOS, or Windows the container is Linux; Docker Desktop runs it on Mac/Windows . This is also the only way to run it on Windows, which can't host it natively. docker pull ghcr.io/thrinz/agentpeek:latest The quickest start is docker-compose.yml /thrinz/agentpeek/blob/main/docker-compose.yml : the agent edits the projects tree you mount. The API key is OPTIONAL: Pro/Max subscription — no key; sign in from the in-app Claude chip after it starts: PROJECTS DIR=~/projects docker compose up -d …or use an Anthropic API key for UI chat mode: PROJECTS DIR=~/projects ANTHROPIC API KEY=sk-ant-... docker compose up -d → http://localhost:8090 It mounts your projects tree the agent's working files , and named volumes for the app state ~/.config/agentpeek and Claude auth ~/.claude so they survive restarts. UI chat mode needs Claude signed in, but the API key is optional — leave it out and sign in with your Pro/Max subscription from the in-app Claude chip it persists in the ~/.claude volume , mount your host ~/.claude to reuse an existing login, or pass ANTHROPIC API KEY for per-token billing. Exposure:the compose file binds— agentpeek runs an autonomous agent, so don't publish it on the open internet. Reach it over your tailnet: 127.0.0.1 on purpose tailscale serve --bg --https=9443 http://127.0.0.1:8090 . The image is built and pushed by .github/workflows/docker.yml /thrinz/agentpeek/blob/main/.github/workflows/docker.yml on every push to main and every v tag no cloud credentials — it uses the built-in GITHUB TOKEN .The sidebar groups sessions into collapsible folders you define yourself create them with the folder button; up to two nested levels . A General folder always exists as the catch-all — sessions created from the CLI land there. The folder is stored on the tmux session itself as the @agentpeek group session option, so it survives renames; the folder list lives in ~/.config/agentpeek/folders.json . The create dialog asks for: a folder required , a Type — Shell a tmux terminal or UI a Claude chat — see UI mode ui-mode--claude-chat — a working directory picked from a collapsible tree rooted at ~/projects DIRS ROOT in app/main.py , and for Shell type a start option AI types your launcher command into the new shell, or plain Shell . AI start optiontypes cds into the new shell. setup.sh installs cds to ~/.local/bin as claude --dangerously-skip-permissions edit that file, or the send-keys command in app/multiplexer.py , to launch a different agent like aider . It won't overwrite an existing cds , so your customisation sticks. Running as root?Claude Code refuses to skip permissions as root, so UI mode and cds fail with exit 1. setup.sh detects root and sets IS SANDBOX=1 in the env file and cds sets it too to allow it — this lets the agent act as root without per-tool prompts, so prefer running agentpeek as a normal user. For an AI Shell + AI session the create dialog also offers “Notify my phone when Claude finishes” with a dropdown of remembered ntfy phone-notifications-ntfy topics — see below. Get a push on your phone every time Claude finishes a turn in a session, using the free ntfy.sh https://ntfy.sh service. Three pieces cooperate: - A Claude Code Stop hook one-time, per machine . Add this to ~/.claude/settings.json — it pushes only when CLAUDE NOTIFY TOPIC is set, so sessions without a topic stay silent: { "hooks": { "Stop": { "hooks": { "type": "command", "command": " -n \"$CLAUDE NOTIFY TOPIC\" && curl -s -H \"Title: Claude Code\" -d \"Claude finished a turn in $ basename \"${CLAUDE PROJECT DIR:-session}\" \" \"https://ntfy.sh/$CLAUDE NOTIFY TOPIC\" /dev/null 2 &1 || true", "async": true } } } } - sets cds CLAUDE NOTIFY TOPIC from its first argument — cds off , cds on uses $CDS NOTIFY TOPIC , export your default in your shell rc , or cds <topic a custom topic . The installed bin/cds already does this. - The create dialog ties it together: tick Notify my phone , pick or add a topic, and agentpeek types cds <topic into the new session for you. Topics you add are remembered in the browser for next time. On your phone, install the ntfy app iOS/Android and subscribe to the same topic name . Topics are public unguessable strings — anyone who knows the name can read its messages, so use something random like claude-$ openssl rand -hex 4 and don't share it. On phones/tablets a touch key bar appears under the terminal when a Shell session is attached, with the keys a soft keyboard can't reliably send to a terminal: esc, tab, ctrl sticky — tap it then a letter for Ctrl-combos , arrow keys , scroll up/down, and paste . Every button routes through tmux send-keys on the server POST /api/sessions/<name /keys , so it works even where iOS Safari's keyboard events don't reach xterm. Pair it with tailscale serve --https so the clipboard-based paste has a secure context. A UI session is a chat with the Claude Agent SDK running in the chosen directory — the same agent as a terminal Claude Code session it edits files, runs bash, uses tools , rendered as a chat instead of a terminal. It needs the claude CLI installed and a Claude connection claude-connection-for-ui-mode . Streaming token-by-token with a live cursor; markdown + GFM tables + code rendering with copy-code buttons; tool calls and results shown inline collapsible . Message queue — keep typing while the agent works; messages run in order. Stop button or Esc interrupts the current turn.in the input autocompletes files in the working directory to reference. @ Model picker Opus / Sonnet / Haiku per session, switchable live; per-turn and running cost shown in the header; optional voice in mic → speech-to-text and out speak replies . Always-on background agents — the agent keeps running if you close the browser; reconnecting auto-reconnect on drop reloads the transcript and the conversation resumes SDK resume . Idle agents no browser, not working are suspended after 30 min and resume on the next message. Sessions run autonomously bypassPermissions — same trust model as your terminal. Registry + transcripts live under ~/.config/agentpeek/ ui sessions.json , ui transcripts/ . UI-mode sessions run the Claude Agent SDK , which authenticates with whatever the host's claude CLI uses. The Claude chip at the bottom of the sidebar shows the connection state and, when not connected, opens a sign-in panel: Sign in with Claude drives claude setup-token server-side: it prints an authorize URL shown in the panel , you approve it in your browser and paste the code back, and the resulting long-lived subscription token is saved as CLAUDE CODE OAUTH TOKEN in ~/.config/agentpeek/agentpeek.env — the same flow as /login in the terminal. Requires a Claude Pro/Max/Team/Enterprise plan. Use an API key saves an ANTHROPIC API KEY instead bills per-token . If the host is already logged into Claude Code ~/.claude/.credentials.json exists , the chip shows connected and nothing else is needed. Disconnecting clears only agentpeek's saved token/key — it never touches the host's own login. UI mode runs Claude Code, which can route to Amazon Bedrock or Google Vertex AI instead of the first-party Anthropic API. agentpeek detects this and adapts: the chip shows "Using AWS Bedrock / Google Vertex" , the in-app sign-in panel is hidden the cloud provider authenticates you , the per-turn cost is hidden billing goes through the cloud account , and the model picker is hidden — on these backends the opus / sonnet / haiku aliases don't resolve, so agentpeek lets Claude Code use the model you set in the environment. There's no UI for this yet — configure it by hand in ~/.config/agentpeek/agentpeek.env loaded by the systemd unit; for the manual uvicorn run, the vars must be in the process environment . Set the backend flag, the model IDs, and the provider credentials, then restart agentpeek. Amazon Bedrock: CLAUDE CODE USE BEDROCK=1 AWS REGION=us-east-1 AWS auth: a profile, static keys, or an attached IAM role AWS PROFILE=default Model IDs are Bedrock inference-profile / model IDs, not the short aliases: ANTHROPIC MODEL=us.anthropic.claude-opus-4-...-v1:0 ANTHROPIC SMALL FAST MODEL=us.anthropic.claude-haiku-4-...-v1:0 Google Vertex AI: CLAUDE CODE USE VERTEX=1 CLOUD ML REGION=us-east5 ANTHROPIC VERTEX PROJECT ID=your-gcp-project GCP auth: application-default credentials gcloud auth application-default login , or a service-account key via GOOGLE APPLICATION CREDENTIALS=/path/key.json ANTHROPIC MODEL=claude-opus-4-... ANTHROPIC SMALL FAST MODEL=claude-haiku-4-... Look up the exact model IDs available in your account/region from the provider console they change over time . The agent's tools bash, file edits, etc. run locally on your box regardless of which backend serves the model. Note that Anthropic's server-hosted features Managed Agents, server-side tools aren't available on Bedrock/Vertex — but agentpeek uses the local Claude Code agent, so that doesn't affect it. agentpeek binds to 127.0.0.1 only and is reachable remotely solely through Tailscale tailscale serve , so the baseline access control is tailnet membership/ACLs. Do not port-forward 8090/7681 to any public interface. Optional key-based login same scheme as filepeek adds a second factor on top of the tailnet. The easiest way to enable it is to run ./setup.sh — it prompts for a password, hashes it, writes ~/.config/agentpeek/agentpeek.env , and restarts the service. Re-run it any time to change the password, or set AGENTPEEK PASSWORD=… ./setup.sh to do it non-interactively. To wire it up by hand instead, set either env var in ~/.config/agentpeek/agentpeek.env read by the systemd unit : generate a password hash .venv/bin/python -m app hash-password then create ~/.config/agentpeek/agentpeek.env with: AGENTPEEK PASSWORD HASH=pbkdf2 sha256$200000$.... browser login AGENTPEEK TOKEN=<random-string scripted access: Authorization: Bearer <token AGENTPEEK SECRET=<random-string keeps sessions valid across restarts restart: systemctl --user restart agentpeek With auth on, the browser logs in at /login PBKDF2-checked password → signed, HttpOnly session cookie, 7-day TTL, per-IP lockout after repeated failures and the terminal WebSocket is gated on the same cookie. With neither var set, the app is open — the accepted posture for a purely local, single-operator setup. Turning it on is recommended once UI mode can drive agents that edit files over the tailnet. Each session's ⋮ menu has Copy SSH attach command , which copies a ready one-liner for that exact session: ssh -t <user @<tailscale-hostname tmux attach -t <session-name detach again without stopping it: Ctrl-b then d -t forces a TTY so tmux runs interactively. There is also Copy local attach command tmux attach -t <name for when you are already on the host. history-limit 1000000 — "unlimited" scrollback, bounded by memory applies to sessions created after the setting is loaded . terminal-overrides ',xterm :smcup@:rmcup@' + status off — disables the alternate screen and the tmux status bar so output flows into the browser's native scrollback buffer and wheel-scrolling/select-to-copy work without tmux copy-mode. Side effects: SSH attaches also get no status bar, and the screen isn't restored after detaching in a CLI terminal. Both accepted for this tool. mouse off — xterm.js owns selection select → Ctrl/Cmd+C copies natively . - The tmux server runs on a dedicated socket tmux -L agentpeek owned by agentpeek-tmux.service , in its own cgroup. So restarting or crashing the app agentpeek / agentpeek-ttyd never touches your sessions — selected via AGENTPEEK TMUX SOCKET=agentpeek honored by app/multiplexer.py and bin/agentpeek-attach ; same socket in the launchd and Docker setups . Stopping It uses agentpeek-tmux is the only thing that kills the tmux server and all sessions. exit-empty off , so it also stays up with zero sessions no placeholder session needed . To reach it by hand: tmux -L agentpeek ls . Terminal sessions are restored after the tmux server dies a host reboot, or a Docker container restart — where the server lives inside the app container . agentpeek keeps a manifest at ~/.config/agentpeek/shell sessions.json name, dir, group, and for AI sessions a Claude session id and recreates the sessions on startup. AI sessions are lazily resumed : each is recreated empty with a pending cds --resume <id that bin/agentpeek-attach runs the first time you open it, so a restart never spawns every Claude at once. Resume needs Claude's transcripts ~/.claude — already a persisted volume in Docker.- Logs: journalctl --user -u agentpeek -u agentpeek-ttyd -f . - The sidebar polls every 3 s and on tab focus, so CLI-created sessions appear automatically. agentpeek is the primary tool — it's where AI agents generate your content. filepeek is its downstream companion; together they cover the loop of working with AI agents on a remote/WSL2 box: agentpeek — run the agents that generate the content: persistent browser terminal sessions. filepeek — view what they produced: renders the Markdown, HTML, Office, and code files those agents generate, in the browser. Both are self-hosted, single-operator tools that bind to 127.0.0.1 and go over Tailscale, and they share a design language. Install filepeek. setup.sh offers to clone and install it next to agentpeek answer the Install filepeek now? prompt, or set AGENTPEEK INSTALL FILEPEEK=1 to do it non-interactively . To do it by hand instead: cd ~ && git clone https://github.com/thrinz/filepeek && cd filepeek ./install.sh serve your projects tree filepeek defaults to port 8765, bound to 127.0.0.1 : FILEPEEK ROOT=~/projects .venv/bin/python app.py then expose it tailnet-only, like agentpeek pick any free https port : tailscale serve --bg --https=9444 http://127.0.0.1:8765