termbeam 1.8.1 → 1.9.0

package/README.md

@@ -14,9 +14,7 @@
 
 </div>
 
-TermBeam lets you access your terminal from a phone, tablet, or any browser — no SSH, no port forwarding, no config files. Run one command and scan the QR code.
-
-I built this because I kept needing to run quick commands on my dev machine while away from my desk, and SSH on a phone is painful. TermBeam gives you a real terminal with a touch-optimized UI — key bar, swipe scroll, pinch zoom — that actually works on small screens. You get multi-session tabs with split view, terminal search, a command palette, 12 themes, and secure remote access out of the box.
+TermBeam lets you access your terminal from a phone, tablet, or any browser — no SSH, no port forwarding, no configuration needed. Run one command and scan the QR code.
 
 [Full documentation](https://dorlugasigal.github.io/TermBeam/) · [Website](https://termbeam.pages.dev)
 
@@ -47,90 +45,79 @@ termbeam
 
 Scan the QR code printed in your terminal, or open the URL on any device.
 
-> **First time?** Run `termbeam -i` for a guided setup wizard that walks you through password, port, and access mode.
-
-### Secure by default
-
-TermBeam starts with a tunnel and auto-generated password out of the box — just run `termbeam` and scan the QR code.
-
 ```bash
 termbeam                        # tunnel + auto-password (default)
-termbeam --password mysecret    # use a specific password
-termbeam --no-tunnel            # LAN-only (no tunnel)
-termbeam --no-password          # disable password protection
+termbeam --password mysecret    # custom password
+termbeam --no-tunnel            # LAN only
 termbeam -i                     # interactive setup wizard
 ```
 
-## Remote Access
+## Features
 
-```bash
-# Tunnel is on by default
-termbeam
+### Mobile-First
 
-# Persisted tunnel (stable URL you can bookmark, reused across restarts, 30-day expiry)
-termbeam --persisted-tunnel
+- **No SSH client needed** — just open a browser on any device
+- **Touch-optimized key bar** with arrows, Tab, Ctrl, Esc, copy, paste, and more
+- **Swipe scrolling**, pinch zoom, and text selection overlay for copy-paste
+- **iPhone PWA safe-area support** for a native-app feel
 
-# LAN-only (no tunnel)
-termbeam --no-tunnel
-```
+### Multi-Session
 
-If the [Dev Tunnels CLI](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started) is not installed, TermBeam will offer to install it for you automatically. You can also install it manually:
+- **Tabbed terminals** with drag-to-reorder and live tab previews on hover/long-press
+- **Split view** — two sessions side-by-side (auto-rotates horizontal/vertical)
+- **Session colors and activity indicators** for at-a-glance status
+- **Folder browser** for picking working directory, optional initial command per session
 
-- **Windows:** `winget install Microsoft.devtunnel`
-- **macOS:** `brew install --cask devtunnel`
-- **Linux:** `curl -sL https://aka.ms/DevTunnelCliInstall | bash`
+### Productivity
 
-Persisted tunnels save a tunnel ID to `~/.termbeam/tunnel.json` so the URL stays the same between sessions.
+- **Terminal search** with regex, match count, and prev/next navigation
+- **Command palette** (Ctrl+K / Cmd+K) for quick access to all actions
+- **Completion notifications** — browser alerts when background commands finish
+- **12 color themes** with adjustable font size
+- **Port preview** — reverse-proxy a local web server through TermBeam
+- **Image paste** from clipboard
 
-## CLI Reference
+### Secure by Default
 
-```bash
-termbeam [shell] [args...]        # start with a specific shell (default: auto-detect)
-termbeam --port 8080              # custom port (default: 3456)
-termbeam --host 0.0.0.0           # allow LAN access (default: 127.0.0.1)
-termbeam --lan                    # shortcut for --host 0.0.0.0
-termbeam -i                       # interactive setup wizard
-termbeam service install          # interactive PM2 service setup wizard
-termbeam service uninstall        # stop & remove PM2 service
-termbeam service status           # show PM2 service status
-termbeam service logs             # tail PM2 service logs
-termbeam service restart          # restart PM2 service
+- **Auto-generated password** with rate limiting and httpOnly cookies
+- **QR code auto-login** with single-use share tokens (5-min expiry)
+- **DevTunnel integration** for secure remote access — ephemeral or persisted URLs
+- **Security headers** (X-Frame-Options, CSP, nosniff) on all responses; only detected shells allowed
+
+## How It Works
+
+TermBeam starts a lightweight web server that spawns a PTY (pseudo-terminal) with your shell, serves a mobile-optimized [xterm.js](https://xtermjs.org/) UI via Express, and bridges the two over WebSocket. Multiple clients can view the same session simultaneously, and sessions persist when all clients disconnect.
+
+```mermaid
+flowchart LR
+  A["Phone / Browser"] <-->|WebSocket| B["TermBeam Server"]
+  B <-->|PTY| C["Shell (zsh/bash)"]
+  B -->|Express| D["Web UI (xterm.js)"]
+  B -.->|Optional| E["DevTunnel"]
 ```
 
-| Flag                  | Description                                          | Default        |
-| --------------------- | ---------------------------------------------------- | -------------- |
-| `--password <pw>`     | Set access password (also accepts `--password=<pw>`) | Auto-generated |
-| `--no-password`       | Disable password (cannot combine with `--public`)    | —              |
-| `--generate-password` | Auto-generate a secure password                      | On             |
-| `--tunnel`            | Create an ephemeral devtunnel URL (private)          | On             |
-| `--no-tunnel`         | Disable tunnel (LAN-only)                            | —              |
-| `--persisted-tunnel`  | Create a reusable devtunnel URL                      | Off            |
-| `--public`            | Allow public tunnel access                           | Off            |
-| `--port <port>`       | Server port                                          | `3456`         |
-| `--host <addr>`       | Bind address                                         | `127.0.0.1`    |
-| `--lan`               | Bind to all interfaces (LAN access)                  | Off            |
-| `--log-level <level>` | Log verbosity (error/warn/info/debug)                | `info`         |
-| `-i, --interactive`   | Interactive setup wizard (guided configuration)      | Off            |
-| `-h, --help`          | Show help                                            | —              |
-| `-v, --version`       | Show version                                         | —              |
-
-| Subcommand          | Description                   |
-| ------------------- | ----------------------------- |
-| `service install`   | Interactive PM2 service setup |
-| `service uninstall` | Stop & remove from PM2        |
-| `service status`    | Show PM2 service status       |
-| `service logs`      | Tail PM2 service logs         |
-| `service restart`   | Restart PM2 service           |
-
-Environment variables: `PORT`, `TERMBEAM_PASSWORD`, `TERMBEAM_CWD`, `TERMBEAM_LOG_LEVEL`, `SHELL` (Unix fallback), `COMSPEC` (Windows fallback). See [Configuration docs](https://dorlugasigal.github.io/TermBeam/configuration/).
+## CLI Highlights
 
-## Security
+| Flag                  | Description                                     | Default        |
+| --------------------- | ----------------------------------------------- | -------------- |
+| `--password <pw>`     | Set access password                             | Auto-generated |
+| `--no-password`       | Disable password protection                     | —              |
+| `--tunnel`            | Create an ephemeral devtunnel URL               | On             |
+| `--no-tunnel`         | Disable tunnel (LAN-only)                       | —              |
+| `--persisted-tunnel`  | Reusable devtunnel URL (stable across restarts) | Off            |
+| `--port <port>`       | Server port                                     | `3456`         |
+| `--host <addr>`       | Bind address                                    | `127.0.0.1`    |
+| `--lan`               | Bind to all interfaces (LAN access)             | Off            |
+| `-i, --interactive`   | Interactive setup wizard                        | Off            |
+| `--log-level <level>` | Log verbosity (error/warn/info/debug)           | `info`         |
+
+For all flags, subcommands, and environment variables, see the [Configuration docs](https://dorlugasigal.github.io/TermBeam/configuration/).
 
-TermBeam auto-generates a password and creates a tunnel by default, so your terminal is protected out of the box. By default, the server binds to `127.0.0.1` (localhost only). Use `--lan` or `--host 0.0.0.0` to allow LAN access, or `--no-tunnel` to disable the tunnel.
+## Security
 
-Auth uses secure httpOnly cookies with 24-hour expiry, login is rate-limited to 5 attempts per minute, and security headers (X-Frame-Options, X-Content-Type-Options, etc.) are set on all responses. Each QR code contains a single-use share token (5-minute expiry) for password-free login. API clients that can't use cookies can authenticate with an `Authorization: Bearer <password>` header.
+TermBeam auto-generates a password and creates a secure tunnel by default, binding to `127.0.0.1` (localhost only). Auth uses httpOnly cookies with 24-hour expiry, login is rate-limited to 5 attempts per minute, QR codes contain single-use share tokens (5-min expiry), and security headers (X-Frame-Options, CSP, nosniff) are set on all responses.
 
-For the full threat model, safe usage guidance, and a quick safety checklist, see [SECURITY.md](SECURITY.md). For detailed security feature documentation, see the [Security Guide](https://dorlugasigal.github.io/TermBeam/security/).
+For the full threat model and safety checklist, see [SECURITY.md](SECURITY.md). For detailed security documentation, see the [Security Guide](https://dorlugasigal.github.io/TermBeam/security/).
 
 ## Contributing
 

package/bin/termbeam.js

@@ -8,13 +8,142 @@ if (subcommand === 'service') {
     console.error(err.message);
     process.exit(1);
   });
+} else if (subcommand === 'resume') {
+  const { resume } = require('../src/resume');
+  resume(process.argv.slice(3)).catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
+} else if (subcommand === 'list') {
+  const { list } = require('../src/resume');
+  list().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
 } else {
+  // Reject any non-flag positional arg — it's not a known subcommand
+  if (subcommand && !subcommand.startsWith('-')) {
+    const { printHelp } = require('../src/cli');
+    console.error(`Unknown command: ${subcommand}\n`);
+    printHelp();
+    process.exit(1);
+  }
+
   const { createTermBeamServer } = require('../src/server.js');
   const { parseArgs } = require('../src/cli');
   const { runInteractiveSetup } = require('../src/interactive');
+  const { readConnectionConfig } = require('../src/resume');
+  const http = require('http');
+
+  function httpPost(url, headers) {
+    return new Promise((resolve) => {
+      const parsed = new URL(url);
+      const req = http.request(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port,
+          path: parsed.pathname,
+          method: 'POST',
+          headers,
+          timeout: 2000,
+        },
+        (res) => {
+          res.resume();
+          resolve(res.statusCode);
+        },
+      );
+      req.on('error', () => resolve(null));
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(null);
+      });
+      req.end();
+    });
+  }
+
+  function checkExistingServer(config) {
+    if (!config) return Promise.resolve(false);
+    const host = config.host === 'localhost' ? '127.0.0.1' : config.host;
+    return new Promise((resolve) => {
+      const req = http.get(
+        `http://${host}:${config.port}/api/sessions`,
+        {
+          timeout: 2000,
+          headers: config.password ? { Authorization: `Bearer ${config.password}` } : {},
+        },
+        (res) => {
+          res.resume();
+          resolve(res.statusCode < 500);
+        },
+      );
+      req.on('error', () => resolve(false));
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(false);
+      });
+    });
+  }
+
+  async function stopExistingServer(config, fallbackPassword) {
+    // Always target loopback — the shutdown endpoint only accepts loopback requests
+    const url = `http://127.0.0.1:${config.port}/api/shutdown`;
+    console.log(`Stopping existing server on port ${config.port}...`);
+
+    // Try with config password, then fallback password, then no password
+    const passwords = [config.password, fallbackPassword, null].filter(
+      (v, i, a) => a.indexOf(v) === i,
+    );
+    let stopped = false;
+    for (const pw of passwords) {
+      const headers = pw ? { Authorization: `Bearer ${pw}` } : {};
+      const status = await httpPost(url, headers);
+      if (status && status !== 401) {
+        stopped = true;
+        break;
+      }
+    }
+    if (!stopped) {
+      console.error(
+        'Cannot stop the existing server — password mismatch.\n' +
+          'Stop it manually (Ctrl+C in its terminal) and try again.',
+      );
+      process.exit(1);
+    }
+    for (let i = 0; i < 20; i++) {
+      await new Promise((r) => setTimeout(r, 250));
+      if (!(await checkExistingServer(config))) break;
+    }
+  }
 
   async function main() {
     const baseConfig = parseArgs();
+    const targetPort = baseConfig.port;
+    const targetHost = baseConfig.host === '0.0.0.0' ? '127.0.0.1' : baseConfig.host;
+
+    // Check connection.json for an existing server
+    const existing = readConnectionConfig();
+    if (existing && (await checkExistingServer(existing))) {
+      if (baseConfig.force) {
+        await stopExistingServer(existing, baseConfig.password);
+      } else {
+        const displayHost = existing.host === '127.0.0.1' ? 'localhost' : existing.host;
+        console.error(
+          `TermBeam is already running on http://${displayHost}:${existing.port}\n` +
+            'Use "termbeam resume" to reconnect, "termbeam list" to list sessions,\n' +
+            'or "termbeam --force" to stop the existing server and start a new one.',
+        );
+        process.exit(1);
+      }
+    }
+
+    // Also check the target port directly (handles stale/missing connection.json)
+    if (baseConfig.force && targetPort !== 0) {
+      const targetConfig = { host: targetHost, port: targetPort, password: baseConfig.password };
+      if (await checkExistingServer(targetConfig)) {
+        await stopExistingServer(targetConfig);
+      }
+    }
+
     let config;
     if (baseConfig.interactive) {
       config = await runInteractiveSetup(baseConfig);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {

package/src/cli.js

@@ -10,6 +10,8 @@ termbeam — Beam your terminal to any device
 
 Usage:
   termbeam [options] [shell] [args...]
+  termbeam resume [name] [options]     Reconnect to a running session
+  termbeam list                        List running sessions
   termbeam service <action>            Manage as a background service (PM2)
 
 Actions (service):
@@ -31,6 +33,7 @@ Options:
   --host <addr>         Bind address (default: 127.0.0.1)
   --lan                 Bind to 0.0.0.0 (allow LAN access, default: localhost only)
   --log-level <level>   Set log verbosity: error, warn, info, debug (default: info)
+  --force               Stop any existing server before starting a new one
   -i, --interactive     Interactive setup wizard (guided configuration)
   -h, --help            Show this help
   -v, --version         Show version
@@ -50,6 +53,8 @@ Examples:
   termbeam /bin/bash                Use bash instead of default shell
   termbeam --interactive               Guided setup wizard
   termbeam service install          Set up as background service (PM2)
+  termbeam resume                   Reconnect to an active session
+  termbeam list                     List all active sessions
 
 Environment:
   PORT                  Server port (default: 3456)
@@ -244,6 +249,7 @@ function parseArgs() {
   let persistedTunnel = false;
   let publicTunnel = false;
   let interactive = false;
+  let force = false;
   let explicitPassword = !!password;
 
   const args = process.argv.slice(2);
@@ -288,6 +294,14 @@ function parseArgs() {
       interactive = true;
     } else if (args[i] === '--log-level' && args[i + 1]) {
       logLevel = args[++i];
+    } else if (args[i].startsWith('--log-level=')) {
+      logLevel = args[i].split('=')[1];
+    } else if (args[i] === '--force') {
+      force = true;
+    } else if (args[i].startsWith('--')) {
+      console.error(`Unknown flag: ${args[i]}\n`);
+      printHelp();
+      process.exit(1);
     } else {
       filteredArgs.push(args[i]);
     }
@@ -341,6 +355,7 @@ function parseArgs() {
     version,
     logLevel,
     interactive,
+    force,
   };
 }
 

package/src/client.js

@@ -0,0 +1,169 @@
+const WebSocket = require('ws');
+
+const DETACH_KEY = '\x02'; // Ctrl+B
+
+/**
+ * Create a terminal client that pipes stdin/stdout over WebSocket.
+ * Resolves when detached or session exits. Rejects on connection error.
+ *
+ * @param {object} opts
+ * @param {string} opts.url        WebSocket URL (ws://host:port/ws)
+ * @param {string} [opts.password] Server password (null for no-auth mode)
+ * @param {string} opts.sessionId  Session ID to connect to
+ * @param {string} [opts.sessionName] Session name (for display)
+ * @param {string} [opts.detachKey] Key to detach (default: Ctrl+B)
+ * @returns {Promise<{reason: string}>}
+ */
+function createTerminalClient({
+  url,
+  password,
+  sessionId,
+  sessionName = 'session',
+  detachKey = DETACH_KEY,
+  detachLabel = 'Ctrl+B',
+}) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url);
+    let cleaned = false;
+    let bannerTimer = null;
+    let bannerShown = false;
+    let onData = null;
+    let onSigwinch = null;
+
+    function showBanner() {
+      if (!cleaned && !bannerShown) {
+        bannerShown = true;
+        process.stdout.write(
+          `\r\n\x1b[33m  attached: ${sessionName} ─── ${detachLabel} to detach\x1b[0m\r\n\r\n`,
+        );
+      }
+      bannerTimer = null;
+    }
+
+    function debounceBanner() {
+      if (bannerShown) return;
+      if (bannerTimer) clearTimeout(bannerTimer);
+      bannerTimer = setTimeout(showBanner, 500);
+    }
+
+    function resetTerminal() {
+      if (bannerTimer) clearTimeout(bannerTimer);
+      process.stdout.write('\x1b]0;\x07');
+      if (process.stdin.isTTY && process.stdin.isRaw) {
+        process.stdin.setRawMode(false);
+      }
+      if (onData) process.stdin.removeListener('data', onData);
+      process.stdin.pause();
+      if (onSigwinch) process.removeListener('SIGWINCH', onSigwinch);
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+        ws.close();
+      }
+    }
+
+    function cleanup(reason) {
+      if (cleaned) return;
+      cleaned = true;
+      resetTerminal();
+      resolve({ reason });
+    }
+
+    ws.on('open', () => {
+      if (password) {
+        ws.send(JSON.stringify({ type: 'auth', password }));
+      } else {
+        ws.send(JSON.stringify({ type: 'attach', sessionId }));
+      }
+    });
+
+    ws.on('message', (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        return;
+      }
+
+      if (msg.type === 'auth_ok') {
+        ws.send(JSON.stringify({ type: 'attach', sessionId }));
+        return;
+      }
+
+      if (msg.type === 'attached') {
+        // Set terminal title to show we're attached
+        process.stdout.write(`\x1b]0;[termbeam] ${sessionName} — ${detachLabel} to detach\x07`);
+
+        const refs = {};
+        enterRawMode(ws, detachKey, cleanup, refs);
+        onData = refs.onData;
+        onSigwinch = refs.onSigwinch;
+        sendResize(ws);
+        debounceBanner();
+        return;
+      }
+
+      if (msg.type === 'output') {
+        debounceBanner();
+        process.stdout.write(msg.data);
+        return;
+      }
+
+      if (msg.type === 'exit') {
+        cleanup(`session exited with code ${msg.code}`);
+        return;
+      }
+
+      if (msg.type === 'error') {
+        cleanup(`error: ${msg.message}`);
+        return;
+      }
+    });
+
+    ws.on('error', (err) => {
+      if (!cleaned) {
+        cleaned = true;
+        resetTerminal();
+        reject(err);
+      }
+    });
+
+    ws.on('close', () => {
+      cleanup('connection closed');
+    });
+  });
+}
+
+function enterRawMode(ws, detachKey, cleanup, refs) {
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+  }
+  process.stdin.resume();
+
+  refs.onData = (data) => {
+    const str = data.toString();
+    if (str === detachKey) {
+      cleanup('detached');
+      return;
+    }
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'input', data: str }));
+    }
+  };
+  process.stdin.on('data', refs.onData);
+
+  refs.onSigwinch = () => sendResize(ws);
+  process.on('SIGWINCH', refs.onSigwinch);
+}
+
+function sendResize(ws) {
+  if (ws.readyState === WebSocket.OPEN && process.stdout.columns && process.stdout.rows) {
+    ws.send(
+      JSON.stringify({
+        type: 'resize',
+        cols: process.stdout.columns,
+        rows: process.stdout.rows,
+      }),
+    );
+  }
+}
+
+module.exports = { createTerminalClient };

