feat: persist DevTunnel ID for stable URLs across restarts (#13)

* feat: persist DevTunnel ID for stable URLs across restarts

Tunnel ID is saved to ~/.termbeam/tunnel.json and reused on next
startup. Tunnel is no longer deleted on shutdown — only the host
process is stopped. Add --new-tunnel flag to force a fresh tunnel.

Closes #10

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* refactor: use --persisted-tunnel flag instead of changing --tunnel behavior

- --tunnel remains ephemeral (no breaking change) — creates fresh, deletes on exit
- --persisted-tunnel opts into persistence — saves ID, reuses across restarts, 30d expiry
- Removes --new-tunnel flag (use --tunnel for a fresh one instead)
- Ephemeral tunnels are deleted on shutdown, persisted ones are preserved

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat: log tunnel mode and expiry in startup banner

Shows 'ephemeral (expires in 1 day)' or 'persisted (expires in 30 days)'
next to the public URL so users know what to expect.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: prevent hang on shutdown with tunnel cleanup

Remove detached:true from tunnel host spawn so the child process
dies with the parent. Remove process.on('exit') handler that called
execSync (which can't run in exit handlers), causing the hang.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: prevent hang on ephemeral tunnel cleanup

Use SIGKILL (Unix) / taskkill /T /F (Windows) to force-kill the host
process tree before running devtunnel delete. Add 10s timeout to the
delete command so it can't hang indefinitely.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: close server and WebSocket on shutdown to prevent hang

Close HTTP server and WebSocket server before exiting so all handles
are released. Add shuttingDown guard to prevent double-shutdown.
Use unref'd timeout as force-exit safety net.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

docs/configuration.md

@@ -6,7 +6,8 @@
 | --------------------- | ------------------------------- | --------- |
 | `--password <pw>`     | Set access password             | None      |
 | `--generate-password` | Auto-generate a secure password | —         |
-| `--tunnel`            | Create a public devtunnel URL   | Off       |
+| `--tunnel`            | Create an ephemeral devtunnel URL | Off       |
+| `--persisted-tunnel`  | Create a reusable devtunnel URL (stable across restarts) | Off |
 | `--port <port>`       | Server port                     | `3456`    |
 | `--host <addr>`       | Bind address                    | `0.0.0.0` |
 | `-h, --help`          | Show help                       | —         |
@@ -67,12 +68,22 @@ termbeam --tunnel --generate-password
 
 ### DevTunnel
 
-The `--tunnel` flag creates a public URL using [Azure DevTunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/):
+The `--tunnel` flag creates an ephemeral public URL using [Azure DevTunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/):
 
 ```bash
 termbeam --tunnel --password mysecret
 ```
 
+For a **stable URL** that persists across restarts, use `--persisted-tunnel`:
+
+```bash
+termbeam --persisted-tunnel --password mysecret
+```
+
+!!! info "Persisted vs Ephemeral Tunnels"
+    - `--tunnel` — Creates a fresh tunnel each time, deleted on shutdown. Good for one-off use.
+    - `--persisted-tunnel` — Saves the tunnel ID to `~/.termbeam/tunnel.json` and reuses it across restarts (30-day expiry). The URL stays the same so you can bookmark it on your phone. To get a fresh URL, just switch back to `--tunnel`.
+
 !!! warning
 Always use a password when using `--tunnel`. The tunnel URL is publicly accessible.
 

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 };

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.');

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 };

test/cli.test.js

@@ -98,6 +98,21 @@ describe('CLI', () => {
     assert.strictEqual(config.port, 9999);
   });
 
+  it('should parse --persisted-tunnel flag', () => {
+    process.argv = ['node', 'termbeam', '--persisted-tunnel'];
+    const { parseArgs } = require('../src/cli');
+    const config = parseArgs();
+    assert.strictEqual(config.persistedTunnel, true);
+    assert.strictEqual(config.useTunnel, true);
+  });
+
+  it('should default persistedTunnel to false', () => {
+    process.argv = ['node', 'termbeam'];
+    const { parseArgs } = require('../src/cli');
+    const config = parseArgs();
+    assert.strictEqual(config.persistedTunnel, false);
+  });
+
   it('should combine multiple flags', () => {
     process.argv = [
       'node',