terminal-expose 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
 # Terminal Expose
 
-Read-only terminal sharing from your own machine.
+Interactive terminal sharing from your own machine.
 
-`terminal-expose` starts a real shell or command on the host where it is run, prints a private viewer URL, and streams the terminal output to anyone who opens that URL.
+`terminal-expose` starts a real shell or command on the host where it is run, prints a private URL, and allows collaborative, interactive access to anyone who opens that URL.
 
 ## Install
 
@@ -38,7 +38,7 @@ Local URL : http://localhost:3000/s/<token>
 LAN URL   : http://192.168.1.10:3000/s/<token>
 ```
 
-Share the full token URL with the viewer. Viewers are read-only.
+Share the full token URL with your collaborators. They will have full read and write access to the terminal.
 
 ## Public Internet Access
 
@@ -61,7 +61,7 @@ You can request a custom localtunnel subdomain:
 terminal-expose --public --subdomain my-terminal-demo bash
 ```
 
-The tunnel URL works outside your Wi-Fi as long as the CLI is still running. If `loca.lt` asks the viewer for a tunnel password, share the printed tunnel password too.
+The tunnel URL works outside your Wi-Fi as long as the CLI is still running. If `loca.lt` asks the user for a tunnel password, share the printed tunnel password too.
 
 For a permanent setup, run it on a public server or forward TCP port `3000` to the machine running the CLI:
 
@@ -83,4 +83,4 @@ TERM_COLS=160 TERM_ROWS=48 terminal-expose bash
 
 ## Security
 
-Anyone with the full URL can watch the session. Do not type passwords, API keys, or private commands in a shared terminal.
+Anyone with the full URL can view and interact with the session. Do not type passwords, API keys, or private commands in a shared terminal.

package/index.js

@@ -1,81 +1,21 @@
 #!/usr/bin/env node
 
-const express = require("express");
 const http = require("http");
-const { Server } = require("socket.io");
-const crypto = require("crypto");
-const https = require("https");
-const os = require("os");
-const pty = require("node-pty");
-const path = require("path");
-const localtunnel = require("localtunnel");
+const { parseArgs } = require("./src/utils/args");
+const { getDefaultShell, getLanUrls } = require("./src/utils/system");
+const { TerminalSession } = require("./src/core/terminal");
+const { setupSocket } = require("./src/core/socket");
+const { startPublicTunnel } = require("./src/core/tunnel");
+const { createApp } = require("./src/server/app");
 
-const app = express();
-const server = http.createServer(app);
+const { PORT, HOST, SESSION_TOKEN, EXTERNAL_URL } = require("./src/config/env");
 
-const PORT = Number(process.env.PORT || 3000);
-const HOST = process.env.HOST || "0.0.0.0";
-const MAX_BUFFER = Number(process.env.MAX_BUFFER || 100000);
-const ECHO_TO_STDOUT = process.env.ECHO_TO_STDOUT !== "0";
-const SESSION_TOKEN =
-  process.env.SESSION_TOKEN || crypto.randomBytes(18).toString("base64url");
+// arguments
 const rawArgs = process.argv.slice(2);
 