package/src/resume.js

@@ -0,0 +1,387 @@
+const http = require('http');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const { createTerminalClient } = require('./client');
+const { bold, dim, red, yellow, choose, createRL, ask } = require('./prompts');
+
+const CONFIG_DIR = process.env.TERMBEAM_CONFIG_DIR || path.join(os.homedir(), '.termbeam');
+const CONNECTION_FILE = path.join(CONFIG_DIR, 'connection.json');
+
+// ── Connection config ────────────────────────────────────────────────────────
+
+function readConnectionConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONNECTION_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeConnectionConfig({ port, host, password }) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONNECTION_FILE, JSON.stringify({ port, host, password }, null, 2) + '\n', {
+    mode: 0o600,
+  });
+  // Ensure restrictive permissions even if the file already existed
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(CONNECTION_FILE, 0o600);
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+function removeConnectionConfig() {
+  try {
+    fs.unlinkSync(CONNECTION_FILE);
+  } catch {
+    /* ignore */
+  }
+}
+
+// ── Arg parsing ──────────────────────────────────────────────────────────────
+
+function parseDetachKey(value) {
+  // \xNN hex escape → control character
+  const hexMatch = value.match(/^\\x([0-9a-fA-F]{2})$/);
+  if (hexMatch) return String.fromCharCode(parseInt(hexMatch[1], 16));
+  // ^X or ctrl+X → control character
+  const caretMatch = value.match(/^\^([A-Za-z])$/);
+  if (caretMatch) return String.fromCharCode(caretMatch[1].toUpperCase().charCodeAt(0) - 64);
+  const ctrlMatch = value.match(/^ctrl\+([A-Za-z])$/i);
+  if (ctrlMatch) return String.fromCharCode(ctrlMatch[1].toUpperCase().charCodeAt(0) - 64);
+  return value;
+}
+
+function parseResumeArgs(args) {
+  let name = null;
+  let port = null;
+  let host = null;
+  let password = null;
+  let detachKey = null;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--port' && args[i + 1]) {
+      port = parseInt(args[++i], 10);
+    } else if (args[i] === '--host' && args[i + 1]) {
+      host = args[++i];
+    } else if (args[i] === '--password' && args[i + 1]) {
+      password = args[++i];
+    } else if (args[i].startsWith('--password=')) {
+      password = args[i].split('=')[1];
+    } else if (args[i] === '--detach-key' && args[i + 1]) {
+      detachKey = parseDetachKey(args[++i]);
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      return { help: true };
+    } else if (args[i].startsWith('--')) {
+      console.error(`Unknown flag: ${args[i]}`);
+      process.exitCode = 1;
+      return { help: true };
+    } else if (!args[i].startsWith('-')) {
+      name = args[i];
+    }
+  }
+
+  return { name, port, host, password, detachKey };
+}
+
+// ── HTTP helpers ─────────────────────────────────────────────────────────────
+
+function httpRequest(urlStr, options = {}) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlStr);
+    const reqOpts = {
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname,
+      method: options.method || 'GET',
+      headers: { ...options.headers },
+    };
+
+    const req = http.request(reqOpts, (res) => {
+      let body = '';
+      res.on('data', (chunk) => (body += chunk));
+      res.on('end', () => resolve({ status: res.statusCode, body, headers: res.headers }));
+    });
+    req.on('error', reject);
+    if (options.body) req.write(options.body);
+    req.end();
+  });
+}
+
+async function fetchSessions(baseUrl, password) {
+  const headers = {};
+  if (password) headers.Authorization = `Bearer ${password}`;
+
+  const res = await httpRequest(`${baseUrl}/api/sessions`, { headers });
+  if (res.status === 401) {
+    throw new Error('unauthorized');
+  }
+  if (res.status >= 400) {
+    throw new Error(`HTTP ${res.status}: ${res.body}`);
+  }
+  return JSON.parse(res.body);
+}
+
+// ── Formatting ───────────────────────────────────────────────────────────────
+
+function formatUptime(createdAt) {
+  const ms = Date.now() - new Date(createdAt).getTime();
+  const secs = Math.floor(ms / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ${mins % 60}m`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ${hours % 24}h`;
+}
+
+function shortId(id) {
+  return id.slice(0, 8);
+}
+
+// ── Help text ────────────────────────────────────────────────────────────────
+
+function detachKeyLabel(key) {
+  if (!key || key === '\x02') return 'Ctrl+B';
+  if (key.length === 1 && key.charCodeAt(0) < 27) {
+    return `Ctrl+${String.fromCharCode(key.charCodeAt(0) + 64)}`;
+  }
+  return key;
+}
+
+function printResumeHelp() {
+  console.log(`
+${bold('termbeam resume')} — Reconnect to a running session
+
+${bold('Usage:')}
+  termbeam resume [name] [options]
+
+${bold('Arguments:')}
+  name                  Session name to connect to (auto-selects if unique match)
+
+${bold('Options:')}
+  --port <port>         Server port (default: from ~/.termbeam/connection.json or 3456)
+  --host <host>         Server host (default: from config or localhost)
+  --password <pw>       Server password (default: from config or prompt)
+  --detach-key <key>    Detach key combo (default: Ctrl+B)
+  -h, --help            Show this help
+
+${bold('Examples:')}
+  termbeam resume                     Select from running sessions
+  termbeam resume my-project          Connect to session named "my-project"
+  termbeam resume --port 4000         Connect to server on port 4000
+
+${dim('Press Ctrl+B to detach from a session without closing it.')}
+`);
+}
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+
+async function resolveConnection(args) {
+  const opts = parseResumeArgs(args);
+  if (opts.help) return { help: true };
+
+  const saved = readConnectionConfig();
+  const host = opts.host || (saved && saved.host) || 'localhost';
+  const port = opts.port || (saved && saved.port) || 3456;
+  let password = opts.password || (saved && saved.password) || null;
+  const connHost = host === 'localhost' ? '127.0.0.1' : host;
+  const baseUrl = `http://${connHost}:${port}`;
+  const displayUrl = `http://${connHost === '127.0.0.1' ? 'localhost' : connHost}:${port}`;
+
+  // Try to fetch sessions, handle auth errors
+  let sessions;
+  try {
+    sessions = await fetchSessions(baseUrl, password);
+  } catch (err) {
+    if (err.message === 'unauthorized') {
+      // Prompt for password if none was explicitly provided
+      if (!opts.password) {
+        const rl = createRL();
+        password = await ask(rl, `  Password for ${displayUrl}:`);
+        rl.close();
+        try {
+          sessions = await fetchSessions(baseUrl, password);
+        } catch {
+          console.error(red('  Authentication failed.'));
+          process.exit(1);
+        }
+      } else {
+        console.error(red('  Authentication failed.'));
+        process.exit(1);
+      }
+    } else if (err.code === 'ECONNREFUSED') {
+      return { refused: true, displayUrl };
+    } else {
+      throw err;
+    }
+  }
+
+  return { host, port, password, baseUrl, displayUrl, sessions, opts };
+}
+
+async function resume(args) {
+  if (process.env.TERMBEAM_SESSION) {
+    console.error(red('  Already inside a TermBeam session. Detach first (Ctrl+B).'));
+    process.exit(1);
+  }
+
+  const conn = await resolveConnection(args);
+  if (conn.help) {
+    printResumeHelp();
+    return;
+  }
+  if (conn.refused) {
+    console.error(red('  No TermBeam server is running.'));
+    process.exit(1);
+  }
+
+  const { host, port, password, sessions, opts } = conn;
+
+  if (sessions.length === 0) {
+    console.error(red('  No active sessions on the server.'));
+    process.exit(1);
+  }
+
+  let session;
+
+  if (opts.name) {
+    // Match by name (case-insensitive) or by ID prefix
+    session =
+      sessions.find((s) => s.name.toLowerCase() === opts.name.toLowerCase()) ||
+      sessions.find((s) => s.id.startsWith(opts.name));
+
+    if (!session) {
+      console.error(red(`  No session matching "${opts.name}".`));
+      console.log(dim('  Available sessions:'));
+      for (const s of sessions) {
+        console.log(dim(`    ${s.name} (${shortId(s.id)})`));
+      }
+      process.exit(1);
+    }
+  } else if (sessions.length === 1) {
+    session = sessions[0];
+  } else {
+    // Interactive chooser
+    const rl = createRL();
+    const choices = sessions.map((s) => ({
+      label: `${s.name}  ${dim(shortId(s.id))}`,
+      hint: `${s.cwd}  ·  ${formatUptime(s.createdAt)}  ·  ${s.clients} client${s.clients !== 1 ? 's' : ''}`,
+    }));
+
+    console.log('');
+    const { index } = await choose(rl, `  ${bold('Select a session:')}`, choices);
+    rl.close();
+    session = sessions[index];
+  }
+
+  const wsHost = host === 'localhost' ? '127.0.0.1' : host;
+  const wsUrl = `ws://${wsHost}:${port}/ws`;
+  const detachKey = opts.detachKey || '\x02';
+
+  try {
+    const { reason } = await createTerminalClient({
+      url: wsUrl,
+      password,
+      sessionId: session.id,
+      sessionName: session.name,
+      detachKey,
+      detachLabel: detachKeyLabel(detachKey),
+    });
+
+    console.log('');
+    if (reason === 'detached') {
+      console.log(yellow(`  Detached from ${bold(session.name)}.`));
+    } else if (reason && reason.startsWith('session exited')) {
+      console.log(dim(`  Session ${bold(session.name)} ended.`));
+    } else {
+      console.log(dim(`  Disconnected from ${bold(session.name)}.`));
+    }
+  } catch (err) {
+    console.error(red(`  Connection failed: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+async function list() {
+  const saved = readConnectionConfig();
+  const host = (saved && saved.host) || 'localhost';
+  const port = (saved && saved.port) || 3456;
+  let password = (saved && saved.password) || null;
+  const connHost = host === 'localhost' ? '127.0.0.1' : host;
+  const baseUrl = `http://${connHost}:${port}`;
+  const displayUrl = `http://${connHost === '127.0.0.1' ? 'localhost' : connHost}:${port}`;
+
+  let sessions;
+  try {
+    sessions = await fetchSessions(baseUrl, password);
+  } catch (err) {
+    if (err.message === 'unauthorized') {
+      if (!password) {
+        const rl = createRL();
+        password = await ask(rl, `  Password for ${displayUrl}:`);
+        rl.close();
+        try {
+          sessions = await fetchSessions(baseUrl, password);
+        } catch {
+          console.error(red('  Authentication failed.'));
+          process.exit(1);
+        }
+      } else {
+        console.error(red('  Authentication failed.'));
+        process.exit(1);
+      }
+    } else if (err.code === 'ECONNREFUSED') {
+      console.log(dim('  No TermBeam server is running.'));
+      return;
+    } else {
+      console.error(red(`  Connection failed: ${err.message}`));
+      process.exit(1);
+    }
+  }
+
+  if (sessions.length === 0) {
+    console.log(dim('  No active sessions.'));
+    return;
+  }
+
+  console.log('');
+  console.log(
+    bold(`  ${sessions.length} session${sessions.length !== 1 ? 's' : ''} on ${displayUrl}`),
+  );
+  console.log('');
+
+  // Table header
+  const nameW = Math.max(6, ...sessions.map((s) => s.name.length));
+  const cwdW = Math.max(4, ...sessions.map((s) => s.cwd.length));
+
+  console.log(
+    dim(
+      `  ${'NAME'.padEnd(nameW)}  ${'ID'.padEnd(8)}  ${'CWD'.padEnd(cwdW)}  ${'UPTIME'.padEnd(8)}  CLIENTS`,
+    ),
+  );
+
+  for (const s of sessions) {
+    const uptime = formatUptime(s.createdAt);
+    console.log(
+      `  ${bold(s.name.padEnd(nameW))}  ${dim(shortId(s.id).padEnd(8))}  ${s.cwd.padEnd(cwdW)}  ${uptime.padEnd(8)}  ${s.clients}`,
+    );
+  }
+  console.log('');
+}
+
+module.exports = {
+  resume,
+  list,
+  writeConnectionConfig,
+  removeConnectionConfig,
+  readConnectionConfig,
+  printResumeHelp,
+  parseDetachKey,
+  CONFIG_DIR,
+  CONNECTION_FILE,
+};

package/src/routes.js

@@ -69,7 +69,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       const token = auth.generateToken();
       res.cookie('pty_token', token, {
         httpOnly: true,
-        sameSite: 'lax',
+        sameSite: 'strict',
         maxAge: 24 * 60 * 60 * 1000,
         secure: req.secure,
       });
@@ -99,7 +99,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       const token = auth.generateToken();
       res.cookie('pty_token', token, {
         httpOnly: true,
-        sameSite: 'lax',
+        sameSite: 'strict',
         maxAge: 24 * 60 * 60 * 1000,
         secure: req.secure,
       });

package/src/server.js

@@ -15,6 +15,7 @@ const { setupRoutes, cleanupUploadedFiles } = require('./routes');
 const { setupWebSocket } = require('./websocket');
 const { startTunnel, cleanupTunnel, findDevtunnel } = require('./tunnel');
 const { createPreviewProxy } = require('./preview');
+const { writeConnectionConfig, removeConnectionConfig } = require('./resume');
 
 // --- Helpers ---
 function getLocalIP() {
@@ -85,10 +86,30 @@ function createTermBeamServer(overrides = {}) {
     sessions.shutdown();
     cleanupUploadedFiles();
     cleanupTunnel();
+    removeConnectionConfig();
     server.close();
     wss.close();
   }
 
+  // Shutdown endpoint for --force (loopback only)
+  app.post('/api/shutdown', auth.middleware, (req, res) => {
+    const remoteAddress = req.socket && req.socket.remoteAddress;
+    if (
+      remoteAddress !== '127.0.0.1' &&
+      remoteAddress !== '::1' &&
+      remoteAddress !== '::ffff:127.0.0.1'
+    ) {
+      res.status(403).json({ error: 'Shutdown is only available from localhost' });
+      return;
+    }
+    res.json({ ok: true });
+    console.log('\n[termbeam] Shutdown requested by another instance. Goodbye!');
+    setTimeout(() => {
+      shutdown();
+      process.exit(0);
+    }, 100);
+  });
+
   async function start() {
     // If tunnel mode is on but devtunnel is missing, offer to install it
     if (config.useTunnel && !findDevtunnel()) {
@@ -134,8 +155,27 @@ function createTermBeamServer(overrides = {}) {
 
     return new Promise((resolve) => {
       server.listen(config.port, config.host, async () => {
+        const actualPort = server.address().port;
         const ip = getLocalIP();
-        const localUrl = `http://${ip}:${config.port}`;
+        const localUrl = `http://${ip}:${actualPort}`;
+
+        // Save connection info for `termbeam resume` auto-discovery
+        try {
+          const connHost =
+            config.host === '0.0.0.0' ||
+            config.host === '127.0.0.1' ||
+            config.host === '::' ||
+            config.host === '::1'
+              ? 'localhost'
+              : config.host;
+          writeConnectionConfig({
+            port: actualPort,
+            host: connHost,
+            password: config.password || null,
+          });
+        } catch {
+          /* non-critical — resume will fall back to defaults */
+        }
 
         const defaultId = sessions.create({
           name: path.basename(config.cwd),
@@ -170,7 +210,7 @@ function createTermBeamServer(overrides = {}) {
         console.log('');
         const isLanReachable =
           config.host === '0.0.0.0' || config.host === '::' || config.host === ip;
-        state.shareBaseUrl = isLanReachable ? localUrl : `http://localhost:${config.port}`;
+        state.shareBaseUrl = isLanReachable ? localUrl : `http://localhost:${actualPort}`;
         const gn = '\x1b[38;5;114m'; // green
         const _dm = '\x1b[2m'; // dim
 
@@ -178,7 +218,7 @@ function createTermBeamServer(overrides = {}) {
 
         let publicUrl = null;
         if (config.useTunnel) {
-          const tunnel = await startTunnel(config.port, {
+          const tunnel = await startTunnel(actualPort, {
             persisted: config.persistedTunnel,
             anonymous: config.publicTunnel,
           });
@@ -203,12 +243,12 @@ function createTermBeamServer(overrides = {}) {
         if (publicUrl) {
           console.log(`  Public:   ${bl}${publicUrl}${rs}`);
         }
-        console.log(`  Local:    http://localhost:${config.port}`);
+        console.log(`  Local:    http://localhost:${actualPort}`);
         if (isLanReachable) {
           console.log(`  LAN:      ${localUrl}`);
         }
 
-        const qrUrl = publicUrl || (isLanReachable ? localUrl : `http://localhost:${config.port}`);
+        const qrUrl = publicUrl || (isLanReachable ? localUrl : `http://localhost:${actualPort}`);
         const qrDisplayUrl = qrUrl; // clean URL shown in console text
         const qrCodeUrl = config.password ? `${qrUrl}?ott=${auth.generateShareToken()}` : qrUrl;
         console.log('');
@@ -223,7 +263,7 @@ function createTermBeamServer(overrides = {}) {
         if (config.password) process.stdout.write(`  Password: ${gn}${config.password}${rs}\n`);
         console.log('');
 
-        resolve({ url: `http://localhost:${config.port}`, defaultId });
+        resolve({ url: `http://localhost:${actualPort}`, defaultId });
       });
     });
   }

package/src/sessions.js

@@ -136,7 +136,7 @@ class SessionManager {
       cols,
       rows,
       cwd,
-      env: { ...process.env, TERM: 'xterm-256color' },
+      env: { ...process.env, TERM: 'xterm-256color', TERMBEAM_SESSION: '1' },
     });
 
     // Send initial command once the shell is ready