@agimon-ai/doompi-sandbox 0.0.1-alpha.101

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# @agimon-ai/doompi-sandbox
+
+Run the DoomPi agent, extensions, and tools in a container while keeping the terminal on the host.
+
+Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi). You can also install it directly in [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
+
+## Requirements
+
+- Node.js 22.19.0 or newer
+- `@earendil-works/pi-coding-agent` 0.85.0
+- One of `docker`, `podman`, `nerdctl`, or `finch` on the host for sandboxed launches
+
+## Install
+
+```bash
+pi install npm:@agimon-ai/doompi-sandbox
+```
+
+Pi loads the extension after installation. Container launches use the DoomPi launcher and require
+this package in the selected major mode's layers, as shown below.
+
+## Enable the sandbox
+
+This layer is still in development, so `doompi init` does not add it to any mode. Opt in by hand:
+name it as a layer in `.doom/modes.yaml`, then list that layer on the mode you want it in.
+
+```yaml
+layers:
+  sandbox:
+    packages:
+      - '@agimon-ai/doompi-sandbox'
+
+majorMode:
+  copilot:
+    description: General-purpose coding mode.
+    layers: [team, ask-user, task, sandbox]
+```
+
+`--sandbox` resolves the provider from the selected mode, so a mode without this layer reports that
+no sandbox harness is available and refuses to launch rather than running unsandboxed.
+
+## Sandboxed launches
+
+With this layer in the selected major mode, `doompi --sandbox` moves the whole session into a
+disposable Linux container instead of running Pi on the host:
+
+1. The harness resolves this package's `./sandbox-harness` export and delegates the launch.
+2. The layer detects the first available engine in the order `docker`, `podman`, `nerdctl`,
+   `finch` (override with `DOOMPI_SANDBOX_ENGINE`), and builds a
+   `doompi-sandbox:v<version>-<digest>` image when that tag is not cached. The digest covers the
+   image definition and bridge source. The image installs DoomPi from the registry rather than
+   copying the host's platform-specific packages.
+3. It starts `docker run --rm` with the repository bind-mounted at its host path, an isolated
+   home volume, and a volume shadowing the repository's `.pi` package store. Inside, the
+   `doompi` launcher replays the same major mode, domains, profile, and Pi arguments.
+
+The terminal stays attached, so the session looks like a host launch while bash, file edits,
+extensions, MCP servers, and skills all execute inside the container. `DOOMPI_SANDBOX=1` marks
+every sandboxed process; nesting is refused.
+
+Only an allowlisted environment enters the container: terminal and locale variables, proxy
+settings, and `DOOMPI_PRESET`. Everything else a shell accumulates stays on the host.
+
+## Engine and runtime selection
+
+The harness invokes each supported engine with Docker-compatible arguments. The engine and its
+VM, if any, must already be running on the host.
+
+`DOOMPI_SANDBOX_RUN_FLAGS` passes extra options straight to the engine, which is how you select a
+different isolation runtime without the layer having to know about it:
+
+```bash
+DOOMPI_SANDBOX_RUN_FLAGS=--runtime=runsc doompi --sandbox
+```
+
+Options must be self-contained (`--flag` or `--flag=value`). A separated value such as
+`--runtime runsc` is refused, because a bare word cannot be told apart from an image name and
+would silently launch a different container.
+
+Alternative isolation runtimes such as Kata or Firecracker are not verified here. Check their
+mount and broker-transport support before relying on them.
+
+## Workspace dev containers
+
+A repository with a `.devcontainer/devcontainer.json` (or a root `.devcontainer.json`) uses that
+container instead of the built-in image, because a workspace that describes its own container is
+describing the toolchain its agent needs. The Dev Containers CLI brings it up, so the file decides
+the image, features, mounts, run arguments and lifecycle hooks in full.
+
+**Workspace devcontainer configuration is trusted executable input, not an isolation policy.**
+It can mount your home directory or the Docker socket and run lifecycle hooks. The launch warns
+about this mode. Set `DOOMPI_SANDBOX_DEVCONTAINER=0` to ignore the file and use the built-in image.
+
+What still applies: the environment allowlist and the credential broker. The container receives the
+session token rather than any real key, and reaches the broker over the host gateway.
+
+Notes on this mode:
+
+- DoomPi is installed into the container on first use with `npm install -g`, since a project's
+  container has no reason to carry it. The CLI reuses the container, so that cost is paid once for
+  its lifetime. A container without `npm` is reported rather than silently degraded.
+- The session attaches through the engine rather than `devcontainer exec`, which allocates no
+  terminal and would break the full-screen TUI.
+- OAuth callback ports cannot be published into a container this layer did not create, so `/login`
+  needs the ports declared as `appPort` in the devcontainer configuration.
+
+## Signing in from inside the sandbox
+
+Subscription logins are not brokered, so `/login` runs inside the container. Two things make its
+browser callback reachable:
+
+- The launch publishes Pi's fixed callback ports back onto host loopback: 1455 (OpenAI Codex),
+  1456 (Radius) and 53692 (Anthropic).
+- `PI_OAUTH_CALLBACK_HOST=0.0.0.0` makes the in-container server bind every interface. A published
+  port reaches the container's external interface, never its loopback, so Pi's default bind would
+  refuse the connection. The redirect the provider sees is unchanged, still `localhost:<port>`.
+
+Credentials land in the per-repository home volume, so a login survives later runs against the
+same repository.
+
+Ports already held by another process are skipped rather than failing the launch, and the run says
+so. A second concurrent sandbox therefore starts normally but cannot complete a login. Providers
+that bind an ephemeral callback port instead of a fixed one, OpenRouter among them, cannot be
+published ahead of the flow and are not covered.
+
+## Terminal behavior
+
+The container runs Pi's TUI directly with inherited stdio: `-i` is always passed and `-t` is added
+when the host has a terminal. The harness does not proxy or re-render terminal frames.
+
+Host integrations are the exception, because the process is not on your host:
+
+| Feature               | In a sandboxed session                                                       |
+| --------------------- | ---------------------------------------------------------------------------- |
+| External editor       | Works. `nano` is installed and Pi falls back to it, editing the mounted file |
+| Opening a browser     | Not available; Pi prints the URL, which is how OAuth login proceeds          |
+| Clipboard integration | Not available; your terminal's own copy and paste still work                 |
+| Desktop notifications | Not available                                                                |
+
+A host `EDITOR` or `VISUAL` is deliberately not forwarded. Those commonly name a desktop
+application, which would resolve to a binary the container does not have and would fail instead of
+falling back to the editor that is there.
+
+## Provider credential broker
+
+For supported providers with a host API key, the credential broker:
+
+1. Starts a broker on the host and grants the container exactly one route to it.
+2. Replaces the credential variable with a random per-session token.
+3. Redirects the provider's base URL at a loopback bridge inside the container, which forwards
+   raw bytes to the broker.
+
+How the container reaches the broker depends on the engine:
+
+| Host                          | Transport                                   | Why                                                                                |
+| ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Linux                         | Unix socket, bind-mounted, owner-only       | Container and host share a kernel, so no port is needed                            |
+| macOS, Windows, any VM engine | Loopback TCP through `host.docker.internal` | A container in a virtual machine cannot connect to a mounted host socket (ENOTSUP) |
+
+On the TCP path the broker binds `127.0.0.1` on an ephemeral port, so it is never exposed beyond
+the host, and the launch passes `--add-host` so the gateway name resolves on every engine. Another
+local process could reach that port, and the session token is what stops it being useful.
+
+The broker validates the token, swaps in the real key, and streams the provider response back.
+Credentials for providers it cannot carry are withheld from the container rather than passed
+through. Turn the whole mechanism off with `DOOMPI_SANDBOX_BROKER=0`.
+
+## In-session command
+
+```text
+/doom-sandbox
+```
+
+Reports whether the current session runs inside the sandbox container or directly on the host.
+
+## Current limits
+
+- The broker carries a curated provider list. OAuth subscription logins are not brokered, so they
+  are performed inside the sandbox and stored in that container's home volume.
+- A host `*_BASE_URL` override is dropped rather than used as the broker's upstream.
+- Compositions that declare local workspace packages cannot load their platform-specific
+  dependencies inside the Linux container; use registry-installed layers for sandboxed work.
+- `dpi --sandbox` runs the harness rather than the synchronized fast path. That path loads Pi
+  in-process against synchronized settings, and a fresh container has none to load, so the
+  session is composed from the repository the way a first run is.
+- Container network access follows the engine's defaults and is not restricted yet.
+- Mounted repositories are writable. Containers do not protect those files from agent edits,
+  and the container engine remains part of the trusted base.
+
+## Public API
+
+```ts
+import { DefaultSandboxExtensionService, activateSandboxExtension } from '@agimon-ai/doompi-sandbox';
+import { launchSandbox } from '@agimon-ai/doompi-sandbox/sandbox-harness';
+```
+
+The Pi host entry is also available at:
+
+```text
+@agimon-ai/doompi-sandbox/extensions/pi
+```
+
+The service layer is host-neutral. `/extensions/pi` registers the in-session command;
+`/sandbox-harness` owns launcher provisioning. The separate `/cockpit-harness` export supports
+the web cockpit's container lifecycle and credential broker.
+
+## Development
+
+Run from this package directory in the workspace:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+pnpm exec vibe-lint check .
+npm pack --dry-run
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
+
+## License
+
+MIT

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/doompi-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,gDAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/doompi-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/brokerHost-BeGtmnK8.mjs

@@ -0,0 +1,302 @@
+import path from "node:path";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import http from "node:http";
+import https from "node:https";
+//#region src/services/brokerRoutes/index.ts
+/**
+* Providers the broker can terminate, mirroring Pi's own provider data.
+*
+* Curated rather than derived: Pi keeps base URLs in package-internal JSON that
+* carries no stability promise. A provider missing here is simply not brokered,
+* and its credential stays on the host.
+*/
+const ROUTES = [
+	{
+		provider: "anthropic",
+		upstream: "https://api.anthropic.com",
+		hostKeyEnv: ["ANTHROPIC_API_KEY"]
+	},
+	{
+		provider: "openai",
+		upstream: "https://api.openai.com/v1",
+		hostKeyEnv: ["OPENAI_API_KEY"]
+	},
+	{
+		provider: "google",
+		upstream: "https://generativelanguage.googleapis.com/v1beta",
+		hostKeyEnv: ["GEMINI_API_KEY"]
+	},
+	{
+		provider: "groq",
+		upstream: "https://api.groq.com/openai/v1",
+		hostKeyEnv: ["GROQ_API_KEY"]
+	},
+	{
+		provider: "xai",
+		upstream: "https://api.x.ai/v1",
+		hostKeyEnv: ["XAI_API_KEY"]
+	},
+	{
+		provider: "openrouter",
+		upstream: "https://openrouter.ai/api/v1",
+		hostKeyEnv: ["OPENROUTER_API_KEY"]
+	},
+	{
+		provider: "deepseek",
+		upstream: "https://api.deepseek.com",
+		hostKeyEnv: ["DEEPSEEK_API_KEY"]
+	},
+	{
+		provider: "mistral",
+		upstream: "https://api.mistral.ai",
+		hostKeyEnv: ["MISTRAL_API_KEY"]
+	},
+	{
+		provider: "together",
+		upstream: "https://api.together.ai/v1",
+		hostKeyEnv: ["TOGETHER_API_KEY"]
+	},
+	{
+		provider: "cerebras",
+		upstream: "https://api.cerebras.ai/v1",
+		hostKeyEnv: ["CEREBRAS_API_KEY"]
+	},
+	{
+		provider: "moonshotai",
+		upstream: "https://api.moonshot.ai/v1",
+		hostKeyEnv: ["MOONSHOT_API_KEY"]
+	},
+	{
+		provider: "zai",
+		upstream: "https://api.z.ai/api/coding/paas/v4",
+		hostKeyEnv: ["ZAI_API_KEY"]
+	}
+];
+/** Selects the providers this host can actually broker for a session. */
+function resolveBrokeredCredentials(environment) {
+	const resolved = [];
+	for (const route of ROUTES) for (const envName of route.hostKeyEnv) {
+		const value = environment[envName]?.trim();
+		if (value) {
+			resolved.push({
+				route,
+				envName,
+				value
+			});
+			break;
+		}
+	}
+	return resolved;
+}
+//#endregion
+//#region src/services/brokerServer/index.ts
+/** Headers a provider SDK may carry its credential in. */
+const CREDENTIAL_HEADERS = [
+	"x-api-key",
+	"authorization",
+	"x-goog-api-key"
+];
+/** Query parameter some Google clients use instead of a header. */
+const CREDENTIAL_QUERY = "key";
+const BEARER_PREFIX = "bearer ";
+/** Connection-scoped headers that must not cross to the upstream request. */
+const HOP_BY_HOP = /* @__PURE__ */ new Set([
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade",
+	"host",
+	"content-length"
+]);
+const PATH_PATTERN = /^\/([^/?]+)(.*)$/;
+function matchesToken(candidate, token) {
+	const left = Buffer.from(candidate);
+	const right = Buffer.from(token);
+	return left.length === right.length && timingSafeEqual(left, right);
+}
+function credentialValue(headerValue) {
+	return headerValue.toLowerCase().startsWith(BEARER_PREFIX) ? headerValue.slice(7) : headerValue;
+}
+function withCredential(headerValue, realKey) {
+	return headerValue.toLowerCase().startsWith(BEARER_PREFIX) ? `Bearer ${realKey}` : realKey;
+}
+/**
+* Rewrites the request's credential, proving the caller holds the session token.
+*
+* Which header carries the key differs per provider SDK, so every candidate is
+* checked rather than assumed. Returns undefined when nothing presented the
+* token, which is what makes an unauthenticated caller indistinguishable from a
+* misrouted one.
+*/
+function swapCredential(headers, search, token, realKey) {
+	const forwarded = {};
+	let authenticated = false;
+	for (const [name, value] of Object.entries(headers)) {
+		if (value === void 0 || HOP_BY_HOP.has(name)) continue;
+		const single = Array.isArray(value) ? value[0] : value;
+		if (CREDENTIAL_HEADERS.includes(name) && single !== void 0) {
+			if (!matchesToken(credentialValue(single), token)) return void 0;
+			forwarded[name] = withCredential(single, realKey);
+			authenticated = true;
+			continue;
+		}
+		forwarded[name] = value;
+	}
+	const queryKey = search.get(CREDENTIAL_QUERY);
+	if (queryKey !== null) {
+		if (!matchesToken(queryKey, token)) return void 0;
+		search.set(CREDENTIAL_QUERY, realKey);
+		authenticated = true;
+	}
+	return authenticated ? forwarded : void 0;
+}
+function reject(response, status, message) {
+	response.writeHead(status, { "content-type": "application/json" });
+	response.end(JSON.stringify({ error: {
+		type: "doompi_broker",
+		message
+	} }));
+}
+/**
+* Terminates provider calls from a sandboxed session on the host.
+*
+* The container never holds a real credential: it presents the session token,
+* and only a request that proves possession of it is forwarded upstream with
+* the host's key attached. Bodies stream in both directions so token-by-token
+* responses are not buffered.
+*/
+function createBrokerServer(options) {
+	const requestUpstream = options.requestUpstream ?? https.request;
+	return http.createServer((request, response) => {
+		const match = PATH_PATTERN.exec(request.url ?? "");
+		const provider = match?.[1];
+		const credential = provider ? options.credentials.get(provider) : void 0;
+		if (!match || !credential) {
+			options.onDenied?.(`unroutable provider path ${request.url ?? ""}`);
+			reject(response, 404, "Unknown provider for this sandbox session.");
+			return;
+		}
+		const target = new URL(`${credential.route.upstream}${match[2] || ""}`);
+		const headers = swapCredential(request.headers, target.searchParams, options.token, credential.value);
+		if (!headers) {
+			options.onDenied?.(`missing or invalid session token for ${credential.route.provider}`);
+			reject(response, 401, "This sandbox session did not present its broker token.");
+			return;
+		}
+		const upstream = requestUpstream(target, {
+			method: request.method,
+			headers: {
+				...headers,
+				host: target.host
+			}
+		}, (upstreamResponse) => {
+			response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
+			upstreamResponse.pipe(response);
+		});
+		upstream.on("error", (error) => {
+			options.onDenied?.(`upstream ${credential.route.provider} failed: ${error.message}`);
+			if (!response.headersSent) reject(response, 502, "The provider could not be reached from the host.");
+			else response.destroy();
+		});
+		request.on("aborted", () => upstream.destroy());
+		request.pipe(upstream);
+	});
+}
+//#endregion
+//#region src/services/brokerHost/index.ts
+const SOCKET_DIRECTORY_PREFIX = "doompi-broker-";
+const SOCKET_FILE_NAME = "broker.sock";
+const OWNER_ONLY_DIRECTORY = 448;
+const TOKEN_BYTES = 32;
+const LOOPBACK = "127.0.0.1";
+const LINUX_PLATFORM = "linux";
+const EPHEMERAL_PORT = 0;
+/**
+* Starts the host-side provider broker for one sandboxed session.
+*
+* Answers undefined when the host holds no brokerable credential, which keeps
+* a session that authenticates some other way on the unbrokered path instead
+* of failing it.
+*/
+async function startBroker(options) {
+	const resolved = resolveBrokeredCredentials(options.environment);
+	if (resolved.length === 0) return void 0;
+	const token = randomBytes(TOKEN_BYTES).toString("base64url");
+	const server = createBrokerServer({
+		credentials: new Map(resolved.map((credential) => [credential.route.provider, credential])),
+		token,
+		onDenied: options.onDenied
+	});
+	const { endpoint, dispose } = (options.platform ?? process.platform) === LINUX_PLATFORM && options.forceLoopback !== true ? await listenOnSocket(server, options.socketDirectory) : await listenOnLoopback(server);
+	return {
+		endpoint,
+		token,
+		providers: resolved.map((credential) => credential.route.provider),
+		withheldEnv: resolved.map((credential) => credential.envName),
+		stop: () => stopBroker(server, dispose)
+	};
+}
+/**
+* Native Linux shares a kernel with the container, so a bind-mounted socket
+* needs no port and is reachable as an ordinary file.
+*/
+async function listenOnSocket(server, fixedDirectory) {
+	const socketDirectory = fixedDirectory ?? fs.mkdtempSync(path.join(os.tmpdir(), SOCKET_DIRECTORY_PREFIX));
+	fs.mkdirSync(socketDirectory, { recursive: true });
+	fs.chmodSync(socketDirectory, OWNER_ONLY_DIRECTORY);
+	const socketPath = path.join(socketDirectory, SOCKET_FILE_NAME);
+	fs.rmSync(socketPath, { force: true });
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(socketPath, () => resolve());
+	});
+	return {
+		endpoint: {
+			transport: "unix",
+			socketDirectory
+		},
+		dispose: () => fixedDirectory ? fs.rmSync(socketPath, { force: true }) : fs.rmSync(socketDirectory, {
+			recursive: true,
+			force: true
+		})
+	};
+}
+/**
+* Everywhere else the container runs in its own virtual machine, which cannot
+* connect to a host unix socket even when the file is shared through: the
+* connect fails with ENOTSUP. Loopback keeps the broker off the network while
+* still being reachable through the engine's host gateway, and the session
+* token is what stops another local process from using it.
+*/
+async function listenOnLoopback(server) {
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(EPHEMERAL_PORT, LOOPBACK, () => resolve());
+	});
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new Error("The broker did not report a listening port.");
+	return {
+		endpoint: {
+			transport: "tcp",
+			port: address.port
+		},
+		dispose: () => void 0
+	};
+}
+async function stopBroker(server, dispose) {
+	await new Promise((resolve) => {
+		server.close(() => resolve());
+		server.closeAllConnections();
+	});
+	dispose();
+}
+//#endregion
+export { startBroker as t };
+
+//# sourceMappingURL=brokerHost-BeGtmnK8.mjs.map