termbeam 0.0.6 → 0.0.8

package/README.md

@@ -1,40 +1,21 @@
-<div align="center">
+# TermBeam
 
-# 📡 TermBeam
-
-**Beam your terminal to any device**
+**Beam your terminal to any device.**
 
 [![npm version](https://img.shields.io/npm/v/termbeam.svg)](https://www.npmjs.com/package/termbeam)
 [![CI](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml/badge.svg)](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/dorlugasigal/TermBeam/coverage-data/endpoint.json)](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
-
-Access your terminal from your phone, tablet, or any browser.
-Multi-session, mobile-optimized, with touch controls.
 
-[Getting Started](#-quick-start) · [Demo](#-demo) · [Documentation](https://dorlugasigal.github.io/TermBeam/) · [Contributing](CONTRIBUTING.md)
+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.
 
-</div>
+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-friendly UI that actually works on small screens.
 
----
+[Full documentation](https://dorlugasigal.github.io/TermBeam/)
 
 https://github.com/user-attachments/assets/c91ca15d-0c84-400f-bbfa-3d58d1be07ee
 
-## ✨ Features
-
-- 📱 **Mobile-first UI** — Touch-friendly interface designed for phones and tablets
-- 🖥️ **Multi-session** — Run multiple terminal sessions simultaneously
-- 🔐 **Password auth** — Token-based authentication with rate limiting
-- 📂 **Folder browser** — Visual directory picker with breadcrumb navigation
-- 👆 **Touch controls** — Arrow keys, Ctrl shortcuts, Tab, Esc via on-screen touch bar
-- 🔤 **Nerd Font support** — Full glyph rendering with JetBrains Mono Nerd Font
-- 📲 **QR code** — Scan to connect instantly from your phone
-- 🌐 **DevTunnel** — Optional public URL for remote access from anywhere
-- 🔍 **Adjustable font size** — Pinch or button zoom for any screen
-- ↔️ **Swipe to delete** — iOS-style session management
-- 🔄 **Smart versioning** — Shows git hash in dev, clean version from npm
-
-## 🚀 Quick Start
+## Quick Start
 
 ```bash
 npx termbeam
@@ -47,124 +28,81 @@ npm install -g termbeam
 termbeam
 ```
 
-That's it. Scan the QR code printed in your terminal, or open the URL on any device.
+Scan the QR code printed in your terminal, or open the URL on any device.
 
-### With password protection (recommended)
+### Password protection (recommended)
 
 ```bash
-# Auto-generate a secure password
 termbeam --generate-password
 
-# Or set your own
+# or set your own
 termbeam --password mysecret
 ```
 
-### Remote access from anywhere
-
-```bash
-termbeam --tunnel --generate-password
-```
+## Features
 
-> Requires the [Azure Dev Tunnels CLI](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started):
->
-> - **Windows:** `winget install Microsoft.devtunnel`
-> - **macOS:** `brew install --cask devtunnel`
-> - **Linux:** `curl -sL https://aka.ms/DevTunnelCliInstall | bash`
+- **Mobile-first UI** with on-screen touch bar (arrow keys, Tab, Ctrl shortcuts, Esc) and swipe-to-delete session management
+- **Multiple sessions** running simultaneously, managed from a single hub page — shows connected client count per session
+- **Password auth** with token-based cookies and rate-limited login
+- **Folder browser** to pick working directories without typing paths
+- **Initial command** — optionally launch a session straight into `htop`, `vim`, or any command
+- **Shell detection** — auto-detects your shell on all platforms (PowerShell, cmd, bash, zsh, Git Bash, WSL)
+- **QR code on startup** for instant phone connection
+- **Light/dark theme** with persistent preference
+- **Adjustable font size** via status bar controls, saved across sessions
+- **Remote access via [DevTunnel](#remote-access)** — ephemeral or persisted public URLs
 
-## 📖 Usage
+## Remote Access
 
 ```bash
-# Start with your default shell
-termbeam
-
-# Use a specific shell
-termbeam /bin/bash
-
-# Custom port and listen on all interfaces (LAN access)
-termbeam --port 8080 --host 0.0.0.0
-
-# Public tunnel + password (access from anywhere)
+# One-off tunnel (deleted on shutdown)
 termbeam --tunnel --generate-password
-```
-
-### CLI Options
-
-| Flag                  | Description                     | Default     |
-| --------------------- | ------------------------------- | ----------- |
-| `--password <pw>`     | Set access password             | None        |
-| `--generate-password` | Auto-generate a secure password | —           |
-| `--tunnel`            | Create a public devtunnel URL   | Off         |
-| `--port <port>`       | Server port                     | `3456`      |
-| `--host <addr>`       | Bind address                    | `127.0.0.1` |
-| `-h, --help`          | Show help                       | —           |
-| `-v, --version`       | Show version                    | —           |
 
-### Environment Variables
-
-| Variable            | Description                     |
-| ------------------- | ------------------------------- |
-| `PORT`              | Server port (overrides default) |
-| `TERMBEAM_PASSWORD` | Access password                 |
-| `TERMBEAM_CWD`      | Default working directory       |
-
-## 🔒 Security
+# Persisted tunnel (stable URL you can bookmark, reused across restarts, 30-day expiry)
+termbeam --persisted-tunnel --generate-password
+```
 
-TermBeam is designed for **local network use**. Key security features:
+Requires the [Dev Tunnels CLI](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started):
 
-- 🔑 **Token-based auth** with secure, httpOnly cookies (24-hour expiry)
-- 🛡️ **Rate limiting** on login (5 attempts per minute)
-- 🔒 **Security headers** (X-Frame-Options, X-Content-Type-Options, CSP, etc.)
-- 🏠 **Localhost by default** — requires explicit `--host 0.0.0.0` for LAN access
+- **Windows:** `winget install Microsoft.devtunnel`
+- **macOS:** `brew install --cask devtunnel`
+- **Linux:** `curl -sL https://aka.ms/DevTunnelCliInstall | bash`
 
-> ⚠️ **Always use a password when exposing to any network.** See the [Security Guide](https://dorlugasigal.github.io/TermBeam/security/) for production deployment tips.
+Persisted tunnels save a tunnel ID to `~/.termbeam/tunnel.json` so the URL stays the same between sessions.
 
-## 🏗️ Architecture
+## CLI Reference
 
-```
-termbeam/
-├── bin/termbeam.js            # CLI entry point
-├── src/
-│   ├── server.js              # Main orchestrator
-│   ├── cli.js                 # Argument parsing & help
-│   ├── auth.js                # Authentication & rate limiting
-│   ├── sessions.js            # PTY session lifecycle
-│   ├── routes.js              # Express HTTP routes
-│   ├── websocket.js           # WebSocket terminal I/O
-│   ├── tunnel.js              # DevTunnel integration
-│   └── version.js             # Smart version detection
-├── public/
-│   ├── index.html             # Session manager UI (mobile)
-│   └── terminal.html          # Terminal UI (xterm.js)
-├── test/                      # Unit tests (node:test)
-├── docs/                      # MkDocs documentation
-└── .github/workflows/         # CI, Release, Docs deployment
+```bash
+termbeam [shell] [args...]        # start with a specific shell (default: auto-detect)
+termbeam --port 8080              # custom port (default: 3456)
+termbeam --host 127.0.0.1        # restrict to localhost (default: 0.0.0.0)
 ```
 
-See the [Architecture Guide](https://dorlugasigal.github.io/TermBeam/architecture/) for details.
+| Flag                  | Description                              | Default     |
+| --------------------- | ---------------------------------------- | ----------- |
+| `--password <pw>`     | Set access password                      | None        |
+| `--generate-password` | Auto-generate a secure password          | —           |
+| `--tunnel`            | Create an ephemeral devtunnel URL        | Off         |
+| `--persisted-tunnel`  | Create a reusable devtunnel URL          | Off         |
+| `--port <port>`       | Server port                              | `3456`      |
+| `--host <addr>`       | Bind address                             | `0.0.0.0`   |
 
-## 📚 Documentation
+Environment variables: `PORT`, `TERMBEAM_PASSWORD`, `TERMBEAM_CWD` (see [Configuration docs](https://dorlugasigal.github.io/TermBeam/configuration/)).
 
-Full documentation is available at **[dorlugasigal.github.io/TermBeam](https://dorlugasigal.github.io/TermBeam/)**
+## Security
 
-- [Getting Started](https://dorlugasigal.github.io/TermBeam/getting-started/)
-- [Configuration](https://dorlugasigal.github.io/TermBeam/configuration/)
-- [Security](https://dorlugasigal.github.io/TermBeam/security/)
-- [API Reference](https://dorlugasigal.github.io/TermBeam/api/)
-- [Architecture](https://dorlugasigal.github.io/TermBeam/architecture/)
+TermBeam binds to all interfaces (`0.0.0.0`) by default, so it's accessible on your local network out of the box. **Always set a password** when running on a shared network, or pass `--host 127.0.0.1` to restrict access to your machine only.
 
-## 🤝 Contributing
+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. API clients that can't use cookies can authenticate with an `Authorization: Bearer <password>` header. See the [Security Guide](https://dorlugasigal.github.io/TermBeam/security/) for more.
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+## Contributing
 
-- Development setup and local workflow
-- Testing guide (Node.js built-in test runner)
-- Commit conventions and PR process
-- Release process (maintainers)
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## 📄 License
+## License
 
-[MIT](LICENSE) — made with ❤️ by [@dorlugasigal](https://github.com/dorlugasigal)
+[MIT](LICENSE)
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
 Special thanks to [@tamirdresher](https://github.com/tamirdresher) for the [blog post](https://www.tamirdresher.com/blog/2026/02/26/squad-remote-control) that inspired the solution idea for this project, and for his [cli-tunnel](https://github.com/tamirdresher/cli-tunnel) implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {
@@ -10,6 +10,7 @@
     "start": "node bin/termbeam.js",
     "dev": "node bin/termbeam.js --generate-password",
     "test": "node --test test/*.test.js",
+    "test:coverage": "c8 --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node --test --test-reporter=spec --test-reporter-destination=stdout test/*.test.js",
     "prepare": "husky",
     "format": "prettier --write .",
     "lint": "node --check src/*.js bin/*.js",
@@ -62,6 +63,7 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
     "prettier": "^3.8.1"

package/public/icons/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="80" fill="#1e1e1e"/>
+  <rect x="32" y="32" width="448" height="448" rx="56" fill="#252526" stroke="#3c3c3c" stroke-width="4"/>
+  <polyline points="140,200 220,260 140,320" fill="none" stroke="#0078d4" stroke-width="32" stroke-linecap="round" stroke-linejoin="round"/>
+  <line x1="260" y1="320" x2="380" y2="320" stroke="#d4d4d4" stroke-width="28" stroke-linecap="round"/>
+</svg>

package/public/index.html

@@ -9,6 +9,8 @@
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="theme-color" content="#1e1e1e" />
+    <link rel="manifest" href="/manifest.json" />
+    <link rel="apple-touch-icon" href="/icons/icon-192.png" />
     <title>TermBeam</title>
     <style>
       :root {
@@ -941,6 +943,10 @@
 
       loadSessions();
       setInterval(loadSessions, 3000);
+
+      if ('serviceWorker' in navigator) {
+        navigator.serviceWorker.register('/sw.js').catch(() => {});
+      }
     </script>
   </body>
 </html>

package/public/manifest.json

@@ -0,0 +1,14 @@
+{
+  "name": "TermBeam",
+  "short_name": "TermBeam",
+  "description": "Beam your terminal to any device",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#1e1e1e",
+  "theme_color": "#1e1e1e",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
+    { "src": "/icons/icon.svg", "sizes": "any", "type": "image/svg+xml" }
+  ]
+}

package/public/sw.js

@@ -0,0 +1,54 @@
+const CACHE_NAME = 'termbeam-v1';
+const SHELL_URLS = ['/', '/terminal'];
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(SHELL_URLS))
+  );
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
+    )
+  );
+  self.clients.claim();
+});
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+
+  // Don't cache WebSocket upgrades or external resources
+  if (
+    event.request.mode === 'websocket' ||
+    url.protocol === 'ws:' ||
+    url.protocol === 'wss:' ||
+    url.origin !== self.location.origin
+  ) {
+    return;
+  }
+
+  // Network-first for API calls
+  if (url.pathname.startsWith('/api/')) {
+    event.respondWith(
+      fetch(event.request).catch(() => caches.match(event.request))
+    );
+    return;
+  }
+
+  // Cache-first for static assets
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      if (cached) return cached;
+      return fetch(event.request).then((response) => {
+        if (response.ok) {
+          const clone = response.clone();
+          caches.open(CACHE_NAME).then((cache) => cache.put(event.request, clone));
+        }
+        return response;
+      });
+    })
+  );
+});

package/public/terminal.html

@@ -9,6 +9,8 @@
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="theme-color" content="#1e1e1e" />
+    <link rel="manifest" href="/manifest.json" />
+    <link rel="apple-touch-icon" href="/icons/icon-192.png" />
     <title>TermBeam — Terminal</title>
     <link
       rel="stylesheet"
@@ -283,6 +285,64 @@
         overflow-y: hidden !important;
       }
 
+      #copy-toast {
+        position: fixed;
+        top: 56px;
+        left: 50%;
+        transform: translateX(-50%) translateY(-8px);
+        background: var(--surface);
+        color: var(--text);
+        border: 1px solid var(--border);
+        padding: 6px 16px;
+        border-radius: 8px;
+        font-size: 13px;
+        font-weight: 600;
+        opacity: 0;
+        pointer-events: none;
+        transition: opacity 0.2s, transform 0.2s;
+        z-index: 200;
+      }
+      #copy-toast.visible {
+        opacity: 1;
+        transform: translateX(-50%) translateY(0);
+      }
+
+      #paste-overlay {
+        display: none;
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background: var(--overlay-bg);
+        z-index: 150;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 12px;
+      }
+      #paste-overlay.visible {
+        display: flex;
+      }
+      #paste-overlay label {
+        font-size: 15px;
+        color: #ffffff;
+        font-weight: 600;
+      }
+      #paste-input {
+        width: 80%;
+        max-width: 400px;
+        min-height: 80px;
+        background: var(--surface);
+        color: var(--text);
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        padding: 10px;
+        font-size: 14px;
+        font-family: 'NerdFont', 'JetBrains Mono', monospace;
+        resize: vertical;
+      }
+
       #reconnect-overlay {
         display: none;
         position: fixed;
@@ -357,6 +417,7 @@
     </div>
 
     <div id="terminal-container"></div>
+    <div id="copy-toast">Copied!</div>
 
     <div id="key-bar">
       <button class="key-btn" data-key="&#x1b;[A" title="Previous command">↑<span class="hint">prev</span></button>
@@ -366,6 +427,8 @@
       <button class="key-btn" data-key="&#x1b;[H" title="Home">Home</button>
       <button class="key-btn" data-key="&#x1b;[F" title="End">End</button>
       <div class="key-sep"></div>
+      <button class="key-btn" id="paste-btn" title="Paste from clipboard">Paste</button>
+      <div class="key-sep"></div>
       <button class="key-btn wide" data-key="&#x09;" title="Autocomplete">Tab</button>
       <div class="key-sep"></div>
       <button class="key-btn" data-key="&#x03;" title="Interrupt process">^C<span class="hint">stop</span></button>
@@ -379,6 +442,15 @@
       </div>
     </div>
 
+    <div id="paste-overlay">
+      <label for="paste-input">Paste your text below</label>
+      <textarea id="paste-input" placeholder="Long-press here and paste…"></textarea>
+      <div class="overlay-actions">
+        <button id="paste-cancel" style="background: rgba(255,255,255,0.15); color: #ffffff;">Cancel</button>
+        <button id="paste-send" style="background: var(--accent); color: #ffffff;">Send</button>
+      </div>
+    </div>
+
     <script src="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"></script>
@@ -573,7 +645,7 @@
           .addEventListener('touchstart', () => {}, { passive: true });
         document.getElementById('key-bar').addEventListener('click', (e) => {
           const btn = e.target.closest('.key-btn');
-          if (!btn) return;
+          if (!btn || !btn.dataset.key) return;
           if (ws && ws.readyState === 1) {
             ws.send(JSON.stringify({ type: 'input', data: btn.dataset.key }));
           }
@@ -592,6 +664,66 @@
         document.getElementById('zoom-in').addEventListener('click', () => applyZoom(fontSize + 2));
         document.getElementById('zoom-out').addEventListener('click', () => applyZoom(fontSize - 2));
 
+        // Clipboard: copy on selection
+        function showToast(msg) {
+          const toast = document.getElementById('copy-toast');
+          toast.textContent = msg;
+          toast.classList.add('visible');
+          clearTimeout(toast._timer);
+          toast._timer = setTimeout(() => toast.classList.remove('visible'), 1500);
+        }
+
+        term.onSelectionChange(() => {
+          const sel = term.getSelection();
+          if (sel && navigator.clipboard && navigator.clipboard.writeText) {
+            navigator.clipboard.writeText(sel).then(() => {
+              showToast('Copied!');
+            }).catch(() => {});
+          }
+        });
+
+        // Clipboard: paste button
+        const pasteOverlay = document.getElementById('paste-overlay');
+        const pasteInput = document.getElementById('paste-input');
+
+        function openPasteModal() {
+          pasteInput.value = '';
+          pasteOverlay.classList.add('visible');
+          pasteInput.focus();
+        }
+
+        function closePasteModal() {
+          pasteOverlay.classList.remove('visible');
+          pasteInput.value = '';
+        }
+
+        document.getElementById('paste-btn').addEventListener('mousedown', (e) => {
+          e.preventDefault();
+        });
+        document.getElementById('paste-btn').addEventListener('click', () => {
+          if (navigator.clipboard && navigator.clipboard.readText) {
+            navigator.clipboard.readText().then((text) => {
+              if (text && ws && ws.readyState === 1) {
+                ws.send(JSON.stringify({ type: 'input', data: text }));
+                showToast('Pasted!');
+              }
+            }).catch(() => {
+              openPasteModal();
+            });
+          } else {
+            openPasteModal();
+          }
+        });
+
+        document.getElementById('paste-send').addEventListener('click', () => {
+          const text = pasteInput.value;
+          if (text && ws && ws.readyState === 1) {
+            ws.send(JSON.stringify({ type: 'input', data: text }));
+          }
+          closePasteModal();
+        });
+        document.getElementById('paste-cancel').addEventListener('click', closePasteModal);
+
         function scheduleReconnect() {
           if (reconnectTimer) clearTimeout(reconnectTimer);
           const seconds = Math.round(reconnectDelay / 1000);
@@ -671,6 +803,10 @@
 
         connect();
       }
+
+      if ('serviceWorker' in navigator) {
+        navigator.serviceWorker.register('/sw.js').catch(() => {});
+      }
     </script>
   </body>
 </html>

package/src/cli.js

@@ -12,7 +12,8 @@ Usage:
 Options:
   --password <pw>       Set access password (or TERMBEAM_PASSWORD env var)
   --generate-password   Auto-generate a secure password
-  --tunnel              Create a public devtunnel URL
+  --tunnel              Create a public devtunnel URL (ephemeral)
+  --persisted-tunnel    Create a reusable devtunnel URL (stable across restarts)
   --port <port>         Set port (default: 3456, or PORT env var)
   --host <addr>         Bind address (default: 0.0.0.0)
   -h, --help            Show this help
@@ -90,6 +91,7 @@ function parseArgs() {
   const cwd = process.env.TERMBEAM_CWD || process.env.PTY_CWD || process.cwd();
   let password = process.env.TERMBEAM_PASSWORD || process.env.PTY_PASSWORD || null;
   let useTunnel = false;
+  let persistedTunnel = false;
 
   const args = process.argv.slice(2);
   const filteredArgs = [];
@@ -99,6 +101,9 @@ function parseArgs() {
       password = args[++i];
     } else if (args[i] === '--tunnel') {
       useTunnel = true;
+    } else if (args[i] === '--persisted-tunnel') {
+      useTunnel = true;
+      persistedTunnel = true;
     } else if (args[i].startsWith('--password=')) {
       password = args[i].split('=')[1];
     } else if (args[i] === '--help' || args[i] === '-h') {
@@ -126,7 +131,7 @@ function parseArgs() {
   const { getVersion } = require('./version');
   const version = getVersion();
 
-  return { port, host, password, useTunnel, shell, shellArgs, cwd, defaultShell, version };
+  return { port, host, password, useTunnel, persistedTunnel, shell, shellArgs, cwd, defaultShell, version };
 }
 
 module.exports = { parseArgs, printHelp };

package/src/routes.js

@@ -1,11 +1,15 @@
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
+const express = require('express');
 const { detectShells } = require('./shells');
 
 const PUBLIC_DIR = path.join(__dirname, '..', 'public');
 
 function setupRoutes(app, { auth, sessions, config }) {
+  // Serve static files (manifest.json, sw.js, icons, etc.)
+  app.use(express.static(PUBLIC_DIR, { index: false }));
+
   // Login page
   app.get('/login', (_req, res) => {
     if (!auth.password) return res.redirect('/');

package/src/server.js

@@ -38,11 +38,17 @@ setupRoutes(app, { auth, sessions, config });
 setupWebSocket(wss, { auth, sessions });
 
 // --- Lifecycle ---
+let shuttingDown = false;
 function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
   console.log('\n[termbeam] Shutting down...');
   sessions.shutdown();
   cleanupTunnel();
-  process.exit(0);
+  server.close();
+  wss.close();
+  // Force exit after giving connections time to close
+  setTimeout(() => process.exit(0), 500).unref();
 }
 
 process.on('SIGINT', shutdown);
@@ -52,7 +58,6 @@ process.on('uncaughtException', (err) => {
   cleanupTunnel();
   process.exit(1);
 });
-process.on('exit', cleanupTunnel);
 
 // --- Start ---
 function getLocalIP() {
@@ -112,10 +117,12 @@ server.listen(config.port, config.host, async () => {
 
   let publicUrl = null;
   if (config.useTunnel) {
-    publicUrl = await startTunnel(config.port);
-    if (publicUrl) {
+    const tunnel = await startTunnel(config.port, { persisted: config.persistedTunnel });
+    if (tunnel) {
+      publicUrl = tunnel.url;
       console.log('');
       console.log(`  🌐 Public:  ${publicUrl}`);
+      console.log(`  Tunnel:   ${tunnel.mode} (expires in ${tunnel.expiry})`);
     } else {
       console.log('');
       console.log('  ⚠️  Tunnel failed to start. Using LAN only.');

package/src/tunnel.js

@@ -1,6 +1,10 @@
 const { execSync, spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
+const os = require('os');
+
+const TUNNEL_CONFIG_DIR = path.join(os.homedir(), '.termbeam');
+const TUNNEL_CONFIG_PATH = path.join(TUNNEL_CONFIG_DIR, 'tunnel.json');
 
 let tunnelId = null;
 let tunnelProc = null;
@@ -29,7 +33,45 @@ function findDevtunnel() {
   return null;
 }
 
-async function startTunnel(port) {
+function loadPersistedTunnel() {
+  try {
+    if (fs.existsSync(TUNNEL_CONFIG_PATH)) {
+      return JSON.parse(fs.readFileSync(TUNNEL_CONFIG_PATH, 'utf-8'));
+    }
+  } catch {}
+  return null;
+}
+
+function savePersistedTunnel(id) {
+  fs.mkdirSync(TUNNEL_CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(TUNNEL_CONFIG_PATH, JSON.stringify({ tunnelId: id, createdAt: new Date().toISOString() }, null, 2));
+}
+
+function deletePersisted() {
+  const persisted = loadPersistedTunnel();
+  if (persisted) {
+    try {
+      execSync(`"${devtunnelCmd}" delete ${persisted.tunnelId} -f`, { stdio: 'pipe' });
+      console.log(`[termbeam] Deleted persisted tunnel ${persisted.tunnelId}`);
+    } catch {}
+    try {
+      fs.unlinkSync(TUNNEL_CONFIG_PATH);
+    } catch {}
+  }
+}
+
+function isTunnelValid(id) {
+  try {
+    execSync(`"${devtunnelCmd}" show ${id} --json`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+let isPersisted = false;
+
+async function startTunnel(port, options = {}) {
   // Check if devtunnel CLI is installed
   const found = findDevtunnel();
   if (!found) {
@@ -66,16 +108,48 @@ async function startTunnel(port) {
       execSync(`"${devtunnelCmd}" user login`, { stdio: 'inherit' });
     }
 
-    const createOut = execSync(`"${devtunnelCmd}" create --expiration 1d --json`, { encoding: 'utf-8' });
-    const tunnelData = JSON.parse(createOut);
-    tunnelId = tunnelData.tunnel.tunnelId;
+    const persisted = options.persisted;
+    isPersisted = !!persisted;
 
-    execSync(`"${devtunnelCmd}" port create ${tunnelId} -p ${port} --protocol http`, { stdio: 'pipe' });
-    execSync(`"${devtunnelCmd}" access create ${tunnelId} -p ${port} --anonymous`, { stdio: 'pipe' });
+    // Try to reuse persisted tunnel
+    let tunnelMode, tunnelExpiry;
+    if (persisted) {
+      tunnelMode = 'persisted';
+      tunnelExpiry = '30 days';
+      const saved = loadPersistedTunnel();
+      if (saved && isTunnelValid(saved.tunnelId)) {
+        tunnelId = saved.tunnelId;
+        console.log(`[termbeam] Reusing persisted tunnel ${tunnelId}`);
+      } else {
+        if (saved) {
+          console.log('[termbeam] Persisted tunnel expired, creating new one');
+        }
+        const createOut = execSync(`"${devtunnelCmd}" create --expiration 30d --json`, { encoding: 'utf-8' });
+        const tunnelData = JSON.parse(createOut);
+        tunnelId = tunnelData.tunnel.tunnelId;
+        savePersistedTunnel(tunnelId);
+        console.log(`[termbeam] Created new persisted tunnel ${tunnelId}`);
+      }
+    } else {
+      tunnelMode = 'ephemeral';
+      tunnelExpiry = '1 day';
+      // Ephemeral tunnel — create fresh, will be deleted on shutdown
+      const createOut = execSync(`"${devtunnelCmd}" create --expiration 1d --json`, { encoding: 'utf-8' });
+      const tunnelData = JSON.parse(createOut);
+      tunnelId = tunnelData.tunnel.tunnelId;
+      console.log(`[termbeam] Created ephemeral tunnel ${tunnelId}`);
+    }
+
+    // Idempotent port and access setup
+    try {
+      execSync(`"${devtunnelCmd}" port create ${tunnelId} -p ${port} --protocol http`, { stdio: 'pipe' });
+    } catch {}
+    try {
+      execSync(`"${devtunnelCmd}" access create ${tunnelId} -p ${port} --anonymous`, { stdio: 'pipe' });
+    } catch {}
 
     const hostProc = spawn(devtunnelCmd, ['host', tunnelId], {
       stdio: ['pipe', 'pipe', 'pipe'],
-      detached: true,
     });
     tunnelProc = hostProc;
 
@@ -88,7 +162,7 @@ async function startTunnel(port) {
         const match = output.match(/(https:\/\/[^\s]+devtunnels\.ms[^\s]*)/);
         if (match) {
           clearTimeout(timeout);
-          resolve(match[1]);
+          resolve({ url: match[1], mode: tunnelMode, expiry: tunnelExpiry });
         }
       });
       hostProc.stderr.on('data', (data) => {
@@ -106,17 +180,35 @@ async function startTunnel(port) {
 }
 
 function cleanupTunnel() {
-  if (tunnelId) {
+  const id = tunnelId;
+  if (tunnelProc) {
     try {
-      if (tunnelProc) tunnelProc.kill();
-      execSync(`"${devtunnelCmd}" delete ${tunnelId} -f`, { stdio: 'pipe' });
-      console.log('[termbeam] Tunnel cleaned up');
+      // On Windows, kill the process tree to ensure all children die
+      if (process.platform === 'win32' && tunnelProc.pid) {
+        try {
+          execSync(`taskkill /pid ${tunnelProc.pid} /T /F`, { stdio: 'pipe', timeout: 5000 });
+        } catch { /* best effort */ }
+      } else {
+        tunnelProc.kill('SIGKILL');
+      }
     } catch {
       /* best effort */
     }
-    tunnelId = null;
     tunnelProc = null;
   }
+  if (id) {
+    tunnelId = null;
+    if (isPersisted) {
+      console.log('[termbeam] Tunnel host stopped (tunnel preserved for reuse)');
+    } else {
+      try {
+        execSync(`"${devtunnelCmd}" delete ${id} -f`, { stdio: 'pipe', timeout: 10000 });
+        console.log('[termbeam] Tunnel cleaned up');
+      } catch {
+        /* best effort — tunnel will expire on its own */
+      }
+    }
+  }
 }
 
 module.exports = { startTunnel, cleanupTunnel };