feat: add shared tunnel server for cloud deployments

- Add TunnelServer class for single-port tunnel multiplexing
- Add --tunnel-port CLI option to enable shared tunnel mode
- Update TunnelAgent to optionally use shared TunnelServer
- Client sends ID on connect when sharedTunnel flag is set
- Server returns sharedTunnel: true and tunnelPort in response
- Document cloud deployment configuration in README

This fixes 404 errors when running pipenet server in containerized
environments like fly.io where only specific ports are exposed.

Author: punkpeye

README.md

@@ -94,6 +94,9 @@ npx pipenet server --port 3000 --domain tunnel.example.com
 # With multiple domains
 npx pipenet server --port 3000 --domain tunnel.example.com --domain tunnel.example.org
 
+# For cloud deployments (single tunnel port mode)
+npx pipenet server --port 3000 --tunnel-port 3001 --domain tunnel.example.com
+
 # Or programmatically
 ```
 
@@ -105,8 +108,14 @@ const server = createServer({
   secure: false,                     // Optional: require HTTPS
   landing: 'https://pipenet.dev',    // Optional: landing page URL
   maxTcpSockets: 10,                 // Optional: max sockets per client
+  tunnelPort: 3001,                  // Optional: shared tunnel port for cloud deployments
 });
 
+// Start tunnel server if using shared tunnel port
+if (server.tunnelServer) {
+  await server.tunnelServer.listen(3001);
+}
+
 server.listen(3000, () => {
   console.log('pipenet server listening on port 3000');
 });
@@ -118,13 +127,45 @@ server.listen(3000, () => {
 - `secure` (boolean) Require HTTPS connections
 - `landing` (string) URL to redirect root requests to
 - `maxTcpSockets` (number) Maximum number of TCP sockets per client (default: 10)
+- `tunnelPort` (number) Shared tunnel port for cloud deployments (enables single-port mode)
 
 ### Server API Endpoints
 
 - `GET /api/status` - Server status and tunnel count
 - `GET /api/tunnels/:id/status` - Status of a specific tunnel
 - `GET /:id` - Request a new tunnel with the specified ID
 
+### Cloud Deployments
+
+When deploying pipenet server to cloud platforms like fly.io, Docker, or Kubernetes, you typically can only expose a limited number of ports. By default, pipenet creates a random TCP port for each tunnel client, which doesn't work well in these environments.
+
+Use the `--tunnel-port` option to enable single-port mode, where all tunnel clients connect to a single shared port:
+
+```bash
+# fly.io example
+pipenet server --port 8080 --tunnel-port 8081 --domain tunnel.example.com --secure
+```
+
+Then expose both ports in your deployment configuration. For fly.io:
+
+```toml
+[[services]]
+  internal_port = 8080
+  protocol = "tcp"
+  [[services.ports]]
+    port = 80
+    handlers = ["http"]
+  [[services.ports]]
+    port = 443
+    handlers = ["http", "tls"]
+
+[[services]]
+  internal_port = 8081
+  protocol = "tcp"
+  [[services.ports]]
+    port = 8081
+```
+
 ## Why pipenet?
 
 pipenet was developed by [glama.ai](https://glama.ai) to enable local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers to connect with remote AI clients (e.g., to give AI assistants access to your local file system).

src/Tunnel.ts

@@ -26,6 +26,7 @@ interface ServerResponse {
   maxConnCount?: number;
   message?: string;
   port: number;
+  sharedTunnel?: boolean;
   url: string;
 }
 
@@ -43,6 +44,7 @@ interface TunnelInfo extends TunnelClusterOptions {
   remoteHost: string;
   remoteIp: string;
   remotePort: number;
+  sharedTunnel?: boolean;
   url: string;
 }
 
@@ -141,7 +143,7 @@ export class Tunnel extends EventEmitter {
   }
 
   private _getInfo(body: ServerResponse): TunnelInfo {
-    const { cachedUrl, id, ip, maxConnCount, port, url } = body;
+    const { cachedUrl, id, ip, maxConnCount, port, sharedTunnel, url } = body;
     const { host, localHost, port: localPort } = this.opts;
     const { allowInvalidCert, localCa, localCert, localHttps, localKey } = this.opts;
 
@@ -159,6 +161,7 @@ export class Tunnel extends EventEmitter {
       remoteHost: new URL(host!).hostname,
       remoteIp: ip,
       remotePort: port,
+      sharedTunnel,
       url,
     };
   }

src/TunnelCluster.ts

@@ -22,6 +22,7 @@ export interface TunnelClusterOptions {
   remoteHost?: string;
   remoteIp?: string;
   remotePort?: number;
+  sharedTunnel?: boolean;
   url?: string;
 }
 
@@ -158,6 +159,11 @@ export class TunnelCluster extends EventEmitter {
     });
 
     remote.once('connect', () => {
+      // Send client ID as the first message for shared tunnel server mode
+      if (opt.sharedTunnel && opt.name) {
+        log('sending client ID for shared tunnel: %s', opt.name);
+        remote.write(opt.name + '\n');
+      }
       this.emit('open', remote);
       connLocal();
     });

src/cli.ts

@@ -27,6 +27,7 @@ interface ServerOptions {
   'max-sockets'?: number;
   port: number;
   secure?: boolean;
+  'tunnel-port'?: number;
 }
 
 async function runClient(opts: ClientOptions) {
@@ -75,14 +76,21 @@ async function runClient(opts: ClientOptions) {
   });
 }
 
-function runServer(opts: ServerOptions) {
+async function runServer(opts: ServerOptions) {
   const server = createServer({
     domains: opts.domain,
     landing: opts.landing,
     maxTcpSockets: opts['max-sockets'],
     secure: opts.secure,
+    tunnelPort: opts['tunnel-port'],
   });
 
+  // Start the tunnel server if configured
+  if (server.tunnelServer && opts['tunnel-port']) {
+    await server.tunnelServer.listen(opts['tunnel-port'], opts.address);
+    console.log('tunnel server listening on port %d', opts['tunnel-port']);
+  }
+
   const listenCallback = () => {
     console.log('pipenet server listening on port %d', opts.port);
     if (opts.address) {
@@ -101,6 +109,9 @@ function runServer(opts: ServerOptions) {
 
   process.on('SIGINT', () => {
     console.log('shutting down server...');
+    if (server.tunnelServer) {
+      server.tunnelServer.close();
+    }
     server.close(() => {
       process.exit(0);
     });
@@ -210,6 +221,11 @@ yargs(hideBin(process.argv))
           default: 10,
           describe: 'Maximum number of TCP sockets per client',
           type: 'number',
+        })
+        .option('tunnel-port', {
+          alias: 't',
+          describe: 'Port for tunnel connections (enables single-port mode for cloud deployments)',
+          type: 'number',
         });
     },
     (argv) => {

src/server/ClientManager.ts

@@ -3,9 +3,11 @@ import { hri } from 'human-readable-ids';
 
 import { Client } from './Client.js';
 import { TunnelAgent } from './TunnelAgent.js';
+import type { TunnelServer } from './TunnelServer.js';
 
 export interface ClientManagerOptions {
   maxTcpSockets?: number;
+  tunnelServer?: TunnelServer;
 }
 
 export interface NewClientInfo {
@@ -47,6 +49,7 @@ export class ClientManager {
     const agent = new TunnelAgent({
       clientId: id,
       maxTcpSockets: 10,
+      tunnelServer: this.opt.tunnelServer,
     });
 
     const client = new Client({ agent, id });

src/server/TunnelAgent.ts

@@ -3,6 +3,8 @@ import { Agent, ClientRequestArgs } from 'http';
 import net from 'net';
 import { Duplex } from 'stream';
 
+import type { TunnelServer } from './TunnelServer.js';
+
 const DEFAULT_MAX_SOCKETS = 10;
 
 export interface TunnelAgentListenInfo {
@@ -12,6 +14,7 @@ export interface TunnelAgentListenInfo {
 export interface TunnelAgentOptions {
   clientId?: string;
   maxTcpSockets?: number;
+  tunnelServer?: TunnelServer;
 }
 
 export interface TunnelAgentStats {
@@ -23,21 +26,28 @@ type CreateConnectionCallback = (err: Error | null, socket: Duplex) => void;
 export class TunnelAgent extends Agent {
   public started: boolean;
   private availableSockets: net.Socket[];
+  private clientId?: string;
   private closed: boolean;
   private connectedSockets: number;
   private log: debug.Debugger;
   private maxTcpSockets: number;
-  private server: net.Server;
+  private server?: net.Server;
+  private tunnelServer?: TunnelServer;
   private waitingCreateConn: CreateConnectionCallback[];
 
   constructor(options: TunnelAgentOptions = {}) {
     super({ keepAlive: true, maxFreeSockets: 1 });
     this.availableSockets = [];
     this.waitingCreateConn = [];
+    this.clientId = options.clientId;
     this.log = debug(`lt:TunnelAgent[${options.clientId}]`);
     this.connectedSockets = 0;
     this.maxTcpSockets = options.maxTcpSockets || DEFAULT_MAX_SOCKETS;
-    this.server = net.createServer();
+    this.tunnelServer = options.tunnelServer;
+    // Only create a local server if no shared tunnel server is provided
+    if (!this.tunnelServer) {
+      this.server = net.createServer();
+    }
     this.started = false;
     this.closed = false;
   }
@@ -61,14 +71,35 @@ export class TunnelAgent extends Agent {
   }
 
   destroy(): void {
-    this.server.close();
+    if (this.tunnelServer && this.clientId) {
+      this.tunnelServer.unregisterHandler(this.clientId);
+    }
+    if (this.server) {
+      this.server.close();
+    }
     super.destroy();
   }
 
   listen(): Promise<TunnelAgentListenInfo> {
     if (this.started) throw new Error('already started');
     this.started = true;
 
+    // If using shared tunnel server, register handler and return port 0
+    // (the actual port is the tunnel server's port, handled externally)
+    if (this.tunnelServer && this.clientId) {
+      this.tunnelServer.registerHandler(this.clientId, (socket) => {
+        this._onConnection(socket);
+      });
+      this.log('registered with shared tunnel server');
+      // Return port 0 to indicate shared tunnel server mode
+      return Promise.resolve({ port: 0 });
+    }
+
+    // Legacy mode: create our own TCP server
+    if (!this.server) {
+      throw new Error('No server available');
+    }
+
     this.server.on('close', this._onClose.bind(this));
     this.server.on('connection', this._onConnection.bind(this));
     this.server.on('error', (err: NodeJS.ErrnoException) => {
@@ -77,8 +108,8 @@ export class TunnelAgent extends Agent {
     });
 
     return new Promise((resolve) => {
-      this.server.listen(() => {
-        const addr = this.server.address() as net.AddressInfo;
+      this.server!.listen(() => {
+        const addr = this.server!.address() as net.AddressInfo;
         this.log('tcp server listening on port: %d', addr.port);
         resolve({ port: addr.port });
       });