termbeam 1.2.9 → 1.3.0

package/README.md

@@ -106,6 +106,11 @@ termbeam [shell] [args...]        # start with a specific shell (default: auto-d
 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 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
 ```
 
 | Flag                  | Description                                          | Default        |
@@ -121,6 +126,16 @@ termbeam --lan                    # shortcut for --host 0.0.0.0
 | `--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`         |
+| `-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/).
 
@@ -128,12 +143,18 @@ Environment variables: `PORT`, `TERMBEAM_PASSWORD`, `TERMBEAM_CWD`, `TERMBEAM_LO
 
 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.
 
-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. The QR code on startup embeds a share token for password-free login — the token is reusable within its 5-minute validity window, which handles tunnel proxy retries and link preview services. 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.
+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.
+
+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/).
 
 ## Contributing
 
 Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
 ## License
 
 [MIT](LICENSE)

package/bin/termbeam.js

@@ -1,2 +1,27 @@
 #!/usr/bin/env node
-require('../src/server.js');
+
+// Dispatch subcommands before loading the server
+const subcommand = (process.argv[2] || '').toLowerCase();
+if (subcommand === 'service') {
+  const { run } = require('../src/service');
+  run(process.argv.slice(3)).catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
+} else {
+  const { createTermBeamServer } = require('../src/server.js');
+  const instance = createTermBeamServer();
+
+  process.on('SIGINT', () => {
+    console.log('\n[termbeam] Shutting down...');
+    instance.shutdown();
+    setTimeout(() => process.exit(0), 500).unref();
+  });
+  process.on('SIGTERM', () => {
+    console.log('\n[termbeam] Shutting down...');
+    instance.shutdown();
+    setTimeout(() => process.exit(0), 500).unref();
+  });
+
+  instance.start();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {
@@ -10,7 +10,7 @@
     "start": "node bin/termbeam.js",
     "dev": "node bin/termbeam.js --generate-password",
     "test": "node -e \"require('child_process').execFileSync(process.execPath,['--test',...require('fs').readdirSync('test').filter(f=>f.endsWith('.test.js')&&!f.startsWith('e2e-')&&f!=='devtunnel-install.test.js').map(f=>'test/'+f)],{stdio:'inherit'})\"",
-    "test:coverage": "c8 --exclude=src/tunnel.js --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node -e \"require('child_process').execFileSync(process.execPath,['--test','--test-reporter=spec','--test-reporter-destination=stdout',...require('fs').readdirSync('test').filter(f=>f.endsWith('.test.js')&&!f.startsWith('e2e-')&&f!=='devtunnel-install.test.js').map(f=>'test/'+f)],{stdio:'inherit'})\"",
+    "test:coverage": "c8 --exclude=src/tunnel.js --exclude=src/devtunnel-install.js --exclude=test --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node -e \"require('child_process').execFileSync(process.execPath,['--test','--test-reporter=spec','--test-reporter-destination=stdout',...require('fs').readdirSync('test').filter(f=>f.endsWith('.test.js')&&!f.startsWith('e2e-')&&f!=='devtunnel-install.test.js').map(f=>'test/'+f)],{stdio:'inherit'})\"",
     "prepare": "husky",
     "format": "prettier --write .",
     "lint": "node --check src/*.js bin/*.js",

package/public/terminal.html

@@ -2050,7 +2050,17 @@
       // ===== Zoom =====
       const MIN_FONT = 2,
         MAX_FONT = 28;
-      let fontSize = parseInt(localStorage.getItem('termbeam-fontsize') || '8', 10);
+      function defaultFontSize() {
+        const w = window.innerWidth;
+        if (w <= 480) return 12;
+        if (w <= 768) return 13;
+        if (w <= 1280) return 14;
+        return 15;
+      }
+      let fontSize = parseInt(
+        localStorage.getItem('termbeam-fontsize') || String(defaultFontSize()),
+        10,
+      );
 
       function applyZoom(size) {
         fontSize = Math.max(MIN_FONT, Math.min(MAX_FONT, size));

package/src/auth.js

@@ -5,41 +5,70 @@ const LOGIN_HTML = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
-  <meta name="theme-color" content="#1a1a2e" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+  <meta name="apple-mobile-web-app-capable" content="yes" />
+  <meta name="mobile-web-app-capable" content="yes" />
+  <meta name="theme-color" content="#1e1e1e" />
   <title>TermBeam — Login</title>
   <style>
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    html, body { height: 100%; background: #1a1a2e; color: #e0e0e0;
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
-      display: flex; align-items: center; justify-content: center; }
-    .card { background: #16213e; border: 1px solid #0f3460; border-radius: 16px;
-      padding: 32px 24px; width: 320px; text-align: center; }
-    h1 { font-size: 20px; margin-bottom: 8px; }
-    h1 span { color: #533483; }
-    p { font-size: 13px; color: #888; margin-bottom: 24px; }
-    input { width: 100%; padding: 12px; background: #1a1a2e; border: 1px solid #0f3460;
-      border-radius: 8px; color: #e0e0e0; font-size: 16px; outline: none;
-      text-align: center; letter-spacing: 2px; }
-    input:focus { border-color: #533483; }
-    button { width: 100%; padding: 12px; margin-top: 16px; background: #533483;
-      color: white; border: none; border-radius: 8px; font-size: 16px;
-      font-weight: 600; cursor: pointer; }
-    button:active { background: #6a42a8; }
-    .error { color: #e74c3c; font-size: 13px; margin-top: 12px; display: none; }
+    :root { --bg:#1e1e1e; --surface:#252526; --border:#3c3c3c; --border-subtle:#474747;
+      --text:#d4d4d4; --text-secondary:#858585; --text-dim:#6e6e6e;
+      --accent:#0078d4; --accent-hover:#1a8ae8; --accent-active:#005a9e;
+      --danger:#f14c4c; --shadow:rgba(0,0,0,0.15); }
+    [data-theme='light'] { --bg:#ffffff; --surface:#f3f3f3; --border:#e0e0e0;
+      --border-subtle:#d0d0d0; --text:#1e1e1e; --text-secondary:#616161;
+      --text-dim:#767676; --accent:#0078d4; --accent-hover:#106ebe;
+      --accent-active:#005a9e; --danger:#e51400; --shadow:rgba(0,0,0,0.06); }
+    * { margin:0; padding:0; box-sizing:border-box; }
+    html, body { height:100%; background:var(--bg); color:var(--text);
+      font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;
+      display:flex; flex-direction:column; align-items:center; justify-content:center;
+      transition:background 0.3s,color 0.3s;
+      padding:env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left); }
+    .theme-toggle { position:fixed; top:16px; right:16px; background:none;
+      border:1px solid var(--border); color:var(--text-dim); width:32px; height:32px;
+      border-radius:8px; cursor:pointer; display:flex; align-items:center;
+      justify-content:center; font-size:16px; transition:color 0.15s,border-color 0.15s,background 0.15s;
+      -webkit-tap-highlight-color:transparent; z-index:10; }
+    .theme-toggle:hover { color:var(--text); border-color:var(--border-subtle); background:var(--border); }
+    .card { background:var(--surface); border:1px solid var(--border); border-radius:12px;
+      padding:32px 24px; width:320px; max-width:calc(100vw - 32px); text-align:center;
+      box-shadow:0 2px 8px var(--shadow); transition:background 0.3s,border-color 0.3s,box-shadow 0.3s; }
+    h1 { font-size:22px; font-weight:700; margin-bottom:4px; }
+    h1 span { color:var(--accent); }
+    .subtitle { font-size:13px; color:var(--text-secondary); margin-bottom:24px; }
+    input { width:100%; padding:12px; background:var(--bg); border:1px solid var(--border);
+      border-radius:8px; color:var(--text); font-size:16px; outline:none;
+      text-align:center; letter-spacing:2px; transition:border-color 0.15s,background 0.3s,color 0.3s; }
+    input:focus { border-color:var(--accent); }
+    .btn { width:100%; padding:12px; margin-top:16px; background:var(--accent);
+      color:#fff; border:none; border-radius:8px; font-size:16px;
+      font-weight:600; cursor:pointer; transition:background 0.15s; }
+    .btn:hover { background:var(--accent-hover); }
+    .btn:active { background:var(--accent-active); }
+    .error { color:var(--danger); font-size:13px; margin-top:12px; display:none; transition:color 0.3s; }
+    .tagline { margin-top:24px; font-size:12px; color:var(--text-dim); transition:color 0.3s; }
   </style>
 </head>
 <body>
+  <button class="theme-toggle" id="themeBtn" aria-label="Toggle theme">🌙</button>
   <div class="card">
     <h1>📡 Term<span>Beam</span></h1>
-    <p>Enter the access password</p>
+    <p class="subtitle">Enter the access password</p>
     <form id="form">
       <input type="password" id="pw" placeholder="Password" autocomplete="off" autofocus />
-      <button type="submit">Unlock</button>
+      <button type="submit" class="btn">Unlock</button>
     </form>
     <div class="error" id="err">Incorrect password</div>
   </div>
+  <p class="tagline">Beam your terminal to any device</p>
   <script>
+    const t=document.getElementById('themeBtn'), h=document.documentElement;
+    function applyTheme(light){h.setAttribute('data-theme',light?'light':'');t.textContent=light?'☀️':'🌙';
+      document.querySelector('meta[name=theme-color]').content=light?'#ffffff':'#1e1e1e';}
+    applyTheme(localStorage.getItem('theme')==='light');
+    t.addEventListener('click',()=>{const light=h.getAttribute('data-theme')!=='light';
+      localStorage.setItem('theme',light?'light':'dark');applyTheme(light);});
     document.getElementById('form').addEventListener('submit', async (e) => {
       e.preventDefault();
       const pw = document.getElementById('pw').value;

package/src/cli.js

@@ -10,6 +10,14 @@ termbeam — Beam your terminal to any device
 
 Usage:
   termbeam [options] [shell] [args...]
+  termbeam service <action>            Manage as a background service (PM2)
+
+Actions (service):
+  install      Interactive setup & start as PM2 service
+  uninstall    Stop & remove from PM2
+  status       Show service status
+  logs         Tail service logs
+  restart      Restart the service
 
 Options:
   --password <pw>       Set access password (or TERMBEAM_PASSWORD env var)
@@ -39,6 +47,7 @@ Examples:
   termbeam --password secret        Start with specific password
   termbeam --persisted-tunnel       Stable tunnel URL across restarts
   termbeam /bin/bash                Use bash instead of default shell
+  termbeam service install          Set up as background service (PM2)
 
 Environment:
   PORT                  Server port (default: 3456)
@@ -329,4 +338,4 @@ function parseArgs() {
   };
 }
 
-module.exports = { parseArgs, printHelp, isKnownShell };
+module.exports = { parseArgs, printHelp, isKnownShell, getWindowsAncestors };

package/src/routes.js

@@ -9,6 +9,30 @@ const log = require('./logger');
 const PUBLIC_DIR = path.join(__dirname, '..', 'public');
 const uploadedFiles = new Map(); // id -> filepath
 
+const IMAGE_SIGNATURES = [
+  { type: 'image/png', bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+  { type: 'image/jpeg', bytes: [0xff, 0xd8, 0xff] },
+  { type: 'image/gif', bytes: [0x47, 0x49, 0x46, 0x38] },
+  { type: 'image/webp', offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] },
+  { type: 'image/bmp', bytes: [0x42, 0x4d] },
+];
+
+function validateMagicBytes(buffer, contentType) {
+  const sig = IMAGE_SIGNATURES.find((s) => s.type === contentType);
+  if (!sig) return true; // unknown type, skip validation
+  const offset = sig.offset || 0;
+  if (buffer.length < offset + sig.bytes.length) return false;
+  const match = sig.bytes.every((b, i) => buffer[offset + i] === b);
+  if (!match) return false;
+  // WebP requires RIFF header at offset 0
+  if (contentType === 'image/webp') {
+    const riff = [0x52, 0x49, 0x46, 0x46];
+    if (buffer.length < 4) return false;
+    return riff.every((b, i) => buffer[i] === b);
+  }
+  return true;
+}
+
 function setupRoutes(app, { auth, sessions, config, state }) {
   // Serve static files (manifest.json, sw.js, icons, etc.)
   app.use(express.static(PUBLIC_DIR, { index: false }));
@@ -204,6 +228,10 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       if (!buffer.length) {
         return res.status(400).json({ error: 'No image data' });
       }
+      if (!validateMagicBytes(buffer, contentType)) {
+        log.warn(`Upload rejected: content-type "${contentType}" does not match file signature`);
+        return res.status(400).json({ error: 'File content does not match declared image type' });
+      }
       const ext =
         {
           'image/png': '.png',

package/src/server.js

@@ -231,11 +231,10 @@ function createTermBeamServer(overrides = {}) {
   return { app, server, wss, sessions, config, auth, start, shutdown };
 }
 
-module.exports = { createTermBeamServer };
+module.exports = { createTermBeamServer, getLocalIP };
 
-// Auto-start when run directly (CLI entry point)
-const _entryBase = path.basename(process.argv[1] || '');
-if (require.main === module || _entryBase === 'termbeam' || _entryBase === 'termbeam.js') {
+// Auto-start when run directly (e.g. `node src/server.js`)
+if (require.main === module) {
   const instance = createTermBeamServer();
 
   process.on('SIGINT', () => {

package/src/service.js

@@ -0,0 +1,731 @@
+const { execFileSync, execFile } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const readline = require('readline');
+
+const TERMBEAM_DIR = path.join(os.homedir(), '.termbeam');
+const ECOSYSTEM_FILE = path.join(TERMBEAM_DIR, 'ecosystem.config.js');
+const DEFAULT_SERVICE_NAME = 'termbeam';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function color(code, text) {
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+const green = (t) => color('32', t);
+const yellow = (t) => color('33', t);
+const red = (t) => color('31', t);
+const cyan = (t) => color('36', t);
+const bold = (t) => color('1', t);
+const dim = (t) => color('2', t);
+
+/**
+ * Prompt the user with a question. Returns the trimmed answer.
+ * If `defaultValue` is provided, it's shown in brackets and used when the user presses Enter.
+ */
+function ask(rl, question, defaultValue) {
+  const suffix = defaultValue != null ? ` ${dim(`[${defaultValue}]`)} ` : ' ';
+  return new Promise((resolve) => {
+    rl.question(`${question}${suffix}`, (answer) => {
+      const trimmed = answer.trim();
+      resolve(trimmed || (defaultValue != null ? String(defaultValue) : ''));
+    });
+  });
+}
+
+/**
+ * Prompt the user with a list of choices using arrow keys.
+ * Each choice can be a string or { label, hint } object.
+ * Up/Down to move, Enter to select. Returns the chosen value.
+ */
+function choose(rl, question, choices, defaultIndex = 0) {
+  // Normalize choices to { label, hint } objects
+  const items = choices.map((c) => (typeof c === 'string' ? { label: c, hint: '' } : c));
+
+  return new Promise((resolve) => {
+    let selected = defaultIndex;
+
+    function lineCount() {
+      return items.reduce((n, item) => n + 1 + (item.hint ? 1 : 0), 0);
+    }
+
+    function render(clear) {
+      if (clear) {
+        process.stdout.write(`\x1b[${lineCount()}A\r\x1b[J`);
+      }
+      items.forEach((item, i) => {
+        const marker = i === selected ? cyan('→') : ' ';
+        const label = i === selected ? bold(item.label) : item.label;
+        process.stdout.write(`  ${marker} ${label}\n`);
+        if (item.hint) {
+          const hintText = item.danger
+            ? red(item.hint)
+            : item.warn
+              ? yellow(item.hint)
+              : dim(item.hint);
+          process.stdout.write(`      ${hintText}\n`);
+        }
+      });
+      process.stdout.write(dim('  ↑/↓ to move, Enter to select'));
+    }
+
+    rl.pause();
+    console.log(`\n${question}`);
+    render(false);
+
+    const wasRaw = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+
+    function onKey(buf) {
+      const key = buf.toString();
+
+      if (key === '\x1b[A' || key === 'k') {
+        selected = (selected - 1 + items.length) % items.length;
+        render(true);
+      } else if (key === '\x1b[B' || key === 'j') {
+        selected = (selected + 1) % items.length;
+        render(true);
+      } else if (key === '\r' || key === '\n') {
+        cleanup();
+        process.stdout.write('\r\x1b[K\n');
+        console.log(dim(`  Selected: ${items[selected].label}`));
+        resolve({ index: selected, value: items[selected].label });
+      } else if (key === '\x03') {
+        cleanup();
+        process.exit(0);
+      }
+    }
+
+    function cleanup() {
+      process.stdin.removeListener('data', onKey);
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(wasRaw || false);
+      }
+      process.stdin.pause();
+      rl.resume();
+    }
+
+    process.stdin.on('data', onKey);
+  });
+}
+
+/**
+ * Ask a yes/no question. Returns boolean.
+ */
+function confirm(rl, question, defaultYes = true) {
+  const hint = defaultYes ? 'Y/n' : 'y/N';
+  return new Promise((resolve) => {
+    rl.question(`${question} ${dim(`[${hint}]`)} `, (answer) => {
+      const a = answer.trim().toLowerCase();
+      if (a === '') resolve(defaultYes);
+      else resolve(a === 'y' || a === 'yes');
+    });
+  });
+}
+
+// ── PM2 Detection ────────────────────────────────────────────────────────────
+
+function findPm2() {
+  try {
+    const cmd = os.platform() === 'win32' ? 'where' : 'which';
+    const result = execFileSync(cmd, ['pm2'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: 5000,
+    });
+    return result.trim().split('\n')[0].trim();
+  } catch {
+    return null;
+  }
+}
+
+function installPm2Global() {
+  console.log(yellow('\nInstalling PM2 globally...'));
+  try {
+    execFileSync('npm', ['install', '-g', 'pm2'], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+    console.log(green('✓ PM2 installed successfully.\n'));
+    return true;
+  } catch (err) {
+    console.error(red(`✗ Failed to install PM2: ${err.message}`));
+    console.error(dim('  Try running: sudo npm install -g pm2'));
+    return false;
+  }
+}
+
+// ── Ecosystem Config ─────────────────────────────────────────────────────────
+
+function buildArgs(config) {
+  const args = [];
+  if (config.password === false) {
+    args.push('--no-password');
+  } else if (config.password) {
+    args.push('--password', config.password);
+  }
+  if (config.port && config.port !== 3456) {
+    args.push('--port', String(config.port));
+  }
+  if (config.host && config.host !== '127.0.0.1') {
+    args.push('--host', config.host);
+  }
+  if (config.lan) {
+    args.push('--lan');
+  }
+  if (config.noTunnel) {
+    args.push('--no-tunnel');
+  }
+  if (config.persistedTunnel) {
+    args.push('--persisted-tunnel');
+  }
+  if (config.publicTunnel) {
+    args.push('--public');
+  }
+  if (config.logLevel && config.logLevel !== 'info') {
+    args.push('--log-level', config.logLevel);
+  }
+  if (config.shell) {
+    args.push(config.shell);
+  }
+  return args;
+}
+
+function generateEcosystem(config) {
+  const entry = require.resolve('../bin/termbeam.js');
+  const args = buildArgs(config);
+  const env = {};
+  if (config.cwd) env.TERMBEAM_CWD = config.cwd;
+
+  const ecosystem = {
+    apps: [
+      {
+        name: config.name || DEFAULT_SERVICE_NAME,
+        script: entry,
+        args: args,
+        cwd: config.cwd || os.homedir(),
+        env,
+        autorestart: true,
+        max_restarts: 10,
+        restart_delay: 1000,
+      },
+    ],
+  };
+
+  return `module.exports = ${JSON.stringify(ecosystem, null, 2)};\n`;
+}
+
+function writeEcosystem(content) {
+  fs.mkdirSync(TERMBEAM_DIR, { recursive: true });
+  fs.writeFileSync(ECOSYSTEM_FILE, content, 'utf8');
+}
+
+// ── PM2 Commands ─────────────────────────────────────────────────────────────
+
+function pm2Exec(args, opts = {}) {
+  try {
+    return execFileSync('pm2', args, {
+      encoding: 'utf8',
+      stdio: opts.inherit ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+      timeout: 30000,
+      ...opts,
+    });
+  } catch (err) {
+    if (opts.silent) return null;
+    console.error(red(`✗ PM2 command failed: pm2 ${args.join(' ')}`));
+    if (err.stderr) console.error(dim(err.stderr.trim()));
+    return null;
+  }
+}
+
+// ── Actions ──────────────────────────────────────────────────────────────────
+
+async function actionInstall() {
+  console.log(dim('\nChecking PM2...\n'));
+
+  // Step 1: Check PM2
+  let pm2Path = findPm2();
+  if (!pm2Path) {
+    console.log(yellow('⚠ PM2 is not installed.'));
+    console.log(dim('  PM2 is a process manager for Node.js that keeps TermBeam running'));
+    console.log(dim('  in the background and can auto-restart it on boot.\n'));
+
+    const rl = createRL();
+    const shouldInstall = await confirm(rl, 'Install PM2 globally now?', true);
+    rl.close();
+
+    if (!shouldInstall) {
+      console.log(dim('\nYou can install PM2 manually: npm install -g pm2'));
+      console.log(dim('Then run: termbeam service install\n'));
+      process.exit(1);
+    }
+    if (!installPm2Global()) process.exit(1);
+    pm2Path = findPm2();
+    if (!pm2Path) {
+      console.error(red('✗ PM2 still not found after installation.'));
+      process.exit(1);
+    }
+  } else {
+    console.log(green(`✓ PM2 found: ${pm2Path}`));
+  }
+
+  // Enter alternate screen buffer for a clean wizard (like vim/htop)
+  process.stdout.write('\x1b[?1049h');
+  // Ensure we exit alternate screen on any exit
+  const exitAltScreen = () => process.stdout.write('\x1b[?1049l');
+  process.on('exit', exitAltScreen);
+
+  // Step 2: Interactive config
+  const rl = createRL();
+  const config = {};
+
+  const steps = [
+    'Service name',
+    'Password',
+    'Port',
+    'Access',
+    'Directory',
+    'Log level',
+    'Boot',
+    'Confirm',
+  ];
+
+  const decisions = [];
+
+  function showProgress(stepIndex) {
+    // Clear alternate screen and move to top
+    process.stdout.write('\x1b[2J\x1b[H');
+
+    console.log(bold('🚀 TermBeam Service Setup'));
+    console.log('');
+    const total = steps.length;
+    const filled = stepIndex + 1;
+    const bar = steps
+      .map((s, i) => {
+        if (i < stepIndex) return green('●');
+        if (i === stepIndex) return cyan('●');
+        return dim('○');
+      })
+      .join(dim(' ─ '));
+    console.log(`${dim(`Step ${filled}/${total}`)}  ${bar}  ${cyan(steps[stepIndex])}`);
+
+    // Show decisions so far
+    if (decisions.length > 0) {
+      console.log('');
+      for (const { label, value } of decisions) {
+        console.log(`  ${dim(label + ':')} ${value}`);
+      }
+    }
+  }
+
+  // Service name
+  showProgress(0);
+  config.name = await ask(rl, 'Service name:', DEFAULT_SERVICE_NAME);
+  decisions.push({ label: 'Service name', value: config.name });
+
+  // Password
+  showProgress(1);
+  const pwChoice = await choose(rl, 'Password authentication:', [
+    {
+      label: 'Auto-generate a secure password',
+      hint: 'A random password will be created and displayed for you',
+    },
+    { label: 'Enter a custom password', hint: 'You choose the password for accessing TermBeam' },
+    {
+      label: 'No password',
+      hint: '⚠ Not recommended — anyone on the network can access your terminal',
+      warn: true,
+    },
+  ]);
+  if (pwChoice.index === 0) {
+    config.password = crypto.randomBytes(16).toString('base64url');
+    console.log(dim(`  Generated password: ${config.password}`));
+  } else if (pwChoice.index === 1) {
+    config.password = await ask(rl, 'Enter password:');
+    while (!config.password) {
+      console.log(red('  Password cannot be empty.'));
+      config.password = await ask(rl, 'Enter password:');
+    }
+  } else {
+    config.password = false;
+  }
+  decisions.push({
+    label: 'Password',
+    value: config.password === false ? yellow('disabled') : '••••••••',
+  });
+
+  // Port
+  showProgress(2);
+  const portStr = await ask(rl, 'Port:', '3456');
+  config.port = parseInt(portStr, 10) || 3456;
+  decisions.push({ label: 'Port', value: String(config.port) });
+
+  // Access mode (combines host binding + tunnel into one clear question)
+  showProgress(3);
+  const accessChoice = await choose(rl, 'How will you connect to TermBeam?', [
+    {
+      label: 'From anywhere (DevTunnel)',
+      hint: 'Creates a secure tunnel URL — access from phone, other networks, anywhere',
+    },
+    {
+      label: 'Local network (LAN)',
+      hint: 'Accessible from devices on the same Wi-Fi/network (e.g. phone on same Wi-Fi)',
+    },
+    {
+      label: 'This machine only',
+      hint: 'Localhost only — most secure, no external access',
+    },
+  ]);
+
+  if (accessChoice.index === 0) {
+    // DevTunnel mode: localhost binding, tunnel enabled, persisted by default for services
+    config.host = '127.0.0.1';
+    config.noTunnel = false;
+    config.persistedTunnel = true;
+    // Re-render step to clear the previous menu before showing sub-question
+    showProgress(3);
+    const publicChoice = await choose(rl, 'Tunnel access:', [
+      {
+        label: 'Private (requires Microsoft login)',
+        hint: 'Only you can access the tunnel — secured via your Microsoft account',
+      },
+      {
+        label: 'Public (anyone with the link)',
+        hint: '🚨 Anyone with the URL can reach your terminal — password is the only protection',
+        danger: true,
+      },
+    ]);
+    config.publicTunnel = publicChoice.index === 1;
+    if (config.publicTunnel && config.password === false) {
+      console.log(yellow('  ⚠ Public tunnels require password authentication.'));
+      config.password = crypto.randomBytes(16).toString('base64url');
+      console.log(dim(`  Auto-generated password: ${config.password}`));
+    }
+  } else if (accessChoice.index === 1) {
+    // LAN mode: bind to all interfaces, no tunnel
+    config.lan = true;
+    config.noTunnel = true;
+  } else {
+    // Localhost only: no tunnel
+    config.host = '127.0.0.1';
+    config.noTunnel = true;
+  }
+  const accessLabel = config.noTunnel
+    ? config.lan
+      ? 'LAN (0.0.0.0)'
+      : 'Localhost only'
+    : config.publicTunnel
+      ? 'DevTunnel (public)'
+      : 'DevTunnel (private)';
+  decisions.push({ label: 'Access', value: accessLabel });
+
+  // Working directory
+  showProgress(4);
+  config.cwd = await ask(rl, 'Working directory:', process.cwd());
+  decisions.push({ label: 'Directory', value: config.cwd });
+
+  // Shell — use current shell automatically
+  config.shell = process.env.SHELL || (os.platform() === 'win32' ? process.env.COMSPEC : '/bin/sh');
+  decisions.push({ label: 'Shell', value: config.shell });
+
+  // Log level
+  showProgress(5);
+  const logChoice = await choose(
+    rl,
+    'Log level:',
+    [
+      { label: 'info', hint: 'Standard logging — startup, connections, errors (recommended)' },
+      { label: 'debug', hint: 'Verbose output — useful for troubleshooting issues' },
+      { label: 'warn', hint: 'Only warnings and errors' },
+      { label: 'error', hint: 'Only critical errors — minimal output' },
+    ],
+    0,
+  );
+  config.logLevel = logChoice.value;
+  decisions.push({ label: 'Log level', value: config.logLevel });
+
+  // Boot
+  showProgress(6);
+  config.startup = await confirm(rl, 'Auto-start TermBeam on system boot?', true);
+  decisions.push({ label: 'Boot', value: config.startup ? 'yes' : 'no' });
+
+  // Confirm
+  showProgress(7);
+  console.log(bold('\n── Configuration Summary ──────────────────'));
+  console.log(`  Service name:  ${cyan(config.name)}`);
+  console.log(
+    `  Password:      ${config.password === false ? yellow('disabled') : cyan(config.password)}`,
+  );
+  console.log(`  Port:          ${cyan(String(config.port))}`);
+  console.log(
+    `  Host:          ${cyan(config.lan ? '0.0.0.0 (LAN)' : config.host || '127.0.0.1')}`,
+  );
+  console.log(`  Tunnel:        ${config.noTunnel ? yellow('disabled') : cyan('enabled')}`);
+  if (!config.noTunnel) {
+    console.log(`  Persisted:     ${config.persistedTunnel ? cyan('yes') : dim('no')}`);
+    console.log(`  Public:        ${config.publicTunnel ? yellow('yes') : dim('no')}`);
+  }
+  console.log(`  Directory:     ${cyan(config.cwd)}`);
+  console.log(`  Shell:         ${cyan(config.shell || 'default')}`);
+  console.log(`  Log level:     ${cyan(config.logLevel)}`);
+  console.log(`  Boot:          ${config.startup ? cyan('yes') : dim('no')}`);
+  console.log(dim('─'.repeat(44)));
+
+  const proceed = await confirm(rl, '\nProceed with installation?', true);
+  rl.close();
+
+  // Exit alternate screen — return to normal terminal
+  exitAltScreen();
+  process.removeListener('exit', exitAltScreen);
+
+  if (!proceed) {
+    console.log(dim('Cancelled.'));
+    process.exit(0);
+  }
+
+  // Step 3: Create working directory if needed, write ecosystem & start
+  if (!fs.existsSync(config.cwd)) {
+    fs.mkdirSync(config.cwd, { recursive: true });
+    console.log(green(`✓ Created directory ${config.cwd}`));
+  }
+  const ecosystemContent = generateEcosystem(config);
+  writeEcosystem(ecosystemContent);
+  console.log(green(`\n✓ Config written to ${ECOSYSTEM_FILE}`));
+
+  // Stop existing instance if running
+  pm2Exec(['delete', config.name], { silent: true });
+
+  // Truncate old log files for a clean start
+  const outLog = path.join(os.homedir(), '.pm2', 'logs', `${config.name}-out.log`);
+  const errLog = path.join(os.homedir(), '.pm2', 'logs', `${config.name}-error.log`);
+  try {
+    fs.writeFileSync(outLog, '', 'utf8');
+  } catch {}
+  try {
+    fs.writeFileSync(errLog, '', 'utf8');
+  } catch {}
+
+  // Start
+  const started = pm2Exec(['start', ECOSYSTEM_FILE], { inherit: true });
+  if (started === null && !fs.existsSync(ECOSYSTEM_FILE)) {
+    console.error(red('✗ Failed to start TermBeam service.'));
+    process.exit(1);
+  }
+
+  pm2Exec(['save'], { inherit: true });
+  console.log(green('\n✓ TermBeam is now running as a PM2 service!'));
+
+  // Run pm2 startup if chosen during wizard
+  if (config.startup) {
+    console.log('');
+    // pm2 startup outputs a sudo command to copy/paste — capture it and run it
+    const startupOutput = pm2Exec(['startup'], { silent: true }) || '';
+    const sudoMatch = startupOutput.match(/^(sudo .+)$/m);
+    if (sudoMatch) {
+      console.log(dim('Setting up boot persistence (may ask for your password)...\n'));
+      const { spawn } = require('child_process');
+      const child = spawn('sh', ['-c', sudoMatch[1]], { stdio: 'inherit' });
+      await new Promise((resolve) => child.on('close', resolve));
+      pm2Exec(['save'], { inherit: true });
+      console.log(green('✓ TermBeam will start automatically on boot.'));
+    } else {
+      // Fallback: just show what pm2 said
+      console.log(startupOutput);
+    }
+  }
+
+  // Wait for server to start and show connection info
+  console.log(dim('\nWaiting for TermBeam to start...'));
+  const maxWait = 15;
+  let logContent = '';
+  for (let i = 0; i < maxWait; i++) {
+    await new Promise((r) => setTimeout(r, 1000));
+    try {
+      logContent = fs.readFileSync(outLog, 'utf8');
+    } catch {
+      continue;
+    }
+    if (logContent.includes('Scan the QR code') || logContent.includes('Local:')) break;
+  }
+  if (logContent) {
+    // Extract from last "Shell:" to last "Scan the QR code" line
+    const lines = logContent.split('\n');
+    const startIdx = lines.findLastIndex((l) => l.includes('Shell:'));
+    const endIdx = lines.findLastIndex((l) => l.includes('Scan the QR code'));
+    if (startIdx >= 0 && endIdx >= startIdx) {
+      console.log('');
+      for (let i = startIdx; i <= endIdx; i++) {
+        console.log(lines[i]);
+      }
+      console.log('');
+    }
+  }
+
+  console.log(dim('\nUseful commands:'));
+  console.log(`  ${cyan('termbeam service status')}   — Check service status`);
+  console.log(`  ${cyan('termbeam service logs')}     — View logs`);
+  console.log(`  ${cyan('termbeam service restart')}  — Restart service`);
+  console.log(`  ${cyan('termbeam service uninstall')} — Remove service\n`);
+}
+
+async function actionUninstall() {
+  const pm2Path = findPm2();
+  if (!pm2Path) {
+    console.error(red('✗ PM2 is not installed.'));
+    process.exit(1);
+  }
+
+  // Find running termbeam services
+  const list = pm2Exec(['jlist'], { silent: true });
+  let services = [];
+  if (list) {
+    try {
+      services = JSON.parse(list).filter(
+        (p) => p.name === DEFAULT_SERVICE_NAME || p.name.startsWith('termbeam'),
+      );
+    } catch {
+      // ignore parse errors
+    }
+  }
+
+  const name = services.length > 0 ? services[0].name : DEFAULT_SERVICE_NAME;
+
+  const rl = createRL();
+  const sure = await confirm(rl, `Remove TermBeam service "${name}" from PM2?`, true);
+  rl.close();
+
+  if (!sure) {
+    console.log(dim('Cancelled.'));
+    process.exit(0);
+  }
+
+  pm2Exec(['stop', name], { inherit: true });
+  pm2Exec(['delete', name], { inherit: true });
+  pm2Exec(['save'], { inherit: true });
+
+  // Clean up ecosystem file
+  if (fs.existsSync(ECOSYSTEM_FILE)) {
+    fs.unlinkSync(ECOSYSTEM_FILE);
+    console.log(dim(`Removed ${ECOSYSTEM_FILE}`));
+  }
+
+  console.log(green(`\n✓ TermBeam service "${name}" removed.\n`));
+}
+
+function actionStatus() {
+  const pm2Path = findPm2();
+  if (!pm2Path) {
+    console.error(red('✗ PM2 is not installed. Run: npm install -g pm2'));
+    process.exit(1);
+  }
+  pm2Exec(['describe', DEFAULT_SERVICE_NAME], { inherit: true });
+}
+
+function actionLogs() {
+  const pm2Path = findPm2();
+  if (!pm2Path) {
+    console.error(red('✗ PM2 is not installed. Run: npm install -g pm2'));
+    process.exit(1);
+  }
+  const { spawn } = require('child_process');
+  const child = spawn('pm2', ['logs', DEFAULT_SERVICE_NAME, '--lines', '200'], {
+    stdio: 'inherit',
+  });
+  child.on('error', (err) => {
+    console.error(red(`✗ Failed to stream logs: ${err.message}`));
+  });
+}
+
+function actionRestart() {
+  const pm2Path = findPm2();
+  if (!pm2Path) {
+    console.error(red('✗ PM2 is not installed. Run: npm install -g pm2'));
+    process.exit(1);
+  }
+  pm2Exec(['restart', DEFAULT_SERVICE_NAME], { inherit: true });
+  console.log(green('\n✓ TermBeam service restarted.\n'));
+}
+
+// ── readline factory ─────────────────────────────────────────────────────────
+
+function createRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+// ── Entrypoint ───────────────────────────────────────────────────────────────
+
+function printServiceHelp() {
+  console.log(`
+${bold('termbeam service')} — Manage TermBeam as a background service (PM2)
+
+${bold('Usage:')}
+  termbeam service install     Interactive setup & start
+  termbeam service uninstall   Stop & remove from PM2
+  termbeam service status      Show service status
+  termbeam service logs        Tail service logs
+  termbeam service restart     Restart the service
+
+${dim('PM2 will be installed globally if not already present.')}
+`);
+}
+
+async function run(args) {
+  const action = (args[0] || '').toLowerCase();
+
+  switch (action) {
+    case 'install':
+      await actionInstall();
+      break;
+    case 'uninstall':
+    case 'remove':
+      await actionUninstall();
+      break;
+    case 'status':
+      actionStatus();
+      break;
+    case 'logs':
+    case 'log':
+      actionLogs();
+      break;
+    case 'restart':
+      actionRestart();
+      break;
+    default:
+      printServiceHelp();
+      break;
+  }
+}
+
+module.exports = {
+  run,
+  findPm2,
+  buildArgs,
+  generateEcosystem,
+  writeEcosystem,
+  pm2Exec,
+  actionStatus,
+  actionRestart,
+  actionLogs,
+  printServiceHelp,
+  color,
+  green,
+  yellow,
+  red,
+  cyan,
+  bold,
+  dim,
+  ask,
+  choose,
+  confirm,
+  TERMBEAM_DIR,
+  ECOSYSTEM_FILE,
+  DEFAULT_SERVICE_NAME,
+};