feat(portal): browser terminal into 24/7 tmux Claude Code session

Self-hosted portal that streams a persistent tmux Claude Code session to
the browser over Socket.io + node-pty, designed to run on a small VPS
behind Tailscale.

- PortalServer (Express + Socket.io + node-pty) attaching to
  tmux new-session -A so the agent survives browser/portal restarts
- Token auth (auto-generated, 0600) gating both page + WS handshake
- Embedded xterm.js UI (no build step, ships in dist)
- stackmemory portal start|status|stop|token CLI
- Hetzner cloud-init, setup.sh, and systemd unit for 24/7 operation
- docs/guides/PORTAL.md walkthrough

https://claude.ai/code/session_01Gk8DiqCeG9uMaWT9RprwP1

Author: claude

docs/guides/PORTAL.md

@@ -0,0 +1,155 @@
+# StackMemory Portal — Run Claude Code 24/7
+
+> A VPS, Claude Code in tmux, a Tailscale VPN, and a vibecoded web terminal.
+> Your agents run 24/7. You experience life.
+
+The **portal** is a self-hosted, browser-based terminal into a persistent
+`tmux` session running Claude Code. Put it on a small VPS behind Tailscale and
+you get a private, always-on coding agent you can check on from your phone,
+laptop, or tablet — no exposed ports, no SaaS in the middle.
+
+```
+┌── Hetzner CX22 (~€4.5/mo) ───────────────────────────┐
+│                                                       │
+│   tmux session "claude"  ──►  claude (max plan)       │
+│        ▲                                              │
+│        │ node-pty                                     │
+│   stackmemory portal  ──►  :7799  (xterm.js + WS)     │
+│        ▲                                              │
+└────────┼──────────────────────────────────────────────┘
+         │  Tailscale (WireGuard, 100.x address)
+         ▼
+   Your browser  →  http://100.x.y.z:7799/?token=…
+```
+
+**Why this shape?**
+
+- **tmux** keeps the agent alive when you close the browser or the portal
+  restarts. Reattach over SSH any time.
+- **Tailscale** gives you an encrypted private address with zero open ports —
+  no nginx, no TLS certs, no firewall holes.
+- **node-pty + xterm.js** stream the real terminal, so Claude Code's TUI,
+  permissions prompts, and colors all work exactly as they do locally.
+
+---
+
+## Quick start (Hetzner cloud-init)
+
+The fastest path — the server provisions itself on first boot.
+
+1. Create a Tailscale **auth key** at
+   <https://login.tailscale.com/admin/settings/keys> (reusable, ephemeral off).
+2. In Hetzner Cloud, **Add Server** → Ubuntu 24.04 → type **CX22**.
+3. Expand **Cloud config** and paste
+   [`scripts/portal/cloud-init.yaml`](../../scripts/portal/cloud-init.yaml).
+   Set `TS_AUTHKEY=` to your key inside the pasted config.
+4. Create the server. After ~2 minutes it's on your tailnet.
+
+Then finish the two interactive steps over SSH:
+
+```bash
+ssh root@<hetzner-ip>
+
+# Authenticate Claude Code (max plan) once — it caches credentials in ~/.claude
+tmux attach -t claude     # log in, approve, then detach with: Ctrl-b d
+
+# Grab your access URL + token
+journalctl -u stackmemory-portal --no-pager | grep -i token
+```
+
+Open `http://100.x.y.z:7799/?token=…` (the `100.x` Tailscale address) from any
+device signed into your tailnet. You're now looking at your agent.
+
+---
+
+## Manual setup
+
+Prefer to do it by hand, or installing on an existing box?
+
+```bash
+# On the VPS (Debian/Ubuntu):
+curl -fsSL https://raw.githubusercontent.com/stackmemoryai/stackmemory/main/scripts/portal/setup.sh | bash
+
+sudo tailscale up                       # join your tailnet (prints an auth URL)
+tmux new -s claude 'claude'             # authenticate Claude, then Ctrl-b d to detach
+stackmemory portal start --cwd ~/work   # start the portal (prints the URL + token)
+```
+
+For 24/7 operation, install the service:
+
+```bash
+sudo cp scripts/portal/stackmemory-portal.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now stackmemory-portal
+journalctl -u stackmemory-portal -f     # tail logs (the access URL is printed here)
+```
+
+---
+
+## The CLI
+
+```bash
+stackmemory portal start      # start the server (foreground; systemd runs this)
+stackmemory portal status     # show status + the access URL for this machine
+stackmemory portal stop       # stop a running portal
+stackmemory portal token      # print the access token
+```
+
+`start` options:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port <n>` | `7799` | Port to listen on |
+| `--host <h>` | `0.0.0.0` | Interface to bind (reachable over the tailnet) |
+| `--session <name>` | `claude` | tmux session name |
+| `--command <cmd>` | `claude` | Command tmux runs (`"claude --resume"`, a wrapper, etc.) |
+| `--cwd <dir>` | cwd | Working directory for the session |
+| `--no-auth` | off | Disable the token (rely on Tailscale alone) |
+
+The portal runs `tmux new-session -A -s <session> <command>`: it **attaches** to
+the session if it already exists, otherwise creates it. Multiple browser tabs
+share the same live session. Closing a tab detaches but never kills the agent.
+
+---
+
+## Security model
+
+- **Network:** binding to `0.0.0.0` is safe *because* the box only has a public
+  IP plus its Tailscale address — keep the cloud firewall closed to `:7799` and
+  reach it exclusively over the tailnet. (Hetzner's firewall: allow `22` from
+  your IP, deny the rest.)
+- **Token:** a 48-char token is generated on first start and stored at
+  `~/.stackmemory/portal/token` (`chmod 600`). It's required on both the page
+  load (`?token=`) and the WebSocket handshake. Rotate it by deleting the file
+  and restarting. `--no-auth` turns this off if you trust your tailnet ACLs.
+- **No inbound ports on the internet.** Tailscale is WireGuard point-to-point;
+  there is nothing to port-scan.
+
+> Treat the token like an SSH key — anyone with the URL gets a live shell as the
+> user running the portal.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `tmux is not installed` | `sudo apt install tmux` |
+| Page loads but terminal is blank / "Cannot start session" | `node-pty` missing on the server: `npm install -g node-pty` (needs `build-essential` + `python3`) |
+| `401 Unauthorized` | Append `?token=<token>` to the URL (`stackmemory portal token`) |
+| Can't reach `100.x` address | `tailscale status` on both ends; make sure your client is logged into the same tailnet |
+| Claude asks to log in every time | Authenticate once inside the tmux session so credentials land in `~/.claude`; ensure systemd `HOME=` points at that user's home |
+| Agent died but portal is up | `tmux attach -t claude` to inspect; the portal recreates the session on next connect |
+
+---
+
+## Files
+
+| Path | Purpose |
+|------|---------|
+| `src/features/portal/server.ts` | Express + Socket.io + node-pty bridge |
+| `src/features/portal/ui.ts` | Embedded xterm.js terminal UI |
+| `src/cli/commands/portal.ts` | `stackmemory portal` command |
+| `scripts/portal/setup.sh` | One-shot VPS installer |
+| `scripts/portal/cloud-init.yaml` | Hetzner first-boot provisioning |
+| `scripts/portal/stackmemory-portal.service` | systemd unit for 24/7 operation |

package.json

@@ -24,6 +24,7 @@
     "dist/src",
     "scripts/git-hooks",
     "scripts/hooks",
+    "scripts/portal",
     "scripts/setup",
     "scripts/setup.sh",
     "scripts/install.sh",

scripts/portal/cloud-init.yaml

@@ -0,0 +1,69 @@
+#cloud-config
+# StackMemory Portal — Hetzner Cloud-Init
+#
+# Paste this into the Hetzner Cloud "Cloud config" box when creating a server
+# (Ubuntu 24.04, a CX22 is plenty: 2 vCPU / 4 GB, ~€4.5/mo). On first boot it
+# installs tmux, Node, Claude Code, StackMemory, and Tailscale, then starts the
+# portal as a systemd service.
+#
+# Set TS_AUTHKEY to a Tailscale auth key (https://login.tailscale.com/admin/settings/keys)
+# to auto-join your tailnet. Otherwise SSH in afterwards and run `tailscale up`.
+#
+# After boot, find the access URL + token with:
+#   journalctl -u stackmemory-portal --no-pager | grep -i token
+
+package_update: true
+packages:
+  - tmux
+  - git
+  - curl
+  - ca-certificates
+  - build-essential
+  - python3
+
+write_files:
+  - path: /etc/stackmemory-portal.env
+    permissions: "0600"
+    content: |
+      # Set this to a Tailscale auth key to auto-join the tailnet on boot.
+      TS_AUTHKEY=
+  - path: /etc/systemd/system/stackmemory-portal.service
+    permissions: "0644"
+    content: |
+      [Unit]
+      Description=StackMemory Portal (browser terminal for Claude Code)
+      After=network-online.target tailscaled.service
+      Wants=network-online.target
+
+      [Service]
+      Type=simple
+      User=root
+      WorkingDirectory=/root/work
+      Environment=HOME=/root
+      Environment=NODE_ENV=production
+      ExecStart=/usr/bin/env stackmemory portal start --port 7799 --session claude --cwd /root/work
+      Restart=always
+      RestartSec=3
+
+      [Install]
+      WantedBy=multi-user.target
+
+runcmd:
+  # Node.js 20.x
+  - curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+  - apt-get install -y nodejs
+  # Claude Code + StackMemory + node-pty (browser terminal backend)
+  - npm install -g @anthropic-ai/claude-code @stackmemoryai/stackmemory node-pty
+  # Tailscale
+  - curl -fsSL https://tailscale.com/install.sh | sh
+  - bash -c 'set -a; . /etc/stackmemory-portal.env; set +a; [ -n "$TS_AUTHKEY" ] && tailscale up --authkey "$TS_AUTHKEY" --ssh || true'
+  # Working dir + start the portal
+  - mkdir -p /root/work
+  - systemctl daemon-reload
+  - systemctl enable --now stackmemory-portal
+
+final_message: |
+  StackMemory Portal is up after $UPTIME seconds.
+  1. If you didn't set TS_AUTHKEY: run `tailscale up` over SSH.
+  2. Authenticate Claude (max plan): `tmux attach -t claude` then log in. Detach with Ctrl-b d.
+  3. Get the URL + token: `journalctl -u stackmemory-portal --no-pager | grep -i token`

scripts/portal/setup.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# StackMemory Portal — VPS setup script.
+#
+# Provisions a fresh Debian/Ubuntu box (e.g. a Hetzner CX22, ~€4.5/mo) to run
+# Claude Code 24/7 inside tmux, reachable from a browser over Tailscale.
+#
+#   curl -fsSL https://raw.githubusercontent.com/stackmemoryai/stackmemory/main/scripts/portal/setup.sh | bash
+#
+# Idempotent: safe to re-run. Re-run after editing PORTAL_* env vars below.
+set -euo pipefail
+
+PORTAL_USER="${PORTAL_USER:-$(whoami)}"
+PORTAL_PORT="${PORTAL_PORT:-7799}"
+PORTAL_SESSION="${PORTAL_SESSION:-claude}"
+PORTAL_WORKDIR="${PORTAL_WORKDIR:-$HOME/work}"
+NODE_MAJOR="${NODE_MAJOR:-20}"
+
+log() { printf '\033[36m[portal-setup]\033[0m %s\n' "$*"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then
+  if have sudo; then SUDO="sudo"; fi
+fi
+
+log "1/6 Installing base packages (tmux, git, curl, build tools)…"
+if have apt-get; then
+  $SUDO apt-get update -y
+  $SUDO apt-get install -y tmux git curl ca-certificates build-essential python3
+fi
+
+log "2/6 Installing Node.js ${NODE_MAJOR}.x…"
+if ! have node || [ "$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)" -lt "$NODE_MAJOR" ]; then
+  curl -fsSL "https://deb.nodesource.com/setup_${NODE_MAJOR}.x" | $SUDO -E bash -
+  $SUDO apt-get install -y nodejs
+fi
+log "    node $(node -v) / npm $(npm -v)"
+
+log "3/6 Installing Claude Code + StackMemory…"
+have claude || $SUDO npm install -g @anthropic-ai/claude-code
+$SUDO npm install -g @stackmemoryai/stackmemory
+# node-pty powers the browser terminal; build tools above let it compile.
+$SUDO npm install -g node-pty || log "    (node-pty global install failed — install it in the portal's working dir)"
+
+log "4/6 Installing Tailscale…"
+if ! have tailscale; then
+  curl -fsSL https://tailscale.com/install.sh | $SUDO sh
+fi
+log "    Run 'sudo tailscale up' to join your tailnet (prints an auth URL)."
+
+log "5/6 Preparing working directory at ${PORTAL_WORKDIR}…"
+mkdir -p "$PORTAL_WORKDIR"
+
+log "6/6 Next steps:"
+cat <<EOF
+
+  StackMemory Portal is installed. To finish:
+
+  1. Join Tailscale:        sudo tailscale up
+  2. Authenticate Claude:   tmux new -s ${PORTAL_SESSION} 'claude'   # log in (max plan), then detach: Ctrl-b d
+  3. Start the portal:      stackmemory portal start --port ${PORTAL_PORT} --session ${PORTAL_SESSION} --cwd ${PORTAL_WORKDIR}
+  4. Open the printed http://100.x.y.z:${PORTAL_PORT}/?token=... URL from any device on your tailnet.
+
+  For 24/7 operation, install the systemd service:
+    sudo cp scripts/portal/stackmemory-portal.service /etc/systemd/system/
+    sudo systemctl enable --now stackmemory-portal
+
+EOF

scripts/portal/stackmemory-portal.service

@@ -0,0 +1,34 @@
+# StackMemory Portal — systemd unit
+#
+# Runs the browser terminal portal 24/7. The Claude Code agent itself lives in
+# a detached tmux session, so it survives portal restarts and browser closes.
+#
+# Install:
+#   sudo cp scripts/portal/stackmemory-portal.service /etc/systemd/system/
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable --now stackmemory-portal
+#   journalctl -u stackmemory-portal -f      # logs (incl. the access URL/token)
+#
+# EDIT BEFORE USE: set User=, WorkingDirectory=, and HOME to match your box.
+# The defaults below assume the common Hetzner "run as root" layout.
+
+[Unit]
+Description=StackMemory Portal (browser terminal for Claude Code)
+After=network-online.target tailscaled.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/root/work
+# HOME must be set so the portal finds ~/.stackmemory and Claude's credentials.
+Environment=HOME=/root
+Environment=NODE_ENV=production
+# Bind to 0.0.0.0 so the Tailscale (100.x) address is reachable; Tailscale
+# itself restricts who can connect, and the portal also requires its token.
+ExecStart=/usr/bin/env stackmemory portal start --port 7799 --session claude --cwd /root/work
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target