-function parseArgs(args) {
-  const options = {
-    publicTunnel: false,
-    tunnelSubdomain: process.env.TUNNEL_SUBDOMAIN || null,
-    tunnelHost: process.env.TUNNEL_HOST || undefined,
-  };
-  const commandArgs = [];
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    if (arg === "--public" || arg === "--tunnel") {
-      options.publicTunnel = true;
-      continue;
-    }
-
-    if (arg === "--subdomain") {
-      options.tunnelSubdomain = args[index + 1] || null;
-      index += 1;
-      continue;
-    }
-
-    if (arg.startsWith("--subdomain=")) {
-      options.tunnelSubdomain = arg.slice("--subdomain=".length) || null;
-      continue;
-    }
-
-    if (arg === "--tunnel-host") {
-      options.tunnelHost = args[index + 1] || undefined;
-      index += 1;
-      continue;
-    }
-
-    if (arg.startsWith("--tunnel-host=")) {
-      options.tunnelHost = arg.slice("--tunnel-host=".length) || undefined;
-      continue;
-    }
-
-    commandArgs.push(arg);
-  }
-
-  if (
-    process.env.PUBLIC_TUNNEL === "1" ||
-    process.env.PUBLIC_TUNNEL === "true"
-  ) {
-    options.publicTunnel = true;
-  }
-
-  return { options, commandArgs };
-}
-
-const { options, commandArgs: command } = parseArgs(rawArgs);
-
 if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
   console.log(`Terminal Expose
+Interactive terminal session sharing over HTTP and WebSocket.
 
 Usage:
   terminal-expose [options] [command] [args...]
@@ -113,385 +53,41 @@ if (rawArgs.includes("--version") || rawArgs.includes("-v")) {
   process.exit(0);
 }
 
-const shellCommand =
-  command.length > 0
-    ? command[0]
-    : process.platform === "win32"
-      ? "powershell.exe"
-      : process.env.SHELL || "bash";
-const shellArgs = command.length > 0 ? command.slice(1) : [];
-
-function getLanUrls() {
-  const urls = [];
-  const interfaces = os.networkInterfaces();
-
-  Object.values(interfaces).forEach((addresses = []) => {
-    addresses
-      .filter((address) => address.family === "IPv4" && !address.internal)
-      .forEach((address) => {
-        urls.push(`http://${address.address}:${PORT}/s/${SESSION_TOKEN}`);
-      });
-  });
-
-  return urls;
-}
-
-function getLocaltunnelPassword() {
-  return new Promise((resolve) => {
-    let settled = false;
-
-    function finish(value) {
-      if (settled) {
-        return;
-      }
-
-      settled = true;
-      resolve(value);
-    }
-
-    const request = https.get("https://loca.lt/mytunnelpassword", (response) => {
-      if (response.statusCode !== 200) {
-        response.resume();
-        finish(null);
-        return;
-      }
-
-      let body = "";
-      response.setEncoding("utf8");
-      response.on("data", (chunk) => {
-        body += chunk;
-      });
-      response.on("end", () => {
-        finish(body.trim() || null);
-      });
-    });
-
-    request.setTimeout(3000, () => {
-      request.destroy();
-      finish(null);
-    });
-
-    request.on("error", () => {
-      finish(null);
-    });
-  });
-}
-
-async function startPublicTunnel() {
-  const localHost =
-    HOST === "0.0.0.0" || HOST === "::" ? "127.0.0.1" : HOST;
-  const tunnelOptions = {
-    port: PORT,
-    local_host: localHost,
-  };
-
-  if (options.tunnelSubdomain) {
-    tunnelOptions.subdomain = options.tunnelSubdomain;
-  }
-
-  if (options.tunnelHost) {
-    tunnelOptions.host = options.tunnelHost;
-  }
-
-  console.log("Public tunnel: starting...");
-
-  const tunnel = await localtunnel(tunnelOptions);
-  const publicUrl = `${tunnel.url.replace(/\/$/, "")}/s/${SESSION_TOKEN}`;
-
-  console.log(`Public URL: ${publicUrl}`);
-
-  if (new URL(tunnel.url).hostname.endsWith(".loca.lt")) {
-    const password = await getLocaltunnelPassword();
-
-    if (password) {
-      console.log(`Tunnel password: ${password}`);
-    }
-  }
-
-  tunnel.on("error", (error) => {
-    console.error(`Public tunnel error: ${error.message}`);
-  });
-
-  tunnel.on("close", () => {
-    console.log("Public tunnel closed.");
-  });
-
-  ["SIGINT", "SIGTERM"].forEach((signal) => {
-    process.once(signal, () => {
-      tunnel.close();
-      process.kill(process.pid, signal);
-    });
-  });
-
-  return tunnel;
-}
-
-const VIEWER_HTML = String.raw`<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Terminal Viewer</title>
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/xterm/css/xterm.css" />
-    <style>
-      html,
-      body {
-        margin: 0;
-        padding: 0;
-        background: #050505;
-        color: #f2f2f2;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-      }
-
-      .topbar {
-        align-items: center;
-        background: #111;
-        border-bottom: 1px solid #2a2a2a;
-        box-sizing: border-box;
-        display: flex;
-        gap: 12px;
-        height: 42px;
-        justify-content: space-between;
-        padding: 0 14px;
-      }
-
-      .title {
-        font-size: 13px;
-        font-weight: 650;
-      }
-
-      .status {
-        align-items: center;
-        color: #b8b8b8;
-        display: flex;
-        font-size: 12px;
-        gap: 8px;
-        min-width: 0;
-      }
-
-      .dot {
-        background: #9ca3af;
-        border-radius: 999px;
-        flex: 0 0 auto;
-        height: 8px;
-        width: 8px;
-      }
-
-      .dot.connected {
-        background: #22c55e;
-      }
-
-      .dot.disconnected {
-        background: #ef4444;
-      }
-
-      #terminal {
-        width: 100vw;
-        height: calc(100vh - 42px);
-      }
-
-      .xterm {
-        height: 100%;
-      }
-    </style>
-  </head>
-  <body>
-    <header class="topbar">
-      <div class="title">Terminal Expose</div>
-      <div class="status">
-        <span id="dot" class="dot"></span>
-        <span id="status">Connecting</span>
-      </div>
-    </header>
-    <div id="terminal"></div>
-    <script src="/socket.io/socket.io.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/xterm/lib/xterm.js"></script>
-    <script>
-      const token = window.location.pathname.split('/').filter(Boolean).pop();
-      const statusText = document.getElementById('status');
-      const dot = document.getElementById('dot');
-      const term = new Terminal({
-        disableStdin: true,
-        cursorBlink: false,
-        convertEol: true,
-        fontFamily: '"JetBrains Mono", "SFMono-Regular", Consolas, monospace',
-        fontSize: 14,
-        scrollback: 10000,
-        theme: {
-          background: '#050505',
-          foreground: '#f4f4f5',
-          cursor: '#f4f4f5',
-          black: '#18181b',
-          red: '#ef4444',
-          green: '#22c55e',
-          yellow: '#eab308',
-          blue: '#3b82f6',
-          magenta: '#a855f7',
-          cyan: '#06b6d4',
-          white: '#e4e4e7'
-        }
-      });
-
-      term.open(document.getElementById('terminal'));
-
-      function setStatus(text, className) {
-        statusText.textContent = text;
-        dot.className = 'dot ' + (className || '');
-      }
-
-      const socket = io({
-        auth: { token },
-        reconnectionAttempts: 10,
-        timeout: 5000
-      });
-
-      socket.on('connect', () => {
-        setStatus('Connected', 'connected');
-      });
-
-      socket.on('terminal-output', (data) => {
-        term.write(data);
-      });
-
-      socket.on('terminal-exit', ({ exitCode, signal }) => {
-        const suffix = signal ? 'signal ' + signal : 'exit code ' + exitCode;
-        setStatus('Command ended: ' + suffix, 'disconnected');
-        term.writeln('\r\n[Command ended: ' + suffix + ']');
-      });
-
-      socket.on('connect_error', (error) => {
-        setStatus(error.message || 'Connection error', 'disconnected');
-      });
-
-      socket.on('disconnect', () => {
-        setStatus('Disconnected', 'disconnected');
-      });
-    </script>
-  </body>
-</html>`;
-
-const io = new Server(server, {
-  cors: {
-    origin: false,
-  },
-});
-
-io.use((socket, next) => {
-  const token = socket.handshake.auth?.token;
-
-  if (token !== SESSION_TOKEN) {
-    return next(new Error("unauthorized"));
-  }
-
-  return next();
-});
-
-const shell = pty.spawn(shellCommand, shellArgs, {
-  name: "xterm-256color",
-  cols: Number(process.env.TERM_COLS || 120),
-  rows: Number(process.env.TERM_ROWS || 40),
-  cwd: process.env.WORKDIR || process.cwd(),
-  env: {
-    ...process.env,
-    TERM: "xterm-256color",
-  },
-});
-
-let terminalBuffer = "";
-let terminalExit = null;
-
-if (process.stdin.isTTY) {
-  process.stdin.setRawMode(true);
-}
-
-process.stdin.resume();
-process.stdin.on("data", (data) => {
-  shell.write(data);
-});
-
-shell.onData((data) => {
-  if (ECHO_TO_STDOUT) {
-    process.stdout.write(data);
-  }
-
-  terminalBuffer += data;
-
-  if (terminalBuffer.length > MAX_BUFFER) {
-    terminalBuffer = terminalBuffer.slice(-MAX_BUFFER);
-  }
-
-  io.emit("terminal-output", data);
-});
-
-shell.onExit(({ exitCode, signal }) => {
-  terminalExit = { exitCode, signal };
-  io.emit("terminal-exit", terminalExit);
-  console.log(`Terminal command exited: code=${exitCode} signal=${signal}`);
+const { options, commandArgs: command } = parseArgs(rawArgs);
 
-  if (process.stdin.isTTY) {
-    process.stdin.setRawMode(false);
-  }
+const shellCommand = command.length > 0 ? command[0] : getDefaultShell();
+const shellArgs = command.length > 0 ? command.slice(1) : [];
 
-  setTimeout(() => {
-    process.exit(exitCode ?? 0);
-  }, 250);
-});
+// Initialize Terminal
+const terminalSession = new TerminalSession(shellCommand, shellArgs);
 
-app.use("/assets", express.static(path.join(__dirname, "public")));
+// Initialize Express App
+let ioInstance = null;
+const app = createApp(() => ioInstance, terminalSession);
+const server = http.createServer(app);
 
-app.get("/", (_, res) => {
-  res.type("html").send(`<!doctype html>
-    <html>
-      <head>
-        <meta charset="utf-8" />
-        <title>Terminal Expose</title>
-      </head>
-      <body style="font-family: system-ui, sans-serif; line-height: 1.5; padding: 32px;">
-        <h1>Terminal Expose</h1>
-        <p>This server is running. Use the private session URL printed in the container logs.</p>
-      </body>
-    </html>`);
-});
+// Initialize Socket.io
+ioInstance = setupSocket(server, terminalSession);
 
-app.get("/health", (_, res) => {
-  res.json({
-    ok: true,
-    viewers: io.engine.clientsCount,
-    exited: terminalExit,
+// Close server and process gracefully on terminal exit
+terminalSession.on("exit", () => {
+  console.log("Shutting down server port...");
+  server.close(() => {
+    // Ensure process is fully killed after server cleanly exits
+    process.exit(terminalSession.exit?.exitCode ?? 0);
   });
-});
-
-app.get("/s/:token", (req, res) => {
-  if (req.params.token !== SESSION_TOKEN) {
-    return res.status(403).send("Invalid session token");
-  }
-
-  res.type("html").send(VIEWER_HTML);
-});
 
-io.on("connection", (socket) => {
-  console.log(`Viewer connected: ${socket.id}`);
-
-  if (terminalBuffer) {
-    socket.emit("terminal-output", terminalBuffer);
-  }
-
-  if (terminalExit) {
-    socket.emit("terminal-exit", terminalExit);
-  }
-
-  socket.on("disconnect", () => {
-    console.log(`Viewer disconnected: ${socket.id}`);
-  });
+  // Force exit if server.close() hangs (e.g., active keep-alive connections)
+  setTimeout(
+    () => process.exit(terminalSession.exit?.exitCode ?? 0),
+    1000,
+  ).unref();
 });
 
 server.listen(PORT, HOST, () => {
   const localUrl = `http://localhost:${PORT}/s/${SESSION_TOKEN}`;
-  const externalUrl = process.env.EXTERNAL_URL
-    ? `${process.env.EXTERNAL_URL.replace(/\/$/, "")}/s/${SESSION_TOKEN}`
+  const externalUrl = EXTERNAL_URL
+    ? `${EXTERNAL_URL.replace(/\/$/, "")}/s/${SESSION_TOKEN}`
     : null;
 
   console.log("\n==============================");
@@ -500,20 +96,22 @@ server.listen(PORT, HOST, () => {
   console.log(`Command   : ${[shellCommand, ...shellArgs].join(" ")}`);
   console.log(`Local URL : ${localUrl}`);
 
-  getLanUrls().forEach((url) => console.log(`LAN URL   : ${url}`));
+  getLanUrls({ port: PORT, session_token: SESSION_TOKEN }).forEach((url) =>
+    console.log(`LAN URL   : ${url}`),
+  );
 
   if (externalUrl) {
     console.log(`Public URL: ${externalUrl}`);
   }
 
   if (options.publicTunnel) {
-    startPublicTunnel().catch((error) => {
+    startPublicTunnel(options, { HOST, PORT, SESSION_TOKEN }).catch((error) => {
       console.error(`Public tunnel failed: ${error.message}`);
     });
   }
 
   console.log("");
-  console.log("Share only the session URL with trusted viewers.");
+  console.log("Share only the session URL with trusted collaborators.");
   console.log("Use --public for internet access without router forwarding.");
   console.log("==============================\n");
 });

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "terminal-expose",
-  "version": "1.0.0",
-  "description": "Read-only terminal session sharing over HTTP and WebSocket.",
+  "version": "1.1.0",
+  "description": "Interactive terminal session sharing over HTTP and WebSocket.",
   "main": "index.js",
   "bin": {
     "terminal-expose": "index.js"
   },
   "files": [
     "index.js",
+    "src",
     "public"
   ],
   "scripts": {

package/src/config/env.js

@@ -0,0 +1,24 @@
+const crypto = require("crypto");
+
+const PORT = Number(process.env.PORT || 1111);
+const HOST = process.env.HOST || "0.0.0.0";
+const MAX_BUFFER = Number(process.env.MAX_BUFFER || 100000);
+const ECHO_TO_STDOUT = process.env.ECHO_TO_STDOUT !== "0";
+const SESSION_TOKEN =
+  process.env.SESSION_TOKEN || crypto.randomBytes(18).toString("base64url");
+const TERM_COLS = Number(process.env.TERM_COLS || 120);
+const TERM_ROWS = Number(process.env.TERM_ROWS || 40);
+const WORKDIR = process.env.WORKDIR || process.cwd();
+const EXTERNAL_URL = process.env.EXTERNAL_URL || null;
+
+module.exports = {
+  PORT,
+  HOST,
+  MAX_BUFFER,
+  ECHO_TO_STDOUT,
+  SESSION_TOKEN,
+  TERM_COLS,
+  TERM_ROWS,
+  WORKDIR,
+  EXTERNAL_URL,
+};

package/src/core/socket.js

@@ -0,0 +1,56 @@
+const { Server } = require("socket.io");
+const { SESSION_TOKEN } = require("../config/env");
+
+function setupSocket(server, terminalSession) {
+  const io = new Server(server, {
+    cors: {
+      origin: false,
+    },
+  });
+
+  io.use((socket, next) => {
+    const token = socket.handshake.auth?.token;
+
+    if (token !== SESSION_TOKEN) {
+      return next(new Error("unauthorized"));
+    }
+
+    return next();
+  });
+
+  io.on("connection", (socket) => {
+    console.log(`Client connected: ${socket.id}`);
+
+    if (terminalSession.buffer) {
+      socket.emit("terminal-output", terminalSession.buffer);
+    }
+
+    if (terminalSession.exit) {
+      socket.emit("terminal-exit", terminalSession.exit);
+    }
+
+    socket.on("terminal-input", (data) => {
+      terminalSession.write(data);
+    });
+
+    socket.on("terminal-resize", ({ cols, rows }) => {
+      terminalSession.resize(cols, rows);
+    });
+
+    socket.on("disconnect", () => {
+      console.log(`Client disconnected: ${socket.id}`);
+    });
+  });
+
+  terminalSession.on("data", (data) => {
+    io.emit("terminal-output", data);
+  });
+
+  terminalSession.on("exit", (exitState) => {
+    io.emit("terminal-exit", exitState);
+  });
+
+  return io;
+}
+
+module.exports = { setupSocket };

package/src/core/terminal.js

@@ -0,0 +1,88 @@
+const pty = require("node-pty");
+const {
+  ECHO_TO_STDOUT,
+  MAX_BUFFER,
+  TERM_COLS,
+  TERM_ROWS,
+  WORKDIR,
+} = require("../config/env");
+
+class TerminalSession {
+  constructor(shellCommand, shellArgs) {
+    this.buffer = "";
+    this.exit = null;
+    this.listeners = [];
+
+    this.shell = pty.spawn(shellCommand, shellArgs, {
+      name: "xterm-256color",
+      // cols: TERM_COLS,
+      // rows: TERM_ROWS,
+      cwd: WORKDIR,
+      env: {
+        ...process.env,
+        TERM: "xterm-256color",
+      },
+    });
+
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.on("data", (data) => {
+      this.shell.write(data);
+    });
+
+    this.shell.onData((data) => {
+      if (ECHO_TO_STDOUT) {
+        process.stdout.write(data);
+      }
+
+      this.buffer += data;
+
+      if (this.buffer.length > MAX_BUFFER) {
+        this.buffer = this.buffer.slice(-MAX_BUFFER);
+      }
+
+      this.emit("data", data);
+    });
+
+    this.shell.onExit(({ exitCode, signal }) => {
+      this.exit = { exitCode, signal };
+      this.emit("exit", this.exit);
+
+      console.log(`Terminal command exited: code=${exitCode} signal=${signal}`);
+
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+    });
+  }
+
+  write(data) {
+    if (this.shell) {
+      this.shell.write(data);
+    }
+  }
+
+  resize(cols, rows) {
+    if (this.shell && cols && rows) {
+      try {
+        this.shell.resize(cols, rows);
+      } catch (err) {
+        console.error("Failed to resize terminal", err);
+      }
+    }
+  }
+
+  on(event, callback) {
+    this.listeners.push({ event, callback });
+  }
+
+  emit(event, data) {
+    this.listeners
+      .filter((listener) => listener.event === event)
+      .forEach((listener) => listener.callback(data));
+  }
+}
+
+module.exports = { TerminalSession };

package/src/core/tunnel.js

@@ -0,0 +1,96 @@
+const https = require("https");
+const localtunnel = require("localtunnel");
+
+function getLocaltunnelPassword() {
+  return new Promise((resolve) => {
+    let settled = false;
+
+    function finish(value) {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      resolve(value);
+    }
+
+    const request = https.get(
+      "https://loca.lt/mytunnelpassword",
+      (response) => {
+        if (response.statusCode !== 200) {
+          response.resume();
+          finish(null);
+          return;
+        }
+
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          finish(body.trim() || null);
+        });
+      },
+    );
+
+    request.setTimeout(3000, () => {
+      request.destroy();
+      finish(null);
+    });
+
+    request.on("error", () => {
+      finish(null);
+    });
+  });
+}
+
+async function startPublicTunnel(options, { HOST, PORT, SESSION_TOKEN }) {
+  const localHost = HOST === "0.0.0.0" || HOST === "::" ? "127.0.0.1" : HOST;
+  const tunnelOptions = {
+    port: PORT,
+    local_host: localHost,
+  };
+
+  if (options.tunnelSubdomain) {
+    tunnelOptions.subdomain = options.tunnelSubdomain;
+  }
+
+  if (options.tunnelHost) {
+    tunnelOptions.host = options.tunnelHost;
+  }
+
+  console.log("Public tunnel: starting...");
+
+  const tunnel = await localtunnel(tunnelOptions);
+  const publicUrl = `${tunnel.url.replace(/\/$/, "")}/s/${SESSION_TOKEN}`;
+
+  console.log(`Public URL: ${publicUrl}`);
+
+  if (new URL(tunnel.url).hostname.endsWith(".loca.lt")) {
+    const password = await getLocaltunnelPassword();
+
+    if (password) {
+      console.log(`Tunnel password: ${password}`);
+    }
+  }
+
+  tunnel.on("error", (error) => {
+    console.error(`Public tunnel error: ${error.message}`);
+  });
+
+  tunnel.on("close", () => {
+    console.log("Public tunnel closed.");
+  });
+
+  ["SIGINT", "SIGTERM"].forEach((signal) => {
+    process.once(signal, () => {
+      tunnel.close();
+      process.kill(process.pid, signal);
+    });
+  });
+
+  return tunnel;
+}
+
+module.exports = { startPublicTunnel };

package/src/server/app.js

@@ -0,0 +1,46 @@
+const express = require("express");
+const path = require("path");
+const { SESSION_TOKEN } = require("../config/env");
+const { VIEWER_HTML } = require("../templates/viewer");
+
+function createApp(ioGetter, terminalSession) {
+  const app = express();
+
+  // We are referring to public directory in root
+  app.use("/assets", express.static(path.join(__dirname, "../../public")));
+
+  app.get("/", (_, res) => {
+    res.type("html").send(`<!doctype html>
+      <html>
+        <head>
+          <meta charset="utf-8" />
+          <title>Terminal Expose</title>
+        </head>
+        <body style="font-family: system-ui, sans-serif; line-height: 1.5; padding: 32px;">
+          <h1>Terminal Expose</h1>
+          <p>This server is running. Use the private session URL printed in the container logs.</p>
+        </body>
+      </html>`);
+  });
+
+  app.get("/health", (_, res) => {
+    const io = ioGetter();
+    res.json({
+      ok: true,
+      clients: io ? io.engine.clientsCount : 0,
+      exited: terminalSession.exit,
+    });
+  });
+
+  app.get("/s/:token", (req, res) => {
+    if (req.params.token !== SESSION_TOKEN) {
+      return res.status(403).send("Invalid session token");
+    }
+
+    res.type("html").send(VIEWER_HTML);
+  });
+
+  return app;
+}
+
+module.exports = { createApp };

package/src/templates/viewer.js

@@ -0,0 +1,95 @@
+const VIEWER_HTML = String.raw`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Terminal Session</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/xterm/css/xterm.css" />
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: #050505;
+        color: #f2f2f2;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+      }
+
+      #terminal {
+        width: 100vw;
+        height: 100vh;
+      }
+
+      .xterm {
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="terminal"></div>
+    <script src="/socket.io/socket.io.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/xterm/lib/xterm.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/xterm-addon-fit/lib/xterm-addon-fit.js"></script>
+    <script>
+      const token = window.location.pathname.split('/').filter(Boolean).pop();
+      const term = new Terminal({
+        cursorBlink: true,
+        convertEol: true,
+        fontFamily: '"JetBrains Mono", "SFMono-Regular", Consolas, monospace',
+        fontSize: 14,
+        scrollback: 10000,
+        theme: {
+          background: '#050505',
+          foreground: '#f4f4f5',
+          cursor: '#f4f4f5',
+          black: '#18181b',
+          red: '#ef4444',
+          green: '#22c55e',
+          yellow: '#eab308',
+          blue: '#3b82f6',
+          magenta: '#a855f7',
+          cyan: '#06b6d4',
+          white: '#e4e4e7'
+        }
+      });
+
+      const fitAddon = new FitAddon.FitAddon();
+      term.loadAddon(fitAddon);
+
+      term.open(document.getElementById('terminal'));
+      fitAddon.fit();
+
+      const socket = io({
+        auth: { token },
+        reconnectionAttempts: 10,
+        timeout: 5000
+      });
+
+      window.addEventListener('resize', () => {
+        fitAddon.fit();
+        socket.emit('terminal-resize', { cols: term.cols, rows: term.rows });
+      });
+
+      socket.on('connect', () => {
+        socket.emit('terminal-resize', { cols: term.cols, rows: term.rows });
+      });
+
+      socket.on('terminal-output', (data) => {
+        term.write(data);
+      });
+
+      term.onData((data) => {
+        socket.emit('terminal-input', data);
+      });
+
+      socket.on('terminal-exit', ({ exitCode, signal }) => {
+        const suffix = signal ? 'signal ' + signal : 'exit code ' + exitCode;
+        term.writeln('\r\n[Command ended: ' + suffix + ']');
+      });
+    </script>
+  </body>
+</html>`;
+
+module.exports = { VIEWER_HTML };

package/src/utils/args.js

@@ -0,0 +1,52 @@
+function parseArgs(args) {
+  const options = {
+    publicTunnel: false,
+    tunnelSubdomain: process.env.TUNNEL_SUBDOMAIN || null,
+    tunnelHost: process.env.TUNNEL_HOST || undefined,
+  };
+  const commandArgs = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--public" || arg === "--tunnel") {
+      options.publicTunnel = true;
+      continue;
+    }
+
+    if (arg === "--subdomain") {
+      options.tunnelSubdomain = args[index + 1] || null;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--subdomain=")) {
+      options.tunnelSubdomain = arg.slice("--subdomain=".length) || null;
+      continue;
+    }
+
+    if (arg === "--tunnel-host") {
+      options.tunnelHost = args[index + 1] || undefined;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--tunnel-host=")) {
+      options.tunnelHost = arg.slice("--tunnel-host=".length) || undefined;
+      continue;
+    }
+
+    commandArgs.push(arg);
+  }
+
+  if (
+    process.env.PUBLIC_TUNNEL === "1" ||
+    process.env.PUBLIC_TUNNEL === "true"
+  ) {
+    options.publicTunnel = true;
+  }
+
+  return { options, commandArgs };
+}
+
+module.exports = { parseArgs };

package/src/utils/system.js

@@ -0,0 +1,34 @@
+const os = require("os");
+
+const getDefaultShell = () => {
+  switch (process.platform) {
+    case "win32":
+      return process.env.ComSpec || "powershell.exe";
+
+    case "darwin":
+      return process.env.SHELL || "/bin/zsh";
+
+    case "linux":
+      return process.env.SHELL || "/bin/bash";
+
+    default:
+      return process.env.SHELL || "/bin/sh";
+  }
+};
+
+function getLanUrls({ port, session_token }) {
+  const urls = [];
+  const interfaces = os.networkInterfaces();
+
+  Object.values(interfaces).forEach((addresses = []) => {
+    addresses
+      .filter((address) => address.family === "IPv4" && !address.internal)
+      .forEach((address) => {
+        urls.push(`http://${address.address}:${port}/s/${session_token}`);
+      });
+  });
+
+  return urls;
+}
+
+module.exports = { getDefaultShell, getLanUrls };