pinggy 0.4.5 → 0.4.7

package/README.md

@@ -11,6 +11,8 @@ Create secure, shareable tunnels to your localhost and manage them from the comm
 - Remote management via secure WebSocket connection (works with Pinggy Dashboard)
 - Configurable logging to file and/or stdout
 - Save and load configuration files
+- Config store for saving, listing, updating, and starting named tunnel configs
+- Auto-start support for launching saved tunnels automatically
 - Simple file server mode for quickly sharing local files
 - Built-in TUI (Text User Interface) for viewing tunnel statistics, requests, and responses in real time
 
@@ -95,11 +97,11 @@ The CLI supports both SSH-style flags and more descriptive long flags. Below is
 | `--logfile` | Path to log file |
 | `--v` | Print logs to stdout |
 | `--vv` | Detailed logs (Node.js SDK + Libpinggy) |
-| `--vvv` | Enable logs from CLI, SDK, and Libpinggy |Libpinggy.
+| `--vvv` | Enable logs from CLI, SDK, and Libpinggy |
 
 ---
 
-### **Config**
+### **Config (File-based)**
 | Flag | Description |
 |------|-------------|
 | `--saveconf <file>` | Create configuration file with provided options |
@@ -199,6 +201,94 @@ pinggy --conf ./myconfig.json -p 8080
 ```
 
 
+## Config management
+
+The CLI includes a built-in config store for saving, listing, and starting tunnel configurations. Configs are persisted as JSON files in your platform's config directory (`~/.config/pinggy/tunnels/` on Linux/macOS, `%APPDATA%/pinggy/tunnels/` on Windows).
+
+### Save a tunnel config
+```bash
+pinggy config save my-tunnel -l 3000 token@pro.pinggy.io
+```
+
+### Save with auto-start enabled
+```bash
+pinggy config save my-tunnel --auto -l 3000
+```
+
+### List all saved configs
+```bash
+pinggy config list
+```
+
+### View details of a saved config
+```bash
+pinggy config show my-tunnel
+pinggy config show my-tunnel other-tunnel    # View multiple configs
+```
+
+### Update a saved config
+```bash
+pinggy config update my-tunnel -l 4000
+```
+
+### Enable or disable auto-start
+```bash
+pinggy config auto my-tunnel
+pinggy config noauto my-tunnel
+pinggy config auto tunnel1 tunnel2           # Multiple configs at once
+```
+
+### Delete a saved config
+```bash
+pinggy config delete my-tunnel
+pinggy config delete tunnel1 tunnel2         # Delete multiple
+```
+
+### Shorthand: view config details
+```bash
+pinggy config my-tunnel                      # Same as: pinggy config show my-tunnel
+```
+
+Configs can be looked up by name (exact match) or by configId prefix (partial match).
+
+
+## Starting saved tunnels
+
+### Start a saved tunnel
+```bash
+pinggy start my-tunnel
+```
+
+### Start with runtime overrides
+```bash
+pinggy start my-tunnel -l 4000
+```
+
+### Start multiple tunnels
+```bash
+pinggy start tunnel1 tunnel2
+```
+
+### Start all auto-start tunnels
+```bash
+pinggy start --all
+```
+
+### Start with remote management
+```bash
+pinggy start --all --remote-management <API_KEY>
+pinggy start tunnel1 tunnel2 --remote-management <API_KEY>
+```
+
+### Start with logging enabled
+```bash
+pinggy start my-tunnel --vvv
+pinggy start --all --logfile /tmp/pinggy.log --loglevel DEBUG
+```
+
+> **Note:** Runtime overrides (`-l`, `--type`, `--token`, etc.) can only be used when starting a single tunnel. For multiple tunnels, update the saved config first with `pinggy config update`.
+
+
 ## File server mode
 Serve a local directory quickly over a tunnel:
 `  pinggy --serve /path/to/files`
@@ -216,5 +306,3 @@ This package follows semantic versioning. See package.json for the current versi
 
 ## License
 Apache License Version 2.0
-
-

package/dist/{chunk-HUN2MRZO.js → chunk-3RTRUYNW.js}

@@ -83,7 +83,9 @@ function enablePackageLogging(opts) {
   return applyLoggingConfig(opts ?? {});
 }
 function enableLoggingByLogLevelInSdk(loglevel, logFilePath) {
-  if (!loglevel) return;
+  if (!loglevel) {
+    return;
+  }
   const l = loglevel.toUpperCase();
   if (loglevel === "DEBUG") {
     pinggy.setDebugLogging(true, LogLevel.DEBUG, logFilePath);

package/dist/{chunk-MBN3YBO4.js → chunk-443UO6IY.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-HUN2MRZO.js";
+} from "./chunk-3RTRUYNW.js";
 
 // src/utils/printer.ts
 import pico2 from "picocolors";
@@ -66,6 +66,11 @@ var _CLIPrinter = class _CLIPrinter {
     const def = this.errorDefinitions.find((d) => d.match(err));
     const msg = def.message(err);
     console.error(pico2.red(pico2.bold("\u2716 Error:")), pico2.red(msg));
+  }
+  static fatal(err) {
+    const def = this.errorDefinitions.find((d) => d.match(err));
+    const msg = def.message(err);
+    console.error(pico2.red(pico2.bold("\u2716 Fatal Error:")), pico2.red(msg));
     process.exit(1);
   }
   static red(message) {
@@ -259,7 +264,9 @@ var TunnelManager = class _TunnelManager {
    */
   async startTunnel(tunnelId) {
     const managed = this.tunnelsByTunnelId.get(tunnelId);
-    if (!managed) throw new Error(`Tunnel with id "${tunnelId}" not found`);
+    if (!managed) {
+      throw new Error(`Tunnel with id "${tunnelId}" not found`);
+    }
     logger.info("Starting tunnel", { tunnelId });
     let urls;
     try {
@@ -307,7 +314,9 @@ var TunnelManager = class _TunnelManager {
    */
   stopTunnel(tunnelId) {
     const managed = this.tunnelsByTunnelId.get(tunnelId);
-    if (!managed) throw new Error(`Tunnel "${tunnelId}" not found`);
+    if (!managed) {
+      throw new Error(`Tunnel "${tunnelId}" not found`);
+    }
     logger.info("Stopping tunnel", { tunnelId, configId: managed.configId });
     try {
       managed.instance.stop();
@@ -488,12 +497,16 @@ var TunnelManager = class _TunnelManager {
   getTunnelInstance(configId, tunnelId) {
     if (configId) {
       const managed = this.tunnelsByConfigId.get(configId);
-      if (!managed) throw new Error(`Tunnel "${configId}" not found`);
+      if (!managed) {
+        throw new Error(`Tunnel "${configId}" not found`);
+      }
       return managed.instance;
     }
     if (tunnelId) {
       const managed = this.tunnelsByTunnelId.get(tunnelId);
-      if (!managed) throw new Error(`Tunnel "${tunnelId}" not found`);
+      if (!managed) {
+        throw new Error(`Tunnel "${tunnelId}" not found`);
+      }
       return managed.instance;
     }
     throw new Error(`Either configId or tunnelId must be provided`);
@@ -672,12 +685,16 @@ var TunnelManager = class _TunnelManager {
   getManagedTunnel(configId, tunnelId) {
     if (configId) {
       const managed = this.tunnelsByConfigId.get(configId);
-      if (!managed) throw new Error(`Tunnel "${configId}" not found`);
+      if (!managed) {
+        throw new Error(`Tunnel "${configId}" not found`);
+      }
       return managed;
     }
     if (tunnelId) {
       const managed = this.tunnelsByTunnelId.get(tunnelId);
-      if (!managed) throw new Error(`Tunnel "${tunnelId}" not found`);
+      if (!managed) {
+        throw new Error(`Tunnel "${tunnelId}" not found`);
+      }
       return managed;
     }
     throw new Error(`Either configId or tunnelId must be provided`);
@@ -1066,7 +1083,9 @@ var TunnelManager = class _TunnelManager {
   notifyPollingErrorListeners(tunnelId, errorMsg) {
     try {
       const listeners = this.tunnelPollingErrorListeners.get(tunnelId);
-      if (!listeners) return;
+      if (!listeners) {
+        return;
+      }
       for (const [id, listener] of listeners) {
         try {
           listener(tunnelId, errorMsg);
@@ -1081,7 +1100,9 @@ var TunnelManager = class _TunnelManager {
   notifyErrorListeners(tunnelId, errorMsg, isFatal) {
     try {
       const listeners = this.tunnelErrorListeners.get(tunnelId);
-      if (!listeners) return;
+      if (!listeners) {
+        return;
+      }
       for (const [id, listener] of listeners) {
         try {
           listener(tunnelId, errorMsg, isFatal);
@@ -1130,7 +1151,9 @@ var TunnelManager = class _TunnelManager {
             managedTunnel.stoppedAt = (/* @__PURE__ */ new Date()).toISOString();
           }
           const listeners = this.tunnelDisconnectListeners.get(tunnelId);
-          if (!listeners) return;
+          if (!listeners) {
+            return;
+          }
           for (const [id, listener] of listeners) {
             try {
               listener(tunnelId, error, messages);
@@ -1158,7 +1181,9 @@ var TunnelManager = class _TunnelManager {
         try {
           logger.info("Tunnel will reconnect", { tunnelId, error, messages });
           const listeners = this.tunnelWillReconnectListeners.get(tunnelId);
-          if (!listeners) return;
+          if (!listeners) {
+            return;
+          }
           for (const [id, listener] of listeners) {
             try {
               listener(tunnelId, error, messages);
@@ -1186,7 +1211,9 @@ var TunnelManager = class _TunnelManager {
         try {
           logger.info("Tunnel reconnecting", { tunnelId, retryCnt });
           const listeners = this.tunnelReconnectingListeners.get(tunnelId);
-          if (!listeners) return;
+          if (!listeners) {
+            return;
+          }
           for (const [id, listener] of listeners) {
             try {
               listener(tunnelId, retryCnt);
@@ -1264,7 +1291,9 @@ var TunnelManager = class _TunnelManager {
             managedTunnel.stoppedAt = (/* @__PURE__ */ new Date()).toISOString();
           }
           const listeners = this.tunnelReconnectionFailedListeners.get(tunnelId);
-          if (!listeners) return;
+          if (!listeners) {
+            return;
+          }
           for (const [id, listener] of listeners) {
             try {
               listener(tunnelId, retryCnt);
@@ -1288,7 +1317,9 @@ var TunnelManager = class _TunnelManager {
         try {
           logger.debug("Error in Tunnel Worker", { tunnelId, errorMessage: error.message });
           const listeners = this.tunnelWorkerErrorListeners.get(tunnelId);
-          if (!listeners) return;
+          if (!listeners) {
+            return;
+          }
           for (const [id, listener] of listeners) {
             try {
               listener(tunnelId, error);
@@ -1771,6 +1802,26 @@ var TunnelOperations = class {
     }
     return status;
   }
+  // --- Placeholder response ---
+  buildPendingTunnelResponse(tunnelid, tunnelConfig, configid, tunnelName, serve) {
+    return {
+      tunnelid,
+      remoteurls: [],
+      tunnelconfig: pinggyOptionsToTunnelConfig(tunnelConfig, configid, tunnelName, false, void 0, serve),
+      status: this.buildStatus(tunnelid, "starting" /* Starting */, "" /* NoError */),
+      stats: newStats()
+    };
+  }
+  buildPendingTunnelResponseV2(tunnelid, tunnelConfig, configFromCli, configid, tunnelName, serve) {
+    return {
+      tunnelid,
+      remoteurls: [],
+      tunnelconfig: pinggyOptionsToTunnelConfigV1(tunnelConfig, configFromCli),
+      status: this.buildStatus(tunnelid, "starting" /* Starting */, "" /* NoError */),
+      stats: newStats(),
+      greetmsg: ""
+    };
+  }
   // --- Helper to construct TunnelResponse ---
   async buildTunnelResponse(tunnelid, tunnelConfig, configid, tunnelName, serve) {
     const [status, stats, tlsInfo, greetMsg, remoteurls] = await Promise.all([
@@ -1811,10 +1862,10 @@ var TunnelOperations = class {
     });
   }
   // --- Operations ---
-  async handleStart(config) {
+  async handleStart(config, noWait = false) {
     try {
       const opts = tunnelConfigToPinggyOptions(config);
-      const { tunnelid, instance, tunnelName, serve, tunnelConfig } = await this.tunnelManager.createTunnel({
+      const managed = await this.tunnelManager.createTunnel({
         ...opts,
         configId: config.configid,
         name: config.configname,
@@ -1822,36 +1873,52 @@ var TunnelOperations = class {
           serve: config.serve
         }
       });
-      await this.tunnelManager.startTunnel(tunnelid);
+      const { tunnelid, tunnelName, serve, tunnelConfig } = managed;
+      const startPromise = this.tunnelManager.startTunnel(tunnelid);
+      if (noWait) {
+        startPromise.catch((err) => {
+          logger.error("No-wait startTunnel failed", { tunnelid, err: String(err) });
+        });
+        return this.buildPendingTunnelResponse(tunnelid, tunnelConfig, config.configid, tunnelName, serve);
+      }
+      await startPromise;
       const tunnelPconfig = await this.tunnelManager.getTunnelConfig("", tunnelid);
-      const resp = this.buildTunnelResponse(tunnelid, tunnelPconfig, config.configid, tunnelName, serve);
-      return resp;
+      return this.buildTunnelResponse(tunnelid, tunnelPconfig, config.configid, tunnelName, serve);
     } catch (err) {
       return this.error(ErrorCode.ErrorStartingTunnel, err, "Unknown error occurred while starting tunnel");
     }
   }
-  async handleStartV2(config) {
+  async handleStartV2(config, noWait = false) {
     try {
-      const { tunnelid, instance, serve } = await this.tunnelManager.createTunnel(config);
+      const managed = await this.tunnelManager.createTunnel(config);
+      const { tunnelid, serve, tunnelConfig } = managed;
       await this.tunnelManager.startTunnel(tunnelid);
       const tunnelPconfig = await this.tunnelManager.getTunnelConfig("", tunnelid);
-      const resp = this.buildTunnelResponseV2(tunnelid, tunnelPconfig, config, config.configId, config.name, config.serve);
-      return resp;
+      return this.buildTunnelResponseV2(tunnelid, tunnelPconfig, config, config.configId, config.name, config.serve);
     } catch (err) {
       return this.error(ErrorCode.ErrorStartingTunnel, err, "Unknown error occurred while starting tunnel");
     }
   }
-  async handleUpdateConfig(config) {
+  async handleUpdateConfig(config, noWait = false) {
     try {
       const opts = tunnelConfigToPinggyOptions(config);
-      const tunnel = await this.tunnelManager.updateConfig({
+      const updateOpts = {
         ...opts,
         configId: config.configid,
         name: config.configname,
         optional: {
           serve: config.serve
         }
-      });
+      };
+      if (noWait) {
+        const existing = this.tunnelManager.getManagedTunnel(config.configid);
+        if (!existing.tunnelConfig) throw new Error("Invalid tunnel state before configuration update");
+        this.tunnelManager.updateConfig(updateOpts).catch((err) => {
+          logger.error("No-wait updateConfig failed", { configid: config.configid, err: String(err) });
+        });
+        return this.buildPendingTunnelResponse(existing.tunnelid, existing.tunnelConfig, config.configid, existing.tunnelName, existing.serve);
+      }
+      const tunnel = await this.tunnelManager.updateConfig(updateOpts);
       if (!tunnel.instance || !tunnel.tunnelConfig)
         throw new Error("Invalid tunnel state after configuration update");
       return this.buildTunnelResponse(tunnel.tunnelid, tunnel.tunnelConfig, config.configid, tunnel.tunnelName, tunnel.serve);
@@ -1859,8 +1926,17 @@ var TunnelOperations = class {
       return this.error(ErrorCode.InternalServerError, err, "Failed to update tunnel configuration");
     }
   }
-  async handleUpdateConfigV2(config) {
+  async handleUpdateConfigV2(config, noWait = false) {
     try {
+      if (noWait) {
+        const existing = this.tunnelManager.getManagedTunnel(config.configId);
+        console.log(existing);
+        if (!existing.tunnelConfig) throw new Error("Invalid tunnel state before configuration update");
+        this.tunnelManager.updateConfig(config).catch((err) => {
+          logger.error("No-wait updateConfigV2 failed", { configId: config.configId, err: String(err) });
+        });
+        return this.buildPendingTunnelResponseV2(existing.tunnelid, existing.tunnelConfig, config, config.configId, existing.tunnelName, existing.serve);
+      }
       const tunnel = await this.tunnelManager.updateConfig(config);
       if (!tunnel.instance || !tunnel.tunnelConfig)
         throw new Error("Invalid tunnel state after configuration update");
@@ -1947,8 +2023,16 @@ var TunnelOperations = class {
       return this.error(ErrorCode.TunnelNotFound, err, "Failed to get tunnel information");
     }
   }
-  async handleRestart(tunnelid) {
+  async handleRestart(tunnelid, noWait = false) {
     try {
+      if (noWait) {
+        const managed2 = this.tunnelManager.getManagedTunnel("", tunnelid);
+        if (!managed2?.tunnelConfig) throw new Error(`Tunnel config for ID "${tunnelid}" not found`);
+        this.tunnelManager.restartTunnel(tunnelid).catch((err) => {
+          logger.error("No-wait restartTunnel failed", { tunnelid, err: String(err) });
+        });
+        return this.buildPendingTunnelResponse(tunnelid, managed2.tunnelConfig, managed2.configId, managed2.tunnelName, managed2.serve);
+      }
       await this.tunnelManager.restartTunnel(tunnelid);
       const managed = this.tunnelManager.getManagedTunnel("", tunnelid);
       if (!managed?.tunnelConfig) throw new Error(`Tunnel config for ID "${tunnelid}" not found`);
@@ -2217,7 +2301,7 @@ var WebSocketCommandHandler = class {
       const dc = StartSchema.parse(raw);
       queuedConfig = dc.tunnelConfig;
       remoteManagementWebSocketPrinter.queueStart(dc.tunnelConfig);
-      const result = await this.tunnelHandler.handleStart(dc.tunnelConfig);
+      const result = await this.tunnelHandler.handleStart(dc.tunnelConfig, true);
       remoteManagementWebSocketPrinter.handleStartResult(dc.tunnelConfig, result);
       return this.wrapResponse(result, req);
     } catch (e) {
@@ -2238,7 +2322,7 @@ var WebSocketCommandHandler = class {
       const dc = StartV2Schema.parse(raw);
       queuedConfig = dc.tunnelConfig;
       remoteManagementWebSocketPrinter.queueStart(dc.tunnelConfig);
-      const result = await this.tunnelHandler.handleStartV2(dc.tunnelConfig);
+      const result = await this.tunnelHandler.handleStartV2(dc.tunnelConfig, true);
       remoteManagementWebSocketPrinter.handleStartResult(dc.tunnelConfig, result);
       return this.wrapResponse(result, req);
     } catch (e) {
@@ -2287,7 +2371,7 @@ var WebSocketCommandHandler = class {
     try {
       const dc = RestartSchema.parse(raw);
       remoteManagementWebSocketPrinter.printRestartRequested(dc.tunnelID);
-      const result = await this.tunnelHandler.handleRestart(dc.tunnelID);
+      const result = await this.tunnelHandler.handleRestart(dc.tunnelID, true);
       remoteManagementWebSocketPrinter.handleRestartResult(dc.tunnelID, result);
       return this.wrapResponse(result, req);
     } catch (e) {
@@ -2302,7 +2386,7 @@ var WebSocketCommandHandler = class {
   async handleUpdateConfigReq(req, raw) {
     try {
       const dc = UpdateConfigSchema.parse(raw);
-      const result = await this.tunnelHandler.handleUpdateConfig(dc.tunnelConfig);
+      const result = await this.tunnelHandler.handleUpdateConfig(dc.tunnelConfig, true);
       return this.wrapResponse(result, req);
     } catch (e) {
       if (e instanceof z2.ZodError) {
@@ -2316,7 +2400,7 @@ var WebSocketCommandHandler = class {
   async handleUpdateConfigV2Req(req, raw) {
     try {
       const dc = UpdateConfigV2Schema.parse(raw);
-      const result = await this.tunnelHandler.handleUpdateConfigV2(dc.tunnelConfig);
+      const result = await this.tunnelHandler.handleUpdateConfigV2(dc.tunnelConfig, true);
       return this.wrapResponse(result, req);
     } catch (e) {
       if (e instanceof z2.ZodError) {
@@ -2482,6 +2566,12 @@ function handleConnectionStatusMessage(firstMessage) {
 // src/remote_management/remoteManagement.ts
 var RECONNECT_SLEEP_MS = 5e3;
 var PING_INTERVAL_MS = 3e4;
+var RemoteManagementUnauthorizedError = class extends Error {
+  constructor() {
+    super("Unauthorized. Please enter a valid token.");
+    this.name = "RemoteManagementUnauthorizedError";
+  }
+};
 var _remoteManagementState = {
   status: "NOT_RUNNING",
   errorMessage: ""
@@ -2546,9 +2636,14 @@ async function initiateRemoteManagement(remoteManagementConfig) {
     try {
       await handleWebSocketConnection(wsUrl, wsHost, remoteManagementConfig.apiKey);
     } catch (error) {
+      if (error instanceof RemoteManagementUnauthorizedError) {
+        throw error;
+      }
       logger.warn("Remote management connection error", { error: String(error) });
     }
-    if (_stopRequested) break;
+    if (_stopRequested) {
+      break;
+    }
     printer_default.warn(`Remote management disconnected. Reconnecting in ${RECONNECT_SLEEP_MS / 1e3} seconds...`);
     logger.info("Reconnecting to remote management after disconnect");
     await sleep(RECONNECT_SLEEP_MS);
@@ -2557,22 +2652,34 @@ async function initiateRemoteManagement(remoteManagementConfig) {
   logger.info("Remote management stopped.");
   return getRemoteManagementState();
 }
-async function handleWebSocketConnection(wsUrl, wsHost, token) {
-  return new Promise((resolve) => {
+async function handleWebSocketConnection(wsUrl, wsHost, token, onOpenCallback) {
+  return new Promise((resolve, reject) => {
     const ws = new WebSocket(wsUrl, {
       headers: { Authorization: `Bearer ${token}` }
     });
     currentWs = ws;
     let heartbeat = null;
     let firstMessage = true;
-    const cleanup = () => {
-      if (heartbeat) clearInterval(heartbeat);
+    let settled = false;
+    const cleanup = (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (heartbeat) {
+        clearInterval(heartbeat);
+      }
       currentWs = null;
-      resolve();
+      if (err) {
+        reject(err);
+      } else {
+        resolve();
+      }
     };
     ws.once("open", () => {
       printer_default.success(`Connected to ${wsHost}`);
       setRemoteManagementState({ status: RemoteManagementStatus.Running, errorMessage: "" });
+      onOpenCallback?.();
       heartbeat = setInterval(() => {
         if (ws.readyState === WebSocket.OPEN) ws.ping();
       }, PING_INTERVAL_MS);
@@ -2600,13 +2707,14 @@ async function handleWebSocketConnection(wsUrl, wsHost, token) {
     ws.on("unexpected-response", (_, res) => {
       if (res.statusCode === 401) {
         setRemoteManagementState({ status: RemoteManagementStatus.NotRunning, errorMessage: `HTTP ${res.statusCode}` });
-        printer_default.error("Unauthorized. Please enter a valid token.");
         logger.error("Unauthorized (401) on remote management connect");
+        cleanup(new RemoteManagementUnauthorizedError());
         ws.close();
       } else {
         logger.warn("Unexpected HTTP response ", { statusCode: res.statusCode });
         printer_default.warn(`Unexpected HTTP ${res.statusCode}. Retrying...`);
         cleanup();
+        ws.close();
       }
     });
     ws.on("close", (code, reason) => {
@@ -2618,7 +2726,7 @@ async function handleWebSocketConnection(wsUrl, wsHost, token) {
     ws.on("error", (err) => {
       setRemoteManagementState({ status: RemoteManagementStatus.Error, errorMessage: err.message });
       logger.warn("WebSocket error", { error: err.message });
-      printer_default.error(err);
+      printer_default.warn(err.message);
       cleanup();
     });
   });
@@ -2648,6 +2756,58 @@ async function closeRemoteManagement(timeoutMs = 1e4) {
     return getRemoteManagementState();
   }
 }
+function startRemoteManagement(remoteManagementConfig) {
+  if (!remoteManagementConfig.apiKey || remoteManagementConfig.apiKey.trim().length === 0) {
+    return Promise.reject(new Error("Remote management token is required"));
+  }
+  const wsUrl = remoteManagementConfig.serverUrl;
+  const wsHost = extractHostname(wsUrl);
+  logger.info("Remote management mode enabled.");
+  _stopRequested = false;
+  return new Promise((resolve, reject) => {
+    let firstSettled = false;
+    const settleOnce = (err) => {
+      if (firstSettled) {
+        return;
+      }
+      firstSettled = true;
+      if (err) {
+        reject(err);
+      } else {
+        resolve(getRemoteManagementState());
+      }
+    };
+    const runLoop = async () => {
+      const sigintHandler = () => {
+        _stopRequested = true;
+      };
+      process.once("SIGINT", sigintHandler);
+      while (!_stopRequested) {
+        logger.info("Connecting to remote management", { wsUrl });
+        setRemoteManagementState({ status: RemoteManagementStatus.Connecting, errorMessage: "" });
+        try {
+          await handleWebSocketConnection(wsUrl, wsHost, remoteManagementConfig.apiKey, () => settleOnce());
+        } catch (error) {
+          if (error instanceof RemoteManagementUnauthorizedError) {
+            settleOnce(error);
+            process.removeListener("SIGINT", sigintHandler);
+            return;
+          }
+          settleOnce();
+          logger.warn("Remote management connection error", { error: String(error) });
+        }
+        if (_stopRequested) {
+          break;
+        }
+        logger.info("Reconnecting to remote management after disconnect");
+        await sleep(RECONNECT_SLEEP_MS);
+      }
+      process.removeListener("SIGINT", sigintHandler);
+      logger.info("Remote management stopped.");
+    };
+    runLoop().catch((err) => settleOnce(err instanceof Error ? err : new Error(String(err))));
+  });
+}
 function getRemoteManagementState() {
   return _remoteManagementState;
 }
@@ -2668,8 +2828,11 @@ export {
   TunnelErrorCodeType,
   TunnelWarningCode,
   TunnelOperations,
+  RemoteManagementUnauthorizedError,
+  buildRemoteManagementWsUrl,
   parseRemoteManagement,
   initiateRemoteManagement,
   closeRemoteManagement,
+  startRemoteManagement,
   getRemoteManagementState
 };