@molecule/api-code-sandbox-docker 1.1.5 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T23:29:06.286Z
+Generated: 2026-10-27T12:31:00.294Z
 -->
 
 # @molecule/api-code-sandbox-docker
@@ -81,6 +81,26 @@ interface DockerConfig {
   labelPrefix?: string
   /** Preview URL template. Use {port} placeholder. */
   previewUrlTemplate?: string
+  /**
+   * The interface published sandbox ports bind to on the daemon's host.
+   * Defaults to `127.0.0.1` (loopback — nothing outside the host reaches a
+   * sandbox port), or the `DOCKER_PUBLISH_HOST_IP` env var.
+   *
+   * The one knob that makes a REMOTE daemon (`host`/`DOCKER_HOST`) usable for
+   * hosting: the control plane's front proxies to the address `describe()`
+   * reports, and that address is this bind. A specific routable IP (the box's
+   * address on a network the front can reach) is the scoped choice; the
+   * wildcards `0.0.0.0`/`::` bind EVERY interface and expose every published
+   * port of every sandbox on that daemon to every network it touches, so in
+   * `NODE_ENV=production` they are refused unless `MOL_DOCKER_ALLOW_PUBLIC_BINDS=1`
+   * is set (honored with a loud warning). A wildcard bind on a remote daemon is
+   * reported as the daemon's own host.
+   *
+   * Exposure is the operator's contract either way: whatever address this
+   * names must be reachable by the front and FIREWALLED against everything
+   * else — binding a port is a deliberate exposure decision, not a default.
+   */
+  publishHostIp?: string
   /**
    * Docker repository holding sandbox TEMPLATES — one tag per template id.
    * Defaults to `molecule-sandbox-template` (or `SANDBOX_TEMPLATE_REPOSITORY`).
@@ -132,6 +152,8 @@ interface ProcessEnv {
   DOCKER_HOST?: string
   /** Docker network sandbox containers attach to (default `molecule-sandbox`, ICC-off). Overridden by `config.network`. [C1-1] */
   SANDBOX_DOCKER_NETWORK?: string
+  /** Interface published ports bind to on the daemon's host (default `127.0.0.1`, loopback-only). Overridden by `config.publishHostIp`. */
+  DOCKER_PUBLISH_HOST_IP?: string
   /** Docker repository holding sandbox templates (default `molecule-sandbox-template`). Overridden by `config.templateRepository`. */
   SANDBOX_TEMPLATE_REPOSITORY?: string
   /** Registry host for sharing templates across hosts. Overridden by `config.templateRegistry`. */
@@ -180,7 +202,7 @@ duplicate container. If `onRetry` returns non-null, that value is used and the
 operation is not re-issued.
 
 ```typescript
-function withTransientRetry(
+function withTransientRetry<T>(
   op: () => Promise<T>,
   opts: {
     label: string
@@ -276,6 +298,9 @@ proxy. When the plain-TCP endpoint comes from the ambient `DOCKER_HOST` env
 (not explicit config) and `NODE_ENV=production`, the provider REFUSES to
 connect — exec payloads would cross the network unencrypted — unless
 `MOL_DOCKER_ALLOW_PLAIN_TCP=1` is set, which is honored with a loud warning.
+Published ports bind loopback by default; a remote daemon used for hosting
+names a routable interface with `config.publishHostIp` / `DOCKER_PUBLISH_HOST_IP`
+(wildcard binds need `MOL_DOCKER_ALLOW_PUBLIC_BINDS=1` in production).
 Caller-supplied container ids are shape-validated (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
 so Docker hex ids, names, and fly-style `app:machine` ids pass) before they are
 interpolated into Docker API paths. The provider never pulls images, so `create()` fails with a no-such-image

package/dist/index.d.ts

@@ -21,6 +21,9 @@
  * (not explicit config) and `NODE_ENV=production`, the provider REFUSES to
  * connect — exec payloads would cross the network unencrypted — unless
  * `MOL_DOCKER_ALLOW_PLAIN_TCP=1` is set, which is honored with a loud warning.
+ * Published ports bind loopback by default; a remote daemon used for hosting
+ * names a routable interface with `config.publishHostIp` / `DOCKER_PUBLISH_HOST_IP`
+ * (wildcard binds need `MOL_DOCKER_ALLOW_PUBLIC_BINDS=1` in production).
  * Caller-supplied container ids are shape-validated (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
  * so Docker hex ids, names, and fly-style `app:machine` ids pass) before they are
  * interpolated into Docker API paths. The provider never pulls images, so `create()` fails with a no-such-image

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}

package/dist/index.js

@@ -21,6 +21,9 @@
  * (not explicit config) and `NODE_ENV=production`, the provider REFUSES to
  * connect — exec payloads would cross the network unencrypted — unless
  * `MOL_DOCKER_ALLOW_PLAIN_TCP=1` is set, which is honored with a loud warning.
+ * Published ports bind loopback by default; a remote daemon used for hosting
+ * names a routable interface with `config.publishHostIp` / `DOCKER_PUBLISH_HOST_IP`
+ * (wildcard binds need `MOL_DOCKER_ALLOW_PUBLIC_BINDS=1` in production).
  * Caller-supplied container ids are shape-validated (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
  * so Docker hex ids, names, and fly-style `app:machine` ids pass) before they are
  * interpolated into Docker API paths. The provider never pulls images, so `create()` fails with a no-such-image

package/dist/inspect.d.ts

@@ -30,6 +30,13 @@ export interface InspectContext {
     labelPrefix: string;
     warn?: (message: string, meta?: Record<string, unknown>) => void;
     debug?: (message: string, meta?: Record<string, unknown>) => void;
+    /**
+     * Where a port bound to EVERY interface is actually reachable, when that is
+     * somewhere other than this process's loopback — the host of a remote
+     * (`tcp://`) daemon. Unset for a local daemon, whose wildcard binds answer
+     * on loopback and nowhere the caller can name.
+     */
+    advertisedHost?: string;
 }
 /** Shape of the fields this module reads from `GET /containers/{id}/json`. */
 interface ContainerInspect {

package/dist/inspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../src/inspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAElB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,CAAA;IACtB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAChE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAClE;AASD,8EAA8E;AAC9E,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChD,eAAe,CAAC,EAAE;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAA;KACpF,CAAA;CACF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,gBAAgB,GAAG,iBAAiB,CA2B3F;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAYnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,cAAc,EACnB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAwB9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,UAAU,EAAE,CAAC,CAkCvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAqBf"}
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../src/inspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAElB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,CAAA;IACtB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAChE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACjE;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AASD,8EAA8E;AAC9E,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChD,eAAe,CAAC,EAAE;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAA;KACpF,CAAA;CACF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,gBAAgB,GAAG,iBAAiB,CAoC3F;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAYnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,cAAc,EACnB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAwB9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,UAAU,EAAE,CAAC,CAkCvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/inspect.js

@@ -53,7 +53,16 @@ export function toDescriptor(ctx, info) {
             const port = Number.parseInt(binding.HostPort ?? '', 10);
             if (!Number.isInteger(port) || port <= 0)
                 continue;
-            ports.push({ sandboxPort, host: binding.HostIp || '127.0.0.1', port });
+            // A bind on every interface has no single address of its own: it is
+            // reachable wherever the daemon's host is reachable, which the context
+            // names for a remote daemon and which is loopback for a local one.
+            const hostIp = binding.HostIp;
+            const bindAll = !hostIp || hostIp === '0.0.0.0' || hostIp === '::';
+            ports.push({
+                sandboxPort,
+                host: bindAll ? (ctx.advertisedHost ?? '127.0.0.1') : hostIp,
+                port,
+            });
         }
     }
     return {

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAcV,eAAe,EAOhB,MAAM,4BAA4B,CAAA;AAoBnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA4K9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ9D;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAg9CD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,KAAK,EAeV,eAAe,EAOhB,MAAM,4BAA4B,CAAA;AAoBnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA4K9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ9D;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AA0hDD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}

package/dist/provider.js

@@ -8,6 +8,7 @@
  */
 import { readFile, statfs } from 'fs/promises';
 import http from 'http';
+import net from 'net';
 import { freemem } from 'os';
 import { Readable } from 'stream';
 import { getLogger } from '@molecule/api-bond';
@@ -318,6 +319,20 @@ export async function withTransientRetry(op, opts) {
  */
 class DockerSandboxProvider {
     name = 'docker';
+    /**
+     * Containers this provider runs live until they are destroyed (optionally
+     * surviving crashes via `SandboxConfig.restartPolicy`) and every published
+     * port is host-mapped at an address `describe()` reports — the two things a
+     * long-lived hosting role needs, which is why this provider is selectable
+     * for it. A LOCAL daemon's default loopback bind is routable only from the
+     * control plane's own host, which is exactly what a co-located front needs;
+     * a remote daemon needs `publishHostIp` to name an address the front can
+     * reach.
+     */
+    hostingCapabilities = {
+        longLived: true,
+        routable: true,
+    };
     /** Resolved daemon endpoint (unix socket or TCP host:port); see {@link resolveDockerEndpoint}. */
     endpoint;
     baseImage;
@@ -353,6 +368,10 @@ class DockerSandboxProvider {
     endpointSafetyChecked = false;
     /** Whether the plain-TCP override warning has fired (once per provider). */
     plainTcpOverrideWarned = false;
+    /** Explicit publish bind from `config.publishHostIp`, if any; env is consulted at create time. */
+    configPublishHostIp;
+    /** Whether the wildcard-bind warning has fired (once per provider). */
+    publicBindOverrideWarned = false;
     constructor(config = {}) {
         const resolved = resolveDockerEndpoint(config);
         this.endpoint = resolved.endpoint;
@@ -363,6 +382,7 @@ class DockerSandboxProvider {
         this.defaultCpu = config.defaultCpu ?? 1;
         this.defaultMemoryMB = config.defaultMemoryMB ?? 1024;
         this.configNetwork = config.network;
+        this.configPublishHostIp = config.publishHostIp;
         this.configTemplateRepository = config.templateRepository;
         this.configTemplateRegistry = config.templateRegistry;
         this.configTemplateRegistryAuth = config.templateRegistryAuth;
@@ -404,8 +424,50 @@ class DockerSandboxProvider {
             labelPrefix: this.labelPrefix,
             warn: (message, meta) => logger.warn(message, meta),
             debug: (message, meta) => logger.debug(message, meta),
+            // A wildcard port bind on a REMOTE daemon is reachable at the daemon's
+            // own host, not at the control plane's loopback — that is the address a
+            // front needs. A local daemon leaves this unset, so a wildcard there
+            // still reports loopback.
+            advertisedHost: 'host' in this.endpoint ? this.endpoint.host : undefined,
         };
     }
+    /**
+     * Resolve the interface published ports bind to on the daemon's host.
+     * Precedence: `config.publishHostIp` (captured at construction) →
+     * `DOCKER_PUBLISH_HOST_IP` env (read here, at create time) → loopback.
+     *
+     * @returns the bind address for `HostConfig.PortBindings`.
+     * @throws {Error} when the value is not an IP address, or is a wildcard
+     *   (`0.0.0.0`/`::`) while `NODE_ENV=production` without
+     *   `MOL_DOCKER_ALLOW_PUBLIC_BINDS=1` — a wildcard publishes every port of
+     *   every sandbox on that daemon to every network it touches, and that is an
+     *   exposure someone must accept by name, never inherit by default.
+     */
+    resolvePublishHostIp() {
+        const raw = this.configPublishHostIp ?? process.env.DOCKER_PUBLISH_HOST_IP ?? '127.0.0.1';
+        const value = raw.trim();
+        if (net.isIP(value) === 0) {
+            throw new Error(`DOCKER_PUBLISH_HOST_IP/publishHostIp must be an IP address (got ${JSON.stringify(raw)}); ` +
+                'a hostname would need Docker to resolve it at bind time, when it may answer differently.');
+        }
+        const wildcard = value === '0.0.0.0' || value === '::';
+        if (wildcard && process.env.NODE_ENV === 'production') {
+            const override = process.env.MOL_DOCKER_ALLOW_PUBLIC_BINDS;
+            if (override !== '1' && override !== 'true') {
+                throw new Error('Publishing sandbox ports on every interface (0.0.0.0/::) while NODE_ENV=production — ' +
+                    'refusing. Bind a specific IP the front can reach, or set ' +
+                    'MOL_DOCKER_ALLOW_PUBLIC_BINDS=1 to explicitly accept exposing every published port ' +
+                    'of every sandbox on this daemon.');
+            }
+            if (!this.publicBindOverrideWarned) {
+                this.publicBindOverrideWarned = true;
+                logger.warn('Sandbox ports bind EVERY interface (MOL_DOCKER_ALLOW_PUBLIC_BINDS accepted) — ' +
+                    'every published port of every sandbox on this daemon is reachable from every network ' +
+                    'it touches. Firewall the host so only the front can dial them.');
+            }
+        }
+        return value;
+    }
     /**
      * Resolve the Docker network to attach containers to. Precedence:
      * `config.network` (captured at construction) → `SANDBOX_DOCKER_NETWORK` env
@@ -489,6 +551,7 @@ class DockerSandboxProvider {
             image = template.ref;
         }
         const publishPorts = resolvePublishPorts(config.publishPorts);
+        const publishHostIp = this.resolvePublishHostIp();
         const env = Object.entries(config.env ?? {}).map(([k, v]) => `${k}=${v}`);
         const labels = {
             [`${this.labelPrefix}.projectId`]: config.projectId,
@@ -523,10 +586,13 @@ class DockerSandboxProvider {
             // bridge. Egress filtering must be enforced host-side, not in a tenant-rooted
             // container.
             CapAdd: ['CHOWN', 'SETGID', 'SETUID'],
-            // Bind ports to localhost only — prevents external access. Which ports is
-            // the caller's business (`config.publishPorts`); the historical
-            // API + Vite pair is the default so existing callers are unaffected.
-            PortBindings: Object.fromEntries(publishPorts.map((port) => [`${port}/tcp`, [{ HostIp: '127.0.0.1', HostPort: '' }]])),
+            // Bind published ports to a chosen interface — loopback by default, so
+            // nothing outside the host reaches a sandbox port. Which ports is the
+            // caller's business (`config.publishPorts`); the historical API + Vite
+            // pair is the default so existing callers are unaffected. The interface
+            // is `resolvePublishHostIp()`'s: loopback until an operator names an
+            // address their front can reach (a remote-hosting daemon).
+            PortBindings: Object.fromEntries(publishPorts.map((port) => [`${port}/tcp`, [{ HostIp: publishHostIp, HostPort: '' }]])),
             Tmpfs: { '/tmp': 'rw,noexec,nosuid,size=256m' },
             ReadonlyPaths: [
                 '/proc/asound',

package/dist/types.d.ts

@@ -42,6 +42,26 @@ export interface DockerConfig {
     labelPrefix?: string;
     /** Preview URL template. Use {port} placeholder. */
     previewUrlTemplate?: string;
+    /**
+     * The interface published sandbox ports bind to on the daemon's host.
+     * Defaults to `127.0.0.1` (loopback — nothing outside the host reaches a
+     * sandbox port), or the `DOCKER_PUBLISH_HOST_IP` env var.
+     *
+     * The one knob that makes a REMOTE daemon (`host`/`DOCKER_HOST`) usable for
+     * hosting: the control plane's front proxies to the address `describe()`
+     * reports, and that address is this bind. A specific routable IP (the box's
+     * address on a network the front can reach) is the scoped choice; the
+     * wildcards `0.0.0.0`/`::` bind EVERY interface and expose every published
+     * port of every sandbox on that daemon to every network it touches, so in
+     * `NODE_ENV=production` they are refused unless `MOL_DOCKER_ALLOW_PUBLIC_BINDS=1`
+     * is set (honored with a loud warning). A wildcard bind on a remote daemon is
+     * reported as the daemon's own host.
+     *
+     * Exposure is the operator's contract either way: whatever address this
+     * names must be reachable by the front and FIREWALLED against everything
+     * else — binding a port is a deliberate exposure decision, not a default.
+     */
+    publishHostIp?: string;
     /**
      * Docker repository holding sandbox TEMPLATES — one tag per template id.
      * Defaults to `molecule-sandbox-template` (or `SANDBOX_TEMPLATE_REPOSITORY`).
@@ -88,6 +108,8 @@ export interface ProcessEnv {
     DOCKER_HOST?: string;
     /** Docker network sandbox containers attach to (default `molecule-sandbox`, ICC-off). Overridden by `config.network`. [C1-1] */
     SANDBOX_DOCKER_NETWORK?: string;
+    /** Interface published ports bind to on the daemon's host (default `127.0.0.1`, loopback-only). Overridden by `config.publishHostIp`. */
+    DOCKER_PUBLISH_HOST_IP?: string;
     /** Docker repository holding sandbox templates (default `molecule-sandbox-template`). Overridden by `config.templateRepository`. */
     SANDBOX_TEMPLATE_REPOSITORY?: string;
     /** Registry host for sharing templates across hosts. Overridden by `config.templateRegistry`. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sHAAsH;IACtH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0IAA0I;IAC1I,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kHAAkH;IAClH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,wJAAwJ;IACxJ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gIAAgI;IAChI,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,oIAAoI;IACpI,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,iGAAiG;IACjG,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,mHAAmH;IACnH,8BAA8B,CAAC,EAAE,MAAM,CAAA;CACxC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sHAAsH;IACtH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0IAA0I;IAC1I,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kHAAkH;IAClH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,wJAAwJ;IACxJ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gIAAgI;IAChI,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,yIAAyI;IACzI,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,oIAAoI;IACpI,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,iGAAiG;IACjG,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,mHAAmH;IACnH,8BAA8B,CAAC,EAAE,MAAM,CAAA;CACxC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-docker",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Docker-based code sandbox container provider",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@molecule/api-bond": "1.0.3",
-    "@molecule/api-code-sandbox": "1.4.1",
+    "@molecule/api-bond": "1.0.4",
+    "@molecule/api-code-sandbox": "1.5.0",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "4.1.12"