@namzu/sandbox 16.0.0 → 17.0.0

package/src/backends/docker/index.ts

@@ -14,14 +14,35 @@
  * Trust model:
  *  - Container is the trust boundary; everything inside is treated
  *    as untrusted code.
- *  - Worker only listens on loopback inside its own netns; the
- *    host adapter reaches it via Docker's port-forward.
- *  - Outbound network from the worker is restricted by host-side
- *    firewall config (see {@link DockerBackendConfig.network}) plus
- *    the egress proxy when one is configured (P3.2).
+ *  - Every call to the worker's control API carries the per-instance
+ *    `NAMZU_SANDBOX_TOKEN` this backend mints at create time and
+ *    injects into the container's environment; a worker the host did
+ *    not create must be provisioned with its own. The worker requires
+ *    it on every route but `/healthz`, and refuses to start at all if
+ *    it has none and is bound to anything routable.
+ *  - Outbound network from the worker is restricted by the network
+ *    it is attached to (see {@link DockerBackendConfig.network}) and,
+ *    for a host allowlist, by an egress proxy running as a sibling
+ *    container on that same network — the only way its traffic reaches
+ *    the internet, because the network is `--internal` and has no route
+ *    off it. The proxy is a container on that subnet like any other, so
+ *    it is not the sandbox's only reachable destination. The proxy
+ *    environment the sandbox is given directs traffic; the topology is
+ *    what confines it. See {@link assertNetworkCarriesThePolicy} and
+ *    #398.
+ *
+ * The credential above is what a previous version of this docblock
+ * claimed network placement alone provided. It said the worker "only
+ * listens on loopback inside its own netns", which is false — the worker
+ * binds every interface by default and has to, because a published
+ * container port forwards to the container's interface address rather
+ * than to its loopback, so a loopback-bound worker is unreachable through
+ * the port this backend publishes. The boundary was the network the
+ * container is attached to, and wanted a credential behind it.
  */
 
 import { spawn } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
 
 import {
 	type ContainerSandboxLayout,
@@ -46,12 +67,7 @@ import {
 	walkFilesViaExec,
 	withHint,
 } from '@namzu/sdk'
-import { EgressProxy } from '../../egress/index.js'
-import type {
-	BrokeredCredential,
-	EgressProxyOptions,
-	RunningEgressProxy,
-} from '../../egress/index.js'
+import type { BrokeredCredential } from '../../egress/index.js'
 
 import {
 	ContainerSandboxLayoutValidationError,
@@ -59,7 +75,11 @@ import {
 	type SandboxBackend,
 	type SandboxBackendOptions,
 } from '../../index.js'
-import { HttpWorkerClient } from '../http-worker-client.js'
+import {
+	HttpWorkerClient,
+	WORKER_UNAUTHORIZED_HINT,
+	workerAuthorization,
+} from '../http-worker-client.js'
 import {
 	OperationDeadline,
 	OperationDeadlineExpired,
@@ -189,6 +209,55 @@ export interface DockerBackendInternalConfig {
 	 */
 	readonly allowInwardFor?: readonly string[]
 
+	/**
+	 * Image the egress proxy runs as, when the policy needs one.
+	 *
+	 * A host allowlist (`static` or `resolver`) is enforced by a proxy, and
+	 * this backend no longer runs that proxy in its own process: it runs it as
+	 * a sibling container, dual-homed between the sandbox's `--internal`
+	 * network (where the sandbox can reach it, and nothing else) and an
+	 * ordinary bridge (where it reaches the internet). See
+	 * {@link renderEgressProxyRunArgs} for the argv and
+	 * `egress-proxy/Dockerfile` for the image to build.
+	 *
+	 * It is a second image rather than a reuse of `image` on purpose, and the
+	 * reason is deployment-shaped rather than hygienic: the sandbox image is a
+	 * host-supplied string that this backend cannot read, so there is no way to
+	 * know whether the image named there has the proxy module in it, and the
+	 * bind-mount alternative breaks exactly on the remote-daemon deployment
+	 * (`hostReachability: 'container-network'`) where the SDK's own filesystem
+	 * is not the daemon's.
+	 *
+	 * Unset, an allowlist policy is REFUSED at `create()` rather than
+	 * downgraded — the same rule the rest of this file applies to a policy it
+	 * cannot enforce. `deny-all` and `allow-all` need no image.
+	 */
+	readonly egressProxyImage?: string
+
+	/**
+	 * Network the egress proxy joins for its route to the internet. Default
+	 * `'bridge'`, docker's own default bridge.
+	 *
+	 * This is the proxy's second leg, and it exists because the internal
+	 * network the sandbox sits on has no route out by design. `'bridge'` is
+	 * the default because it always exists and always has NAT, which keeps a
+	 * host's first allowlist policy working without a second network to
+	 * create.
+	 *
+	 * **The default is also the one wart of this topology, and a host that
+	 * shares a docker daemon should know it.** The proxy listens on every
+	 * interface inside its own container, so any other container attached to
+	 * the same network reaches it too — and this proxy enforces its allowlist
+	 * for whoever asks and stamps brokered credentials on the requests it
+	 * forwards. On `'bridge'` that means every container on the host's default
+	 * bridge. Name a dedicated network here (one only this deployment's
+	 * containers join) to decide who that is. There is deliberately no switch
+	 * that narrows the listener instead: the container has no way to know
+	 * which of its own interfaces is which, and a listener bound to the wrong
+	 * one is a sandbox with no route out at all.
+	 */
+	readonly egressProxyUpstreamNetwork?: string
+
 	readonly network?: 'none' | 'bridge' | string
 	readonly readyPollIntervalMs?: number
 	readonly readyTimeoutMs?: number
@@ -229,6 +298,12 @@ export interface DockerBackendInternalConfig {
 	 * monitoring filters) via `docker ps --filter label=…`. Keys
 	 * containing `=` or empty names throw at spawn time — the docker
 	 * CLI accepts them but the resulting label split is ambiguous.
+	 *
+	 * They are applied to the egress proxy's container too, when one runs.
+	 * That is deliberate in both directions: a reaper that collects a
+	 * sandbox's containers should collect the proxy with them, and a proxy
+	 * left running by a sandbox that died is a container holding real
+	 * credentials with a route to the internet.
 	 */
 	readonly labels?: Readonly<Record<string, string>>
 }
@@ -285,6 +360,14 @@ export function buildDockerBackend(config: DockerBackendInternalConfig): Sandbox
  * just the way out. It now keeps the configured network, and
  * {@link assertNetworkCarriesThePolicy} is what makes that network a
  * boundary.
+ *
+ * Every policy that returns the configured network depends on that same
+ * assertion, which is why the two live side by side: this function says which
+ * network the container joins, and that one refuses the network if it cannot
+ * do what the policy asks of it (#398). An allowlist used to answer the
+ * configured network and get a proxy environment variable pointed at a
+ * host-side listener — enforcement by convention, which an uncooperative
+ * process simply ignores.
  */
 export function resolveNetwork(
 	configured: string,
@@ -305,7 +388,7 @@ export function resolveNetwork(
 			// reporting that it had been restricted.
 			if (hasProxy) return configured
 			throw new Error(
-				`The docker sandbox backend cannot enforce an egress policy of kind '${egress.kind}' without an egress proxy: it has nothing to filter hosts through. Construct the provider with one, or use 'deny-all' / 'allow-all'. Refusing rather than silently granting full network access.`,
+				`The docker sandbox backend cannot enforce an egress policy of kind '${egress.kind}' without an egress proxy: it has nothing to filter hosts through. Name the image it should run the proxy as (egressProxyImage — see packages/sandbox/egress-proxy/Dockerfile), or use 'deny-all' / 'allow-all'. Refusing rather than silently granting full network access.`,
 			)
 	}
 }
@@ -347,9 +430,9 @@ export function isInternalNetwork(inspectedInternalFlag: string): boolean {
 /**
  * Refuse a container whose network cannot do what was asked of it.
  *
- * Two requirements meet on the same object here, and both were previously
- * unstated — which is how the backend came to ship a default configuration
- * that could not create a sandbox at all:
+ * Three requirements meet on the same object here, and the first two were
+ * previously unstated — which is how the backend came to ship a default
+ * configuration that could not create a sandbox at all:
  *
  *  - **A published host port needs a route out.** Docker binds the port by
  *    NAT to the container's address, so a container with no address gets no
@@ -365,12 +448,31 @@ export function isInternalNetwork(inspectedInternalFlag: string): boolean {
  *    nothing. `deny-all` pointed at the default bridge would be full egress
  *    under a policy object claiming none — the "accepted and silently
  *    ignored" failure the rest of this file exists to refuse.
+ *  - **A host allowlist needs one too, for the same reason and with one
+ *    addition.** Until #398 the allowlist tier answered the configured
+ *    network and pointed the sandbox at a proxy running on the host's
+ *    loopback, and the only thing making traffic go through it was
+ *    `HTTP_PROXY`. That is a request, not a boundary: anything inside the
+ *    container that opens a socket directly reaches the network with the
+ *    allowlist unconsulted, and untrusted code is the caller least likely to
+ *    honour a convention. With the proxy as a sibling container on an
+ *    `--internal` network, the only way the sandbox's traffic reaches the
+ *    internet is that container, and it cannot change that because
+ *    `--cap-drop=ALL` took `NET_ADMIN` away (see {@link HARDENING_ARGS}). The
+ *    environment variables stay and now DIRECT traffic rather than permit it.
+ *    On a network that is not internal there is no such route to remove, and
+ *    the policy is back to being advisory — which is what this refuses.
  *
- * They are exact opposites, so `deny-all` over a published host port is
- * impossible rather than merely unsupported: no arrangement of docker
+ * The first two are exact opposites, so `deny-all` over a published host port
+ * is impossible rather than merely unsupported: no arrangement of docker
  * networking both denies all egress and lets the host reach the worker over
- * TCP. Closing that needs the control channel moved off TCP — see #398 —
- * and is not a flag this function could accept.
+ * TCP. Closing that needs the control channel moved off TCP — see #398 — and
+ * is not a flag this function could accept. The same opposition now reaches
+ * an allowlist policy, which is new: an allowlist on an internal network must
+ * be reached by container name, so a host that used a published port with a
+ * host allowlist has to move that consumer onto the internal network. That is
+ * a consequence of the boundary existing at all and not a gap in this
+ * function; the refusal below names the mode to move to.
  */
 export function assertNetworkCarriesThePolicy(
 	network: string,
@@ -391,29 +493,210 @@ export function assertNetworkCarriesThePolicy(
 			`The docker sandbox backend was asked for an egress policy of 'deny-all' on network '${network}', but that network is not internal, so the container can still reach the world. Create it with 'docker network create --internal ${network}' — an internal bridge denies egress in the kernel, rather than through an environment variable a workload may decline to read, while sibling containers still reach the worker by name. Refusing rather than reporting a boundary that is not there.`,
 		)
 	}
+
+	if (needsEgressProxy(egress) && !internal) {
+		throw new Error(
+			`The docker sandbox backend was asked for an egress policy of kind '${egress?.kind}' on network '${network}', but that network is not internal, so nothing stops the container from reaching the world directly and the allowlist would only be a proxy environment variable a workload may decline to read. Create the network with 'docker network create --internal ${network}': the sandbox then reaches the internet only through the egress proxy container, which is the boundary — and set hostReachability: 'container-network' to reach the worker by name on it, since a published host port needs a route out this network does not have. Refusing rather than reporting a boundary that is not there.`,
+		)
+	}
+}
+
+/**
+ * What the proxy container is told, as a value.
+ *
+ * The boundary's whole configuration. It is a value for the reason
+ * {@link resolveNetwork} is one: everything downstream of here needs a running
+ * Docker daemon, so a credential that failed to reach the boundary could only
+ * be caught by an operator noticing their requests arrive unauthenticated in
+ * production. A knob a host sets and the boundary never receives is the
+ * failure this shape exists to make testable.
+ *
+ * `parseProxyConfig` in `egress-proxy/server.mjs` refuses every shape in here
+ * it cannot read — and this function's own output is fed to that parser by
+ * `__tests__/hardening.test.ts`, so the two ends are pinned against each other
+ * rather than each against its own idea of the shape. A field renamed on one
+ * side alone fails a test rather than starting a boundary that enforces
+ * something nobody wrote.
+ */
+export interface EgressProxyContainerConfig {
+	readonly port: number
+	readonly allowedHosts: readonly string[]
+	readonly credentials: readonly BrokeredCredential[]
+	readonly allowInwardFor?: readonly string[]
+	/**
+	 * Names that denote the proxy itself, for its loop guard. The container's
+	 * own hostname is added to this by the entrypoint; this field carries the
+	 * network alias, which is the name the sandbox actually dials.
+	 */
+	readonly selfNames?: readonly string[]
 }
 
 /**
- * The options the boundary is built from, as a value.
+ * Build the proxy container's configuration.
  *
- * Extracted for the same reason {@link resolveNetwork} is: everything
- * downstream of here needs a running Docker daemon, so a policy that never
- * reached the proxy could only be caught by an operator noticing their
- * traffic denied in production. A knob a host sets and the boundary never
- * receives is the failure this shape exists to make testable.
+ * `allowedHosts` is already resolved here rather than passed as a policy, and
+ * that is the one behavioural difference this change carries into the
+ * boundary: the in-process proxy called the host's resolver per request, and
+ * the container cannot. A `resolver` policy that rotates is honoured at
+ * `create()` and again at every `setNetworkPolicy()` — the container has no
+ * channel back to the host's resolver, and a channel the container CAN reach
+ * is one the sandbox can reach too, which would let the sandbox ask for its
+ * own allowlist to be widened. See `docs/sdk/sandbox-egress.md`.
  */
-export function egressProxyOptions(
+export function egressProxyContainerConfig(
 	config: Pick<DockerBackendInternalConfig, 'brokeredCredentials' | 'allowInwardFor'>,
-	policy: EgressPolicy,
-): EgressProxyOptions {
+	allowedHosts: readonly string[],
+	port: number,
+): EgressProxyContainerConfig {
 	return {
-		// Re-resolved per request rather than captured once, so a `resolver`
-		// policy that rotates is honoured and `setNetworkPolicy` can swap it
-		// on a live sandbox.
-		allowedHosts: () => resolveAllowedHosts(policy),
+		port,
+		allowedHosts,
 		credentials: config.brokeredCredentials ?? [],
 		...(config.allowInwardFor ? { allowInwardFor: config.allowInwardFor } : {}),
+		selfNames: [PROXY_HOST_ALIAS],
+	}
+}
+
+/**
+ * `--label key=value` flags, validated before they reach the daemon.
+ *
+ * An empty key or one containing `=` would silently produce a malformed label
+ * that a downstream `docker ps --filter label=…` could not match, so misuse
+ * surfaces during construction rather than as a container that mysteriously
+ * has no labels.
+ */
+function renderLabelArgs(labels: Readonly<Record<string, string>> | undefined): string[] {
+	const args: string[] = []
+	if (!labels) return args
+	for (const [key, value] of Object.entries(labels)) {
+		if (!key || key.includes('=')) {
+			throw new Error(`docker label key ${JSON.stringify(key)} is invalid (empty or contains '=')`)
+		}
+		args.push('--label', `${key}=${value}`)
 	}
+	return args
+}
+
+/**
+ * Name the proxy container reads its configuration from.
+ *
+ * The NAME travels in the argv and the VALUE travels in the `docker` CLI
+ * child's environment, which is why this is one constant used by both ends of
+ * that pair rather than a literal written twice.
+ */
+const EGRESS_PROXY_CONFIG_ENV = 'NAMZU_EGRESS_PROXY_CONFIG'
+
+/** Everything {@link renderEgressProxyRunArgs} renders, as a value. */
+export interface EgressProxyArgvInput {
+	readonly config: DockerBackendInternalConfig
+	readonly containerName: string
+	/** Network the proxy reaches the internet through. See `egressProxyUpstreamNetwork`. */
+	readonly upstreamNetwork: string
+	/** The internal network the sandbox is on, which the proxy is also joined to. */
+	readonly internalNetwork: string
+}
+
+/**
+ * The `docker run` argv for the egress proxy container, as a value.
+ *
+ * Extracted for the reason every other argv in this file is: nothing
+ * downstream of it can run without a docker daemon, so a flag that never
+ * reached it — or a `--network` that named the wrong side of a dual-homed
+ * container — could only be caught by an operator in production, where the
+ * symptom is a sandbox that reaches nothing.
+ *
+ * The two networks are the whole topology and they are two calls:
+ * `docker run --network <upstream>` gives the container a default route, and
+ * {@link renderEgressProxyAttachArgs}'s `docker network connect` adds the
+ * internal network afterwards. The order is load-bearing. Attached to the
+ * internal network FIRST it would come up with no default route and no way to
+ * acquire one, and the proxy would be a boundary in front of nothing.
+ *
+ * The hardening baseline is the sandbox's, minus the parts that describe a
+ * filesystem. `--cap-drop=ALL`, `--no-new-privileges` and `--ipc private` are
+ * applied exactly as {@link HARDENING_ARGS} defines them, because this
+ * container sits between untrusted code and the internet and is the last one in
+ * the deployment that should be holding a capability. `--read-only` is the
+ * sandbox's too, with one tmpfs: the proxy writes nothing, and the tmpfs is
+ * there so that a Node process which one day wants a temp file fails at a
+ * filesystem boundary rather than at a mysterious `EROFS`.
+ *
+ * The image is last, so nothing after it is read as a flag — the same rule the
+ * sandbox argv follows, and here it also means the image's own `CMD` starts the
+ * proxy rather than this argv naming an entrypoint.
+ */
+export function renderEgressProxyRunArgs(input: EgressProxyArgvInput): string[] {
+	const { config, containerName, upstreamNetwork, internalNetwork } = input
+	if (!config.egressProxyImage) {
+		throw new Error(
+			'renderEgressProxyRunArgs was called without config.egressProxyImage; the docker backend cannot start an egress proxy container it has no image for. resolveNetwork refuses an allowlist policy in this state, so reaching here means the refusal was bypassed.',
+		)
+	}
+	if (upstreamNetwork === 'none') {
+		throw new Error(
+			`egressProxyUpstreamNetwork is 'none', which would give the proxy container no interface and no route: it would come up unable to reach anything, and the only way the sandbox's traffic reaches the internet would be a boundary that cannot reach it itself. Name a bridge, or drop the field to take the 'bridge' default.`,
+		)
+	}
+	if (upstreamNetwork === internalNetwork) {
+		throw new Error(
+			`egressProxyUpstreamNetwork names '${upstreamNetwork}', which is the same network the sandbox is on — the internal one. A container whose primary network is internal comes up with no default route and never acquires one, so the proxy would start with no way to reach the internet: the boundary would be a container that can only talk to the sandbox. Name a different network for egressProxyUpstreamNetwork, or drop the field to take the 'bridge' default.`,
+		)
+	}
+	return [
+		'run',
+		'--detach',
+		'--rm',
+		'--name',
+		containerName,
+		// The name the sandbox dials, and the name the proxy's own loop guard
+		// has to recognise as itself. Set as the container's hostname so the
+		// entrypoint can read it back with `os.hostname()` instead of holding a
+		// second copy of the constant.
+		'--hostname',
+		PROXY_HOST_ALIAS,
+		'--network',
+		upstreamNetwork,
+		...HARDENING_ARGS,
+		'--read-only',
+		'--tmpfs',
+		`/tmp:${TMPFS_MOUNT_OPTIONS}`,
+		...renderLabelArgs(config.labels),
+		// The NAME only: docker takes the value from the environment of the
+		// `docker` CLI process it names, which the caller sets (see
+		// `startEgressProxyContainer`). The value is the whole policy —
+		// including brokered credential values — and an argv is a worse place
+		// for it than an environment on every platform that has a process
+		// table: `/proc/<pid>/cmdline` is world-readable on Linux, so putting
+		// it here published it to every local user on the docker host for as
+		// long as the client ran, where the child's own environment is readable
+		// only by the user that owns the process. It is still readable by
+		// anything with access to the daemon, through `docker inspect`, and
+		// `docs/sdk/sandbox-egress.md` says so.
+		'--env',
+		EGRESS_PROXY_CONFIG_ENV,
+		config.egressProxyImage,
+	]
+}
+
+/**
+ * The `docker network connect` argv that makes the proxy dual-homed.
+ *
+ * `--alias` is what puts `namzu-egress` in the internal network's DNS, which
+ * is the name {@link buildDockerRunArgs} hands the sandbox in its proxy
+ * environment. The alias rather than the container name because the alias is
+ * the constant: a container named `namzu-egress-<sandbox-id>` would otherwise
+ * make the sandbox's `HTTP_PROXY` value depend on a generated id, and the two
+ * would have to be kept in step by hand.
+ */
+export function renderEgressProxyAttachArgs(input: EgressProxyArgvInput): string[] {
+	return [
+		'network',
+		'connect',
+		'--alias',
+		PROXY_HOST_ALIAS,
+		input.internalNetwork,
+		input.containerName,
+	]
 }
 
 /**
@@ -530,9 +813,35 @@ const HARDENING_ARGS: readonly string[] = [
 	'private',
 ]
 
-/** Name the container reaches the host-side egress proxy by. */
+/**
+ * Name the sandbox reaches the egress proxy by.
+ *
+ * This used to be a `--add-host namzu-egress:host-gateway` entry, because the
+ * proxy ran on the host's loopback and `host-gateway` is docker's portable
+ * name for the host from inside a container. It is now the proxy's own
+ * container name and network alias on the internal network, which needs no
+ * alias file at all: docker's embedded DNS resolves a container's aliases for
+ * every container on the same user-defined network. The constant survives the
+ * mechanism because what the sandbox is told has not changed — only what makes
+ * the name resolve, and whether anything else can be reached.
+ */
 const PROXY_HOST_ALIAS = 'namzu-egress'
 
+/**
+ * Port the egress proxy listens on inside its own container.
+ *
+ * A fixed port rather than one the host reads back, because there is no host
+ * port involved: the sandbox dials the proxy container directly on the network
+ * they share. The old arrangement had to read a published port back out of
+ * `docker inspect`, with the race and the failure mode that came with it.
+ */
+const EGRESS_PROXY_PORT_INSIDE_CONTAINER = 2025
+
+/** Name of the sibling container the egress proxy runs in, for one sandbox. */
+function egressProxyContainerName(sandboxId: string): string {
+	return `${PROXY_HOST_ALIAS}-${sandboxId}`
+}
+
 /**
  * Mount options for every scratch mount this backend creates.
  *
@@ -838,9 +1147,12 @@ export interface DockerRunArgvInput {
 	readonly network: string
 	readonly hostReachability: 'host-port' | 'container-network'
 	/**
-	 * Port the host-side egress proxy listens on, when one is running. Absent
-	 * means no proxy, and no proxy environment is passed in — which is not the
-	 * same fact as a proxy that was configured and is unreachable.
+	 * Port the egress proxy listens on, when one is running. Absent means no
+	 * proxy, and no proxy environment is passed in — which is not the same
+	 * fact as a proxy that was configured and is unreachable.
+	 *
+	 * It is the proxy CONTAINER's port, on the internal network the two
+	 * containers share; nothing is published on the host any more.
 	 */
 	readonly egressProxyPort?: number
 }
@@ -849,7 +1161,7 @@ export interface DockerRunArgvInput {
  * The complete `docker run` argv, as a value.
  *
  * Extracted for the same reason {@link resolveNetwork} and
- * {@link egressProxyOptions} were: everything downstream of it needs a running
+ * {@link egressProxyContainerConfig} were: everything downstream of it needs a running
  * Docker daemon, so a confinement flag that never reached the argv — or one
  * that reached it in an order that cancels another — could only be caught by an
  * operator noticing its effect missing in production. Spawning a fake `docker`
@@ -883,22 +1195,7 @@ export function buildDockerRunArgs(input: DockerRunArgvInput): string[] {
 		args.push('--user', config.runAsUser)
 	}
 
-	// `--label key=value` flags. Validate first — an empty key or
-	// a key containing `=` would silently produce a malformed
-	// label that downstream `docker ps --filter label=…` queries
-	// could not match reliably. Throw before the spawn so misuse
-	// surfaces during construction, not as a mysterious "container
-	// has no labels" later.
-	if (config.labels) {
-		for (const [key, value] of Object.entries(config.labels)) {
-			if (!key || key.includes('=')) {
-				throw new Error(
-					`docker label key ${JSON.stringify(key)} is invalid (empty or contains '=')`,
-				)
-			}
-			args.push('--label', `${key}=${value}`)
-		}
-	}
+	args.push(...renderLabelArgs(config.labels))
 
 	args.push(...renderLayoutMountArgs(layout))
 	// Forward only the workspace root so the worker's lexical
@@ -909,15 +1206,27 @@ export function buildDockerRunArgs(input: DockerRunArgvInput): string[] {
 	// write it to a bind path the worker reads at startup —
 	// avoids env-size limits, keeps the wire shape minimal.
 	if (egressProxyPort !== undefined) {
-		// `host-gateway` is docker's own portable name for the host from
-		// inside a container; hard-coding a bridge address would break on
-		// every platform whose bridge is numbered differently. The proxy
-		// itself binds loopback, so this alias is the only way in.
-		args.push('--add-host', `${PROXY_HOST_ALIAS}:host-gateway`)
+		// No `--add-host`, and no `host-gateway`. The proxy is a container on
+		// this container's own internal network and `PROXY_HOST_ALIAS` is its
+		// network alias there (see {@link renderEgressProxyAttachArgs}), which
+		// docker's embedded DNS resolves with no alias file involved. The alias
+		// entry this replaced pointed at the host's loopback, where the proxy
+		// used to run — and a name resolving to a host that is not on this
+		// network is exactly the route this change removes.
 		const proxyUrl = `http://${PROXY_HOST_ALIAS}:${egressProxyPort}`
-		// Both spellings: tooling is split between them, and a workload
-		// that reads only the one that is missing bypasses the boundary
-		// entirely — which would look exactly like the policy working.
+		// Both spellings: tooling is split between them, and a workload that
+		// reads only the one that is missing loses the redirection.
+		//
+		// **These are convenience, not the boundary, and that is the point of
+		// the arrangement.** A tool that honours them sends its requests to the
+		// proxy; a tool that ignores them — a Go or Rust binary that does not
+		// read proxy env, `curl --noproxy '*'`, a raw socket — has nowhere to
+		// send anything. This container is on an `--internal` network with no
+		// default route, and the only host on it is the proxy, so the
+		// uncooperative path fails with `Network unreachable` rather than
+		// bypassing the allowlist. What makes that true is
+		// {@link assertNetworkCarriesThePolicy} refusing a network that is not
+		// internal, not this block of environment.
 		for (const key of ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy']) {
 			args.push('--env', `${key}=${proxyUrl}`)
 		}
@@ -972,6 +1281,25 @@ export function buildDockerRunArgs(input: DockerRunArgvInput): string[] {
 		args.push('--env', `${key}=${value}`)
 	}
 
+	// The worker's credential, rendered VALUELESS and last among the `--env`
+	// flags.
+	//
+	// Valueless, because `docker run --env NAME` reads the value out of the
+	// docker CLI's own environment — which `runOnce` is handed — and an argv
+	// is the wrong place for a secret: `ps` shows it to every user on the
+	// host for as long as the CLI lives, and a non-zero run puts the whole
+	// argv into the error this backend throws. The CLI environment is
+	// readable only by the same user and root, and the message is redacted
+	// besides.
+	//
+	// Last, because docker applies repeated `--env` flags in order and the
+	// last one wins: a host that separately sets `NAMZU_SANDBOX_TOKEN` in
+	// `options.env` — a copied example, an inherited environment — must not
+	// be able to displace the value its own client is sending, which would
+	// produce a container that rejects every call and reads as a broken
+	// worker rather than as a duplicated setting.
+	args.push('--env', 'NAMZU_SANDBOX_TOKEN')
+
 	args.push(config.image)
 	return args
 }
@@ -986,50 +1314,61 @@ async function spawnDockerSandbox(
 	const id = generateSandboxId()
 	const docker = config.dockerBinary ?? DEFAULT_DOCKER_BINARY
 
-	// The boundary a host allowlist is actually enforced at. Started before
-	// the container so its address can be handed in as proxy environment,
-	// and torn down with the sandbox — a proxy holding real credentials
-	// must not outlive the thing it was filtering for.
-	let egressProxy: RunningEgressProxy | undefined
-	if (needsEgressProxy(options.egress) && options.egress) {
-		const policy = options.egress
-		try {
-			egressProxy = await new EgressProxy(egressProxyOptions(config, policy)).listen()
-			options.signal?.throwIfAborted()
-		} catch (error) {
-			await egressProxy?.close().catch(() => undefined)
-			throw error
-		}
-	}
+	// The worker's per-instance credential, minted HERE — per `create()`, not
+	// per process and never per image. Three properties are the point, and
+	// each one rules out a cheaper shape:
+	//
+	//  - Per instance. A token baked into the image is shared by every
+	//    container ever built from it and readable by anything that can pull
+	//    it, which is a worse artifact than a documented absence: it looks
+	//    like a credential while separating nobody.
+	//  - Not in an argv, and not in any message. It rides in the docker CLI
+	//    child's environment, which `runOnce` is handed, and the CLI resolves
+	//    it there for the valueless `--env NAMZU_SANDBOX_TOKEN`; a non-zero
+	//    `docker run` renders its argv with every `--env` value redacted. So
+	//    `ps` on the host does not show it and the error this backend throws
+	//    does not carry it — neither of which was true when the value was
+	//    rendered into the argv.
+	//  - Where it IS visible, said plainly: the container's own config, so
+	//    `docker inspect <name>` shows it for the container's life, to anyone
+	//    who can already talk to the daemon — the same authority that can
+	//    `docker exec` into the sandbox. And the worker's own `/proc` inside
+	//    the container, to a workload that shares its uid. Both are why it is
+	//    per-instance and dies with the container rather than being shared or
+	//    long-lived.
+	//  - Dead with the container. Nothing revokes it, because the only process
+	//    that would accept it is removed with the sandbox, and the container's
+	//    config that still holds it is removed with it.
+	//
+	// 32 bytes rather than a uuid: this is a secret, not an identifier, and
+	// base64url keeps it one argv-free environment value on every platform.
+	const workerToken = randomBytes(32).toString('base64url')
 
 	const hostReachability = config.hostReachability ?? 'host-port'
-	const network = resolveNetwork(
-		config.network ?? 'none',
-		options.egress,
-		egressProxy !== undefined,
-	)
+	// Whether a proxy CONTAINER will run, which is what `resolveNetwork` turns
+	// on: an allowlist policy needs the image to run one as, and without it
+	// there is no boundary to hand traffic to. The refusal lives in
+	// `resolveNetwork` so that every caller of it gets the same answer, and it
+	// fires before anything is started.
+	const proxyPlanned = needsEgressProxy(options.egress) && config.egressProxyImage !== undefined
+	const network = resolveNetwork(config.network ?? 'none', options.egress, proxyPlanned)
 	// Whether this network can carry the reachability mode and the policy is
 	// a fact about the network, so it is checked against the daemon rather
-	// than inferred from its name. Before the container starts on purpose: a
+	// than inferred from its name. Before anything starts on purpose: a
 	// refusal here is a wiring mistake and must not arrive dressed as a
 	// container that failed to come up, which is exactly how it used to
 	// arrive.
-	try {
-		assertNetworkCarriesThePolicy(
-			network,
-			hostReachability,
-			options.egress,
-			await inspectNetworkInternalFlag(docker, network, options.signal),
-		)
-	} catch (err) {
-		// The allowlist kinds start a proxy above, and this is outside the
-		// try/catch that owns teardown — so without this the refusal would
-		// leave a listening server on loopback stamping real credentials.
-		await egressProxy?.close().catch(() => undefined)
-		throw err
-	}
+	assertNetworkCarriesThePolicy(
+		network,
+		hostReachability,
+		options.egress,
+		await inspectNetworkInternalFlag(docker, network, options.signal),
+	)
 	const containerName = `namzu-sandbox-${id}`
 
+	/** The proxy container's name, once it is being started. */
+	let egressProxyContainer: string | undefined
+
 	// All bind sources come from the consumer-supplied layout. The
 	// backend never allocates host directories and never removes them
 	// — that pre-existing single-mount mkdtemp path was the source of
@@ -1043,20 +1382,32 @@ async function spawnDockerSandbox(
 		// reconciliation; an external daemon that commits after this delete still
 		// needs its ordinary label/name reaper.
 		const removeContainer = runOnceQuiet(docker, ['rm', '-f', containerName], signal)
-		// The proxy starts BEFORE the container and its only other close is
-		// in `destroy()`, which a create that never returned can never
-		// reach. So every failure between the two — a daemon that is down, a
-		// port that could not be read, a worker that missed its readiness
-		// deadline, a label the validator rejected — left a listening server
-		// on loopback stamping real credential headers, plus a retained
-		// event-loop handle, and a retry loop left one per attempt. That is
-		// exactly the invariant this file states where the proxy is started:
-		// it must not outlive the thing it was filtering for.
-		// Start both teardown arms before awaiting either. A stuck runtime must
-		// not prevent the proxy from releasing its credential-bearing listener.
-		const closeProxy = egressProxy?.close().catch(() => undefined) ?? Promise.resolve()
-		egressProxy = undefined
-		await Promise.all([removeContainer, closeProxy])
+		// The proxy container starts BEFORE the sandbox and its only other
+		// teardown is in `destroy()`, which a create that never returned can
+		// never reach. So every failure between the two — a daemon that is
+		// down, a port that could not be read, a worker that missed its
+		// readiness deadline, an abort — would leave a container holding real
+		// credentials and a live route to the internet, and a retry loop left
+		// one per attempt. That is the invariant this file states where the
+		// proxy is started: it must not outlive the thing it was filtering
+		// for. Start both arms before awaiting either: a stuck runtime must
+		// not keep the credential-bearing one alive.
+		//
+		// The proxy arm is the reconciler rather than a `runOnceQuiet` on this
+		// signal, and the difference is the grace this function's caller runs
+		// under: `runFailureCleanup` spends ONE SECOND on both arms together,
+		// so a daemon that is slow to answer rather than down would have its
+		// `docker rm -f` killed at that boundary — the credential-bearing
+		// container outliving the sandbox by exactly the failure this exists to
+		// prevent. The reconciler carries its own deadline, is not reachable by
+		// any abort, and is not waited on by the caller's grace either: it
+		// finishes whether or not this function is still listening.
+		const removeProxy =
+			egressProxyContainer === undefined
+				? Promise.resolve()
+				: removeEgressProxyContainer(docker, egressProxyContainer)
+		egressProxyContainer = undefined
+		await Promise.all([removeContainer, removeProxy])
 	}
 
 	let hostPort: number
@@ -1066,16 +1417,53 @@ async function spawnDockerSandbox(
 	const rootDir = resolvedLayout.outputs.containerPath
 
 	try {
+		// The boundary a host allowlist is actually enforced at, as a sibling
+		// container on this container's network (#398). Started before the
+		// sandbox so its alias is in the network's DNS by the time the sandbox's
+		// proxy environment resolves it, and removed with the sandbox — a proxy
+		// holding real credentials must not outlive the thing it was filtering
+		// for, and on this topology a leftover one is also a live route to the
+		// internet for anything that can reach that network.
+		//
+		// Inside this `try` on purpose, which the first cut of this change got
+		// wrong. This block has three suspension points — the resolver, the
+		// proxy's `docker run`, and an explicit `throwIfAborted()` — and an
+		// abort at any of them leaves a container holding real credentials with
+		// nothing that will ever remove it: `destroy()` is unreachable, because
+		// `create()` never returned a handle. Outside the `try` the abort
+		// rethrew past `cleanupOnFailure`; inside it, every path that does not
+		// return a `Sandbox` goes through that cleanup, which removes the proxy
+		// by name on a deadline of its own. The abort that arrives here has to
+		// be raised by a call inside the block — the sandbox's own `docker run`
+		// does that itself — so an abort before this point reaches the same
+		// place by the same route.
+		if (proxyPlanned && options.egress) {
+			egressProxyContainer = egressProxyContainerName(id)
+			// Resolved once, here, rather than per request — see
+			// `egressProxyContainerConfig` for what that costs and why it is paid.
+			const allowedHosts = await resolveAllowedHosts(options.egress)
+			options.signal?.throwIfAborted()
+			await startEgressProxyContainer({
+				docker,
+				config,
+				containerName: egressProxyContainer,
+				internalNetwork: network,
+				allowedHosts,
+				signal: options.signal,
+			})
+			options.signal?.throwIfAborted()
+		}
+
 		const args = buildDockerRunArgs({
 			config,
 			options,
 			containerName,
 			network,
 			hostReachability,
-			...(egressProxy ? { egressProxyPort: egressProxy.port } : {}),
+			...(egressProxyContainer ? { egressProxyPort: EGRESS_PROXY_PORT_INSIDE_CONTAINER } : {}),
 		})
 
-		await runOnce(docker, args, options.signal)
+		await runOnce(docker, args, options.signal, { NAMZU_SANDBOX_TOKEN: workerToken })
 		if (hostReachability === 'host-port') {
 			hostPort = await readMappedPort(docker, containerName, options.signal)
 			baseUrl = `http://127.0.0.1:${hostPort}`
@@ -1108,7 +1496,7 @@ async function spawnDockerSandbox(
 	let retirementPromise: Promise<{ readonly accepted: boolean; readonly error?: Error }> | undefined
 	let teardownPromise: Promise<void> | undefined
 	let teardownComplete = false
-	const workerClient = new HttpWorkerClient(baseUrl)
+	const workerClient = new HttpWorkerClient(baseUrl, workerToken)
 	const assertActive = (): void => {
 		if (lifecycle !== 'active') {
 			throw new Error(`Sandbox ${id} is ${lifecycle}; no new worker operation can be admitted`)
@@ -1125,10 +1513,17 @@ async function spawnDockerSandbox(
 			} catch (error) {
 				teardownError = error
 			} finally {
-				try {
-					await egressProxy?.close()
-				} catch (error) {
-					teardownError ??= error
+				// The proxy goes with the sandbox, for the reason it is
+				// started before it: a container holding real credentials must
+				// not outlive the thing it was filtering for, and on this
+				// topology leaving it running would also leave a live route to
+				// the internet on a network the sandbox was confined to.
+				if (egressProxyContainer !== undefined) {
+					try {
+						await runOnce(docker, ['rm', '-f', egressProxyContainer], signal)
+					} catch (error) {
+						teardownError ??= error
+					}
 				}
 			}
 			if (teardownError !== undefined) throw teardownError
@@ -1212,15 +1607,81 @@ async function spawnDockerSandbox(
 			// here and doing nothing would leave the caller believing the
 			// sandbox had been confined when it had not. Same rule the
 			// egress-kind refusal above follows.
-			if (!egressProxy) {
+			if (egressProxyContainer === undefined) {
 				throw withHint(
 					new Error(
 						'This sandbox cannot change its network policy: it was created without an egress proxy, so its network was fixed at creation and there is nothing to narrow. Refusing rather than accepting a policy that would not be applied.',
 					),
-					'Construct the provider with an egress proxy to make the policy mutable, or create a second sandbox under the narrower policy.',
+					'Construct the provider with an egress proxy (and an egressProxyImage to run it as) to make the policy mutable, or create a second sandbox under the narrower policy.',
 				)
 			}
-			egressProxy.setAllowedHosts(async () => policy.allowedHosts)
+			// The policy lives in the proxy container's environment, which is
+			// written when the container starts and cannot be rewritten from
+			// outside. So a live policy change REPLACES the container: the
+			// allowlist the caller asked for is the allowlist the next
+			// connection meets, and the connections open at that instant fail
+			// closed. That is a real difference from the in-process proxy this
+			// used to be — it swapped the allowlist in place, with no window in
+			// which the proxy was absent — and it is the honest trade for a
+			// boundary the sandbox cannot route around. See
+			// `docs/sdk/sandbox-egress.md`.
+			//
+			// The name is read out of the closure once, here, rather than at
+			// each use below: `cleanupOnFailure` clears it, and a swap that
+			// raced a failing create would otherwise call `assertActive()` and
+			// then name `undefined` in the removal.
+			const proxyContainer = egressProxyContainer
+			try {
+				await restartEgressProxyContainer({
+					docker,
+					config,
+					containerName: proxyContainer,
+					internalNetwork: network,
+					allowedHosts: policy.allowedHosts,
+				})
+				// A teardown that landed while the replacement was starting
+				// leaves a container nothing else will ever remove: `destroy()`
+				// is running or has run, `egressProxyContainer` is only removed
+				// from `teardownSandbox` and `cleanupOnFailure`, and the
+				// `assertActive()` above ran BEFORE the first `await` — before
+				// the swap suspended inside `restartEgressProxyContainer`, which
+				// is exactly when a teardown lands. So the swap fails here
+				// rather than reporting a policy change on a sandbox that no
+				// longer exists.
+				assertActive()
+			} finally {
+				// ... and the replacement is removed even so, because the check
+				// above cannot be where the guarantee lives. It sits AFTER the
+				// container comes into existence, and that ordering is what
+				// makes it airtight rather than merely narrower than the check
+				// at entry. A generation counter read before the `docker run`
+				// has the opposite shape: it can only refuse a start it already
+				// knows about, and a teardown that begins between that refusal
+				// being evaluated and the daemon committing the container is in
+				// no check's view — the container exists and nothing has looked
+				// since. Here the two orderings partition the space instead. A
+				// teardown that began before this point has already set
+				// `lifecycle`, synchronously (`teardownSandbox` and `retire()`
+				// both do, before their first `await`), so this removal runs. A
+				// teardown that begins after it issues its own `rm -f` for this
+				// same name — `teardownSandbox` reads `egressProxyContainer`,
+				// which is this container — against a container that, at this
+				// point, exists. Whichever of the two runs second finds the
+				// container and removes it, and both are idempotent.
+				//
+				// A signal-less remover, and not `runOnce` on some signal, for
+				// the reason `removeEgressProxyContainer` exists: the teardown
+				// this is racing may be one whose own signal was already
+				// aborted, and it removes nothing at all in that case (the whole
+				// container set is left, which is what `Sandbox.destroy`
+				// promises to settle promptly over). That is the caller's
+				// contract and not something to defeat — but a proxy container
+				// holding brokered credentials and a live route to the internet
+				// is not something to leave with it either.
+				if (lifecycle !== 'active') {
+					await removeEgressProxyContainer(docker, proxyContainer)
+				}
+			}
 		},
 
 		async writeFile(path: string, content: string | Buffer): Promise<void> {
@@ -1230,7 +1691,10 @@ async function spawnDockerSandbox(
 			try {
 				res = await fetch(`${baseUrl}/write-file`, {
 					method: 'POST',
-					headers: { 'content-type': 'application/json' },
+					headers: {
+						'content-type': 'application/json',
+						...workerAuthorization(workerToken),
+					},
 					body: JSON.stringify({
 						path,
 						content: buf.toString('base64'),
@@ -1250,6 +1714,12 @@ async function spawnDockerSandbox(
 					{ cause: err },
 				)
 			}
+			if (res.status === 401) {
+				throw withHint(
+					new Error(`write-file failed: HTTP 401 ${await res.text()}`),
+					WORKER_UNAUTHORIZED_HINT,
+				)
+			}
 			if (!res.ok) {
 				throw new Error(`write-file failed: HTTP ${res.status} ${await res.text()}`)
 			}
@@ -1278,10 +1748,19 @@ async function spawnDockerSandbox(
 			}
 			const res = await fetch(`${baseUrl}/read-file`, {
 				method: 'POST',
-				headers: { 'content-type': 'application/json' },
+				headers: {
+					'content-type': 'application/json',
+					...workerAuthorization(workerToken),
+				},
 				body: JSON.stringify({ path, encoding: 'base64' }),
 				signal: options?.signal,
 			})
+			if (res.status === 401) {
+				throw withHint(
+					new Error(`read-file failed: HTTP 401 ${await res.text()}`),
+					WORKER_UNAUTHORIZED_HINT,
+				)
+			}
 			if (!res.ok) {
 				throw new Error(`read-file failed: HTTP ${res.status} ${await res.text()}`)
 			}
@@ -1336,6 +1815,211 @@ async function spawnDockerSandbox(
 	}
 }
 
+/** The proxy's upstream network when the host named none. See the field. */
+const DEFAULT_EGRESS_PROXY_UPSTREAM_NETWORK = 'bridge'
+
+/**
+ * How long a reconciliation remove of the proxy container may take.
+ *
+ * The same order as `retire()`'s own deadline, and for the same reason: this
+ * bounds a call to a daemon that may never answer. It is a deadline of its own
+ * rather than the caller's, because the caller is usually an aborted operation
+ * — see {@link removeEgressProxyContainer}.
+ */
+const EGRESS_PROXY_REMOVE_TIMEOUT_MS = 5_000
+
+/**
+ * Remove the proxy container, on a path that is already failing.
+ *
+ * Three properties, each of which the first cut of this change got wrong, and
+ * each of which is why this is a function rather than a `runOnceQuiet` call at
+ * three sites:
+ *
+ *  - **It never takes the caller's signal.** A reconciliation remove handed an
+ *    already-aborted signal does not reach the daemon at all: `runOnce` and
+ *    `runOnceQuiet` install an abort listener that kills the child the moment
+ *    they see one, so `docker rm -f` dies before it is spawned and the
+ *    container survives — in exactly the case this exists to handle, an
+ *    operation that was aborted midway through starting it.
+ *  - **It is bounded anyway.** A fresh deadline of its own, so a daemon that
+ *    never answers cannot hang the failure path that is cleaning up after it.
+ *  - **It does not throw.** Whatever went wrong to bring the caller here is the
+ *    thing the caller needs to hear; a failure to remove is reported by the
+ *    container's own name in `docker ps` and by the label reaper this file
+ *    documents, not by replacing that error with a worse one.
+ */
+async function removeEgressProxyContainer(docker: string, containerName: string): Promise<void> {
+	const deadline = new OperationDeadline(
+		EGRESS_PROXY_REMOVE_TIMEOUT_MS,
+		`egress proxy container ${containerName} removal`,
+	)
+	try {
+		await deadline.run((signal) => runOnceQuiet(docker, ['rm', '-f', containerName], signal))
+	} catch {
+		// Deliberately swallowed. See the third property above.
+	}
+}
+
+interface EgressProxyContainerInput {
+	readonly docker: string
+	readonly config: DockerBackendInternalConfig
+	readonly containerName: string
+	readonly internalNetwork: string
+	/**
+	 * The hosts the proxy will permit, already resolved. Resolved by the
+	 * caller rather than passed as a policy because the two callers resolve
+	 * differently and the difference is the point: `create()` resolves a
+	 * policy once through {@link resolveAllowedHosts}, and `setNetworkPolicy`
+	 * is handed a list by definition (`SandboxNetworkPolicy`).
+	 */
+	readonly allowedHosts: readonly string[]
+	readonly signal?: AbortSignal
+}
+
+/**
+ * Start the proxy container: run it, join it to the internal network, prove it
+ * is up.
+ *
+ * Three steps and not one, in this order, for reasons that are all about the
+ * topology rather than about docker's ergonomics. `docker run --network
+ * <upstream>` gives the proxy its default route — the leg that reaches the
+ * internet. `docker network connect --alias` adds the internal leg the sandbox
+ * dials it on, and it has to be second: a container created on an internal
+ * network first comes up with no default route and never gets one, which is a
+ * proxy that can reach nothing. The readiness check is third because the first
+ * two are `docker run` exiting 0, and `docker run --detach` exits 0 for a
+ * container whose entrypoint is about to fail — an image without the compiled
+ * module in it, or a config the entrypoint refused. Those failures arrive as a
+ * sandbox whose every outbound request fails, which reads as the policy
+ * working.
+ *
+ * A failure after the container exists removes it before rethrowing. Leaving
+ * it would leave a container holding real credentials and a live route to the
+ * internet with no sandbox it belongs to. This is not the only remover on that
+ * path: the block that starts this container sits INSIDE the `try` that owns
+ * `cleanupOnFailure`, and the name it is started under is in
+ * `egressProxyContainer` from before the call, so the caller's cleanup removes
+ * the same name again. The first cut of this change had the block outside that
+ * `try` and this sentence said the caller's own cleanup could not see the
+ * container; the two were wrong together, and the leak was real.
+ */
+async function startEgressProxyContainer(input: EgressProxyContainerInput): Promise<void> {
+	const { docker, config, containerName, internalNetwork, allowedHosts, signal } = input
+
+	const argvInput: EgressProxyArgvInput = {
+		config,
+		containerName,
+		upstreamNetwork: config.egressProxyUpstreamNetwork ?? DEFAULT_EGRESS_PROXY_UPSTREAM_NETWORK,
+		internalNetwork,
+	}
+	// The policy, on its way to the container's environment by way of the
+	// `docker` CLI's own. See `renderEgressProxyRunArgs` for why it does not
+	// travel in the argv.
+	const proxyEnvironment = {
+		[EGRESS_PROXY_CONFIG_ENV]: JSON.stringify(
+			egressProxyContainerConfig(config, allowedHosts, EGRESS_PROXY_PORT_INSIDE_CONTAINER),
+		),
+	}
+
+	try {
+		await runOnce(docker, renderEgressProxyRunArgs(argvInput), signal, proxyEnvironment)
+	} catch (error) {
+		// The container may exist even though this call did not return
+		// successfully: `docker run --detach` is a CLI process talking to a
+		// daemon, and the daemon can commit the container while the client is
+		// killed, times out, or fails to report the id back. Remove by name
+		// before rethrowing, which is what the docblock above promised in the
+		// first cut of this change and did not do.
+		await removeEgressProxyContainer(docker, containerName)
+		// An abort is not a failure to start, and the caller that aborted is
+		// entitled to hear its own reason back — the same rule every other
+		// catch in this file follows. Without this an acquisition timeout would
+		// arrive dressed as an image-install problem, which is the diagnosis
+		// shape this file refuses everywhere else.
+		signal?.throwIfAborted()
+		throw withHint(
+			new Error(
+				`Could not start the egress proxy container '${containerName}' from image '${config.egressProxyImage}': ${error instanceof Error ? error.message : String(error)}`,
+			),
+			'Build that image with `docker build -f packages/sandbox/egress-proxy/Dockerfile -t <tag> packages/sandbox` (after `pnpm --filter @namzu/sandbox build`), and name the tag in egressProxyImage. The sandbox is deliberately not started when the only way its traffic reaches the internet is missing.',
+		)
+	}
+
+	try {
+		await runOnce(docker, renderEgressProxyAttachArgs(argvInput), signal)
+		await assertEgressProxyContainerIsRunning(docker, containerName, signal)
+	} catch (error) {
+		await removeEgressProxyContainer(docker, containerName)
+		throw error
+	}
+}
+
+/**
+ * Replace the proxy container, for `setNetworkPolicy`.
+ *
+ * The policy the container enforces is in its environment, which is written
+ * when it starts and is not writable from outside, so a live policy change is
+ * a new container. The window between the two is one in which the sandbox has
+ * no route out at all — the old proxy is gone and the new one is not up yet —
+ * which fails CLOSED. That is the property worth naming: the alternative
+ * ordering (start the second, then remove the first) has no such window, but
+ * two containers cannot hold the same name or the same network alias, so it
+ * would need a second name the sandbox's `HTTP_PROXY` does not know.
+ */
+async function restartEgressProxyContainer(
+	input: Omit<EgressProxyContainerInput, 'signal'>,
+): Promise<void> {
+	await removeEgressProxyContainer(input.docker, input.containerName)
+	try {
+		await startEgressProxyContainer(input)
+	} catch (error) {
+		// The hint names both states rather than assuming the safe one. The
+		// removal above swallows its own failure, so "the old container is
+		// gone" is not something this function knows: if the daemon never
+		// answered the remove, the previous container is still up and still
+		// enforcing the policy the caller just replaced — which would be a
+		// worse thing to misreport than a sandbox with no route out.
+		throw withHint(
+			error instanceof Error ? error : new Error(String(error)),
+			"Check `docker ps` for this sandbox's proxy container before relying on the new policy: the replacement did not come up, so this sandbox either has no route out at all (every request fails closed) or still has the previous container enforcing the policy you just replaced. Retry, or destroy the sandbox and create it under the policy you want.",
+		)
+	}
+}
+
+/**
+ * Whether the daemon says the proxy container is still up.
+ *
+ * Read the same way {@link inspectNetworkInternalFlag} reads the network's
+ * `Internal` flag, and for the same reason: an unreadable answer is not
+ * evidence. A container that has already exited is gone (`--rm` removed it),
+ * so the failure arrives as a failed `docker inspect` rather than as a
+ * `false`, and both have to land on the same refusal.
+ */
+async function assertEgressProxyContainerIsRunning(
+	docker: string,
+	containerName: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	let running = ''
+	try {
+		running = await runOnce(
+			docker,
+			['inspect', '--format', '{{.State.Running}}', containerName],
+			signal,
+		)
+	} catch {
+		signal?.throwIfAborted()
+		running = ''
+	}
+	if (running.trim() === 'true') return
+	throw withHint(
+		new Error(
+			`The egress proxy container '${containerName}' is not running after being started, so this sandbox has no boundary to reach and no other route out.`,
+		),
+		'Almost always the image: it either lacks the compiled module (build the package before the image — `pnpm --filter @namzu/sandbox build`) or the entrypoint refused its configuration. `docker logs <container>` has the line the entrypoint wrote; the container is started with --rm, so an already-exited one is gone and its output with it.',
+	)
+}
+
 /**
  * Ask Docker which host port it bound to the worker port. Used
  * instead of the pre-reserve-then-publish pattern (which had a
@@ -1455,10 +2139,104 @@ async function waitForWorkerReady(
 	)
 }
 
-function runOnce(binary: string, args: string[], signal?: AbortSignal): Promise<string> {
+/**
+ * The argv as it may appear in an error message: the KEYS of every env
+ * entry, with the values replaced.
+ *
+ * A rendered argv is the last place a secret should survive. A non-zero
+ * `docker run` is a routine outcome — a missing image, a name conflict, a
+ * daemon hiccup, ENOSPC — and its message goes wherever the sandbox
+ * package's errors go: a log line, a telemetry batch, a CI transcript, a
+ * pasted bug report. The env flags carry the worker's credential and every
+ * value the host put in `options.env` (an API key, a broker token), and
+ * none of them are needed to explain an exit code. The keys are kept
+ * because they are what distinguishes "the image could not be pulled" from
+ * "the environment was rejected".
+ *
+ * EVERY SPELLING docker accepts for that flag, not the one this backend
+ * happens to emit today. `-e` IS `--env`, separated or `=`-attached, and
+ * this function used to compare each element to the literal `'--env'`: the
+ * long separated form this builder writes was redacted and `-e K=V`,
+ * `--env=K=V` and `-e=K=V` were printed in full. A future caller writing
+ * any of the three would have put a credential in a log line behind a
+ * docblock that promised it would not. The covered forms are `--env K=V`,
+ * `--env=K=V`, `-e K=V`, `-e=K=V` and the attached short form `-eK=V`; the
+ * one shape it does not read is a value attached to an `-e` bundled into a
+ * group of other short flags (`-iteK=V`), which no caller here writes and
+ * which no rule short of matching `-e` anywhere inside an option could
+ * catch. A valueless entry in any form (`--env K`) is passed through: it
+ * resolves from the CLI's own environment and carries no value to redact.
+ *
+ * That redacts the workspace paths the layout is rendered from as well,
+ * which are not secrets. They are also not what an exit code is about, and
+ * a rule with exceptions is a rule that leaks the first time someone's
+ * credential does not look like one.
+ */
+export function redactDockerArgv(args: readonly string[]): string[] {
+	const rendered = [...args]
+	/** `K=V` → `K=<redacted>`, keeping the key; a valueless entry is left alone. */
+	const redactEntry = (entry: string): string => {
+		const separator = entry.indexOf('=')
+		return separator > 0 ? `${entry.slice(0, separator)}=<redacted>` : entry
+	}
+	for (let index = 0; index < rendered.length; index += 1) {
+		const arg = rendered[index] as string
+		if (arg === '--env' || arg === '-e') {
+			const entry = rendered[index + 1]
+			if (entry !== undefined) rendered[index + 1] = redactEntry(entry)
+			index += 1
+			continue
+		}
+		// Attached, where the option's value is the rest of the same element:
+		// the `=` forms, and the short form with no separator (`-eK=V`).
+		const prefix = arg.startsWith('--env=')
+			? '--env='
+			: arg.startsWith('-e=')
+				? '-e='
+				: arg.startsWith('-e') && arg.length > 2
+					? '-e'
+					: undefined
+		if (prefix !== undefined) rendered[index] = prefix + redactEntry(arg.slice(prefix.length))
+	}
+	return rendered
+}
+
+/**
+ * Run a docker subcommand to completion.
+ *
+ * `extraEnv` is added to the child's environment rather than the parent's, and
+ * it is how a value reaches a container without entering the argv this file
+ * builds. Two callers use it, for the same reason:
+ *
+ *  - The sandbox's own `docker run`, which hands over the worker's
+ *    per-instance credential for the valueless `--env NAMZU_SANDBOX_TOKEN` its
+ *    argv carries (minted in `spawnDockerSandbox`).
+ *  - The egress proxy's `docker run`, which names its configuration variable
+ *    in the argv and hands the value over here. See
+ *    `renderEgressProxyRunArgs`.
+ *
+ * Anything a process is told through the environment is visible to `ps`'s
+ * neighbour, `/proc/<pid>/environ`, only to the user that owns it — while an
+ * argv is world-readable on Linux.
+ */
+function runOnce(
+	binary: string,
+	args: string[],
+	signal?: AbortSignal,
+	extraEnv?: Readonly<Record<string, string>>,
+): Promise<string> {
 	return new Promise((resolve, reject) => {
 		signal?.throwIfAborted()
-		const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+		const child = spawn(binary, args, {
+			stdio: ['ignore', 'pipe', 'pipe'],
+			// The one channel a value can ride in without entering the argv
+			// this process builds: `ps` shows an argv to every user on the
+			// host, and `/proc/<pid>/environ` is readable only by the same
+			// user and root. `docker run --env NAME` (no `=`) reads the value
+			// out of the CLI's own environment, which is why the credential
+			// is passed this way and rendered valueless in the argv.
+			...(extraEnv ? { env: { ...process.env, ...extraEnv } } : {}),
+		})
 		let stdout = ''
 		let stderr = ''
 		let settled = false
@@ -1485,7 +2263,12 @@ function runOnce(binary: string, args: string[], signal?: AbortSignal): Promise<
 		child.on('error', (error) => finish(error))
 		child.on('close', (code) => {
 			if (code === 0) finish(undefined, stdout.trim())
-			else finish(new Error(`${binary} ${args.join(' ')} exited ${code}: ${stderr.trim()}`))
+			else
+				finish(
+					new Error(
+						`${binary} ${redactDockerArgv(args).join(' ')} exited ${code}: ${stderr.trim()}`,
+					),
+				)
 		})
 		if (signal?.aborted) abort()
 		else signal?.addEventListener('abort', abort, { once: true })