@namzu/sandbox 18.1.1 → 19.0.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @namzu/sandbox
 
+## 19.0.0
+
+### Major Changes
+
+- 3e7a97b: No API change. The peer dependency on `@namzu/sdk` moves to the 44 major,
+  because the SDK itself had a major release (its run became a turn inside a
+  session). `@namzu/sandbox` reads no renamed field, but its peer range is
+  published as a caret on the SDK version it was built with, so the SDK major
+  takes it out of range and forces this bump.
+
+  What to do: upgrade `@namzu/sdk` and `@namzu/sandbox` together. Nothing in your
+  code changes.
+
+### Minor Changes
+
+- 0a89444: New: egress profiles. `defineEgressProfile({ name, hosts: [{ host, ports? }] })`
+  validates one named host allowlist, and `createSandboxProvider` takes it as
+  `egressProfile` instead of `defaultEgress`. On docker, runsc and firecracker a
+  profile becomes `deny-all` (no hosts) or a `static` allowlist. Whatever a
+  backend cannot honour is refused at construction with
+  `SandboxEgressProfileError`: ports on firecracker, any profile on the ACI
+  standby pool or beside `defaultEgress`, and a
+  `brokeredCredentials` host the profile does not allow. On docker and runsc a
+  live `setNetworkPolicy` under a profile may only name hosts the profile covers.
+  On kubernetes, `createSandboxProvider` refuses `egressProfile`; put
+  `kubernetesEgressFromProfile(profile, { engine: 'cilium' })` in
+  `backend.egress` instead, which also bounds workspaces and writes the profile
+  label only with `profileLabel: true`.
+
+  Nothing changes for a config without `egressProfile`.
+
+- aee81a6: The docker and runsc egress proxy now enforces the `ports` of an egress
+  profile, on the port it actually dials: an upgraded `http://host/` and a
+  `CONNECT` with no port are checked on 443. A host may use the union of the
+  ports of every rule that matches it. The same check is available on
+  `EgressProxy` as `allowedPorts`, and `egressPortsForRules(profile.hosts)`
+  builds that option from a profile's rules with the same union rule.
+
+  **Rebuild `egressProxyImage` from `packages/sandbox/egress-proxy/Dockerfile`
+  before using `ports`.** A profile with ports sends the proxy a new
+  configuration variable, `NAMZU_EGRESS_PROXY_CONFIG_V2`, and the backend first
+  reads the image's `ai.namzu.egress-proxy.config` label with
+  `docker image inspect`, refusing an image that does not declare version 2 (or
+  that is not on the daemon: `docker image inspect` does not pull). Profiles
+  without ports, and every policy without a profile, need nothing: the proxy
+  gets the same configuration and argv as before.
+
+- c366ca7: New: sandbox seeds. `ensureSandboxSeed(sandbox, seed, { root })` makes the git
+  repositories of a `defineSandboxSeed({ name, repositories })` present under
+  `root` inside any sandbox, through `exec` only. Every call checks each
+  repository (origin URL, and that its pinned or recorded commit is an ancestor
+  of HEAD; a `ref` changed since the clone, or a pin dropped, is drift unless
+  the ref's commit is exactly HEAD) and clones only what is missing, so running it after each create or
+  workspace resume costs one check when nothing changed. Drift is refused before
+  anything is cloned (`onDrift: 'report'` records it instead), and nothing is
+  ever deleted or re-cloned. `root` is required; on docker, use
+  `layout.scratch`, not the outputs root. A repository directory may not sit
+  inside another's, nor under `.namzu/`. URLs with a user name or password,
+  `ssh://` and `git@host:path` are refused, so no credential enters the guest.
+  The guest needs `sh`, `git`, `find`, `mkdir`, `mktemp`, `rm` and GNU `mv`.
+
+  Nothing changes for code that does not call it.
+
+### Patch Changes
+
+- 251d815: On the docker backend, two overlapping `setNetworkPolicy()` calls on one
+  sandbox could leave no egress proxy running while a caller was told its policy
+  was in force, or resolve one call while the other call's policy was the one
+  applied. Calls on one sandbox now run one at a time, in the order they were
+  made, and each resolves only once its own policy is running. A call that asks
+  for the allowlist already in force no longer restarts the proxy. No action is
+  needed.
+- Updated dependencies [8805360]
+- Updated dependencies [9355755]
+- Updated dependencies [755a81a]
+- Updated dependencies [cb1f00c]
+- Updated dependencies [933ba6d]
+- Updated dependencies [3e7a97b]
+- Updated dependencies [a84dc1c]
+- Updated dependencies [b064cea]
+- Updated dependencies [9238347]
+- Updated dependencies [a14b013]
+- Updated dependencies [3641102]
+  - @namzu/sdk@44.0.0
+
 ## 18.1.1
 
 ### Patch Changes

package/README.md

@@ -2,8 +2,8 @@
 type: Reference
 title: "@namzu/sandbox"
 description: >-
-  Container and process isolation for Namzu runs. Two isolation tiers over
-  four backends, a bounded filesystem view, and an egress boundary the run
+  Container and process isolation for Namzu agents. Two isolation tiers over
+  four backends, a bounded filesystem view, and an egress boundary the agent
   cannot talk its way past.
 tags: [readme, package, sandbox, isolation]
 status: stable
@@ -14,7 +14,7 @@ generated: { by: human:bahadirarda, at: 2026-08-30T00:00:00Z }
 
 <h1>@namzu/sandbox</h1>
 
-**Container and process isolation for Namzu runs.**
+**Container and process isolation for Namzu agents.**
 
 [![npm](https://img.shields.io/npm/v/@namzu/sandbox.svg)](https://www.npmjs.com/package/@namzu/sandbox)
 [![build](https://github.com/cogitave/namzu/actions/workflows/ci.yml/badge.svg)](https://github.com/cogitave/namzu/actions/workflows/ci.yml)
@@ -28,7 +28,7 @@ generated: { by: human:bahadirarda, at: 2026-08-30T00:00:00Z }
 
 Runs a tool call somewhere that is not your process. Two isolation tiers
 over four backends, a bounded filesystem view, and an egress boundary the
-run cannot talk its way past.
+agent cannot talk its way past.
 
 ## Install
 
@@ -98,7 +98,7 @@ off nothing else: `--cap-drop=ALL`, `--security-opt=no-new-privileges` and
 Because those four paths are tmpfs, they are RAM, not the container's writable
 layer: scratch larger than half the host's RAM (or than `--memory`, the tighter
 of the two when the host sets one) fails with `ENOSPC` rather than spilling onto
-the host's disk. A run that writes temp files bigger than its memory budget does
+the host's disk. A workload that writes temp files bigger than its memory budget does
 not have to give up the baseline over it: `layout.scratch` is a bind to a host
 directory and stays disk-backed, so a host with room on disk mounts one there
 and points the workload at it — `TMPDIR` set to that container path through the
@@ -761,6 +761,36 @@ Both methods are capability-checked. A backend that cannot preserve the same
 isolation and ownership boundary omits them; callers must not fall back to a
 host process or a different sandbox.
 
+## Egress profiles
+
+`defineEgressProfile({ name, hosts: [{ host, ports? }] })` is one named,
+validated allowlist a host can give any backend. `createSandboxProvider({
+egressProfile })` turns it into `deny-all` (no hosts) or a `static` allowlist
+on docker, runsc and firecracker, and refuses at construction, before any I/O,
+what a backend cannot honour: ports on firecracker, any profile on the ACI
+standby pool, a profile beside `defaultEgress`, and a brokered credential for a
+host outside the profile. On kubernetes, put
+`kubernetesEgressFromProfile(profile, { engine: 'cilium' })` in
+`backend.egress`, which also covers workspaces. On docker and runsc the egress
+proxy enforces a rule's `ports` on the port it dials; rebuild the proxy image
+from `egress-proxy/Dockerfile` first, since the backend refuses an image
+without its `ai.namzu.egress-proxy.config="2"` label. A profile carries no
+credentials and has no wildcard. See
+[docs/sdk/sandbox-egress-profiles.md](../../docs/sdk/sandbox-egress-profiles.md).
+
+## Sandbox seeds
+
+`ensureSandboxSeed(sandbox, defineSandboxSeed({ name, repositories }), { root })`
+makes git repositories present under `root`, doing only what is missing: every
+call checks each repository (origin, and that its pinned or recorded commit is
+an ancestor of HEAD; a changed `ref` is drift unless the checkout already holds
+it), refuses drift without touching anything, clones what is
+missing into a partial directory and moves it into place. `root` is required:
+put it on a kubernetes workspace's disk mount, or `layout.scratch` on docker,
+never the docker outputs root. URLs with credentials, `ssh://` and `git@` are
+refused, so nothing secret enters the guest. See
+[docs/sdk/sandbox-seeds.md](../../docs/sdk/sandbox-seeds.md).
+
 ## Firecracker network policy
 
 At microVM creation, the Firecracker backend maps the resolved egress decision

package/dist/backends/docker/index.d.ts

@@ -42,6 +42,7 @@
  */
 import { type ContainerSandboxLayout, type ResolvedContainerSandboxLayout } from '@namzu/sdk';
 import type { BrokeredCredential } from '../../egress/index.js';
+import { type SandboxEgressProfile } from '../../egress/profile.js';
 import { type EgressPolicy, type SandboxBackend, type SandboxBackendOptions } from '../../index.js';
 /**
  * Backend-specific tuning. Most hosts use the defaults; advanced
@@ -248,6 +249,15 @@ export interface DockerBackendInternalConfig {
      * credentials with a route to the internet.
      */
     readonly labels?: Readonly<Record<string, string>>;
+    /**
+     * The egress profile the provider was built with, already validated by
+     * `defineEgressProfile`. The create-time policy is derived from it by the
+     * provider; the backend reads it for what a policy cannot carry. Under a
+     * profile, a brokered credential for a host outside it is refused at
+     * construction, and a live `setNetworkPolicy` may only name hosts the
+     * profile covers.
+     */
+    readonly egressProfile?: SandboxEgressProfile;
 }
 /**
  * Build a {@link SandboxBackend} backed by Docker. Construction is
@@ -378,6 +388,17 @@ export interface EgressProxyContainerConfig {
      * network alias, which is the name the sandbox actually dials.
      */
     readonly selfNames?: readonly string[];
+    /**
+     * The egress profile's rules, every one of them, when the profile carries
+     * ports. Present only then, and only in the V2 configuration
+     * ({@link EGRESS_PROXY_CONFIG_V2_ENV}): the proxy computes a host's
+     * allowed ports as the union over every rule that matches it, so a rule
+     * without ports is listed too.
+     */
+    readonly hostPorts?: readonly {
+        readonly host: string;
+        readonly ports?: readonly number[];
+    }[];
 }
 /**
  * Build the proxy container's configuration.
@@ -391,7 +412,31 @@ export interface EgressProxyContainerConfig {
  * 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 declare function egressProxyContainerConfig(config: Pick<DockerBackendInternalConfig, 'brokeredCredentials' | 'allowInwardFor'>, allowedHosts: readonly string[], port: number): EgressProxyContainerConfig;
+export declare function egressProxyContainerConfig(config: Pick<DockerBackendInternalConfig, 'brokeredCredentials' | 'allowInwardFor' | 'egressProfile'>, allowedHosts: readonly string[], port: number): EgressProxyContainerConfig;
+/**
+ * Whether the proxy has port rules to enforce: a profile with at least one
+ * rule that carries `ports`. Only then is the configuration sent as V2, and
+ * only then is the image's label checked, so every other policy starts the
+ * proxy with exactly the V1 configuration and argv it always had.
+ */
+export declare function usesPortRules(config: Pick<DockerBackendInternalConfig, 'egressProfile'>): boolean;
+/** The environment variable the proxy's configuration travels in. See {@link usesPortRules}. */
+export declare function egressProxyConfigEnvName(config: Pick<DockerBackendInternalConfig, 'egressProfile'>): string;
+/**
+ * The V2 configuration, which adds port rules. Sent INSTEAD of the V1 one,
+ * never beside it: an image that predates port rules reads only V1, finds it
+ * unset and exits, so it fails closed rather than enforcing hosts without
+ * ports. `egress-proxy/server.mjs` is the reader.
+ */
+export declare const EGRESS_PROXY_CONFIG_V2_ENV = "NAMZU_EGRESS_PROXY_CONFIG_V2";
+/**
+ * The image label saying which configuration version the proxy image reads.
+ * `egress-proxy/Dockerfile` sets it to `2`. Checked with `docker image
+ * inspect` before a proxy with port rules is started, because the other
+ * signal, the container exiting, can arrive after the readiness check has
+ * already passed.
+ */
+export declare const EGRESS_PROXY_IMAGE_CONFIG_LABEL = "ai.namzu.egress-proxy.config";
 /** Everything {@link renderEgressProxyRunArgs} renders, as a value. */
 export interface EgressProxyArgvInput {
     readonly config: DockerBackendInternalConfig;

package/dist/backends/docker/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/docker/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/docker/index.ts"],"names":[],"mappings":"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"}

package/dist/backends/docker/index.js

@@ -43,6 +43,8 @@
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { SANDBOX_DEFAULT_OUTPUTS_PATH, SANDBOX_DEFAULT_SCRATCH_PATH, SANDBOX_DEFAULT_SKILLS_PARENT, SANDBOX_DEFAULT_TOOL_RESULTS_PATH, SANDBOX_DEFAULT_TRANSCRIPTS_PATH, SANDBOX_DEFAULT_UPLOADS_PATH, generateSandboxId, walkFilesViaExec, withHint, } from '@namzu/sdk';
+import { assertBrokeredCredentialsFitProfile } from '../../egress/profile-wiring.js';
+import { SandboxEgressProfileError, egressProfileCoversEntry, egressProfileHasPorts, } from '../../egress/profile.js';
 import { ContainerSandboxLayoutValidationError, } from '../../index.js';
 import { HttpWorkerClient, WORKER_UNAUTHORIZED_HINT, workerAuthorization, } from '../http-worker-client.js';
 import { OperationDeadline, OperationDeadlineExpired, probeHttpHealth, resolveReadinessOptions, runFailureCleanup, } from '../readiness.js';
@@ -64,6 +66,9 @@ export function buildDockerBackend(config) {
     // argv is built, because that is the only place a caller cannot skip them.
     assertCpuLimitIsRenderable(config.cpuLimit);
     assertRootfsOptionsAreCoherent(config);
+    if (config.egressProfile !== undefined) {
+        assertBrokeredCredentialsFitProfile(config.egressProfile, config.brokeredCredentials, config.runtime === 'runsc' ? 'runsc' : 'docker');
+    }
     const readiness = resolveReadinessOptions('docker', config.readyTimeoutMs, config.readyPollIntervalMs, {
         timeoutMs: DEFAULT_READY_TIMEOUT_MS,
         pollIntervalMs: DEFAULT_READY_POLL_MS,
@@ -134,6 +139,15 @@ export async function resolveAllowedHosts(egress) {
         return await egress.resolve();
     throw new Error(`Egress policy of kind "${egress.kind}" does not describe a host allowlist and must not be routed through the proxy.`);
 }
+/**
+ * Whether two allowlists are the same list: same hosts, same order, duplicates
+ * kept. Deliberately not a set comparison. The proxy is handed the list as
+ * written, and a reordered list is a different configuration even when it
+ * permits the same hosts; the only cost of calling it different is one swap.
+ */
+function sameHostList(a, b) {
+    return a.length === b.length && a.every((host, index) => host === b[index]);
+}
 /** Whether a policy needs a boundary before it can be enforced at all. */
 export function needsEgressProxy(egress) {
     return egress?.kind === 'static' || egress?.kind === 'resolver';
@@ -228,8 +242,24 @@ export function egressProxyContainerConfig(config, allowedHosts, port) {
         credentials: config.brokeredCredentials ?? [],
         ...(config.allowInwardFor ? { allowInwardFor: config.allowInwardFor } : {}),
         selfNames: [PROXY_HOST_ALIAS],
+        ...(usesPortRules(config) && config.egressProfile
+            ? { hostPorts: config.egressProfile.hosts }
+            : {}),
     };
 }
+/**
+ * Whether the proxy has port rules to enforce: a profile with at least one
+ * rule that carries `ports`. Only then is the configuration sent as V2, and
+ * only then is the image's label checked, so every other policy starts the
+ * proxy with exactly the V1 configuration and argv it always had.
+ */
+export function usesPortRules(config) {
+    return config.egressProfile !== undefined && egressProfileHasPorts(config.egressProfile);
+}
+/** The environment variable the proxy's configuration travels in. See {@link usesPortRules}. */
+export function egressProxyConfigEnvName(config) {
+    return usesPortRules(config) ? EGRESS_PROXY_CONFIG_V2_ENV : EGRESS_PROXY_CONFIG_ENV;
+}
 /**
  * `--label key=value` flags, validated before they reach the daemon.
  *
@@ -258,6 +288,21 @@ function renderLabelArgs(labels) {
  * that pair rather than a literal written twice.
  */
 const EGRESS_PROXY_CONFIG_ENV = 'NAMZU_EGRESS_PROXY_CONFIG';
+/**
+ * The V2 configuration, which adds port rules. Sent INSTEAD of the V1 one,
+ * never beside it: an image that predates port rules reads only V1, finds it
+ * unset and exits, so it fails closed rather than enforcing hosts without
+ * ports. `egress-proxy/server.mjs` is the reader.
+ */
+export const EGRESS_PROXY_CONFIG_V2_ENV = 'NAMZU_EGRESS_PROXY_CONFIG_V2';
+/**
+ * The image label saying which configuration version the proxy image reads.
+ * `egress-proxy/Dockerfile` sets it to `2`. Checked with `docker image
+ * inspect` before a proxy with port rules is started, because the other
+ * signal, the container exiting, can arrive after the readiness check has
+ * already passed.
+ */
+export const EGRESS_PROXY_IMAGE_CONFIG_LABEL = 'ai.namzu.egress-proxy.config';
 /**
  * The `docker run` argv for the egress proxy container, as a value.
  *
@@ -329,7 +374,7 @@ export function renderEgressProxyRunArgs(input) {
         // anything with access to the daemon, through `docker inspect`, and
         // `docs/sdk/sandbox-egress.md` says so.
         '--env',
-        EGRESS_PROXY_CONFIG_ENV,
+        egressProxyConfigEnvName(config),
         config.egressProxyImage,
     ];
 }
@@ -950,6 +995,11 @@ async function spawnDockerSandbox(config, options, readiness) {
     const containerName = `namzu-sandbox-${id}`;
     /** The proxy container's name, once it is being started. */
     let egressProxyContainer;
+    /**
+     * The allowlist the running proxy container was started with, or
+     * `undefined` when that is not known. See `setNetworkPolicy`.
+     */
+    let appliedHosts;
     // 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
@@ -1016,6 +1066,12 @@ async function spawnDockerSandbox(config, options, readiness) {
         // does that itself — so an abort before this point reaches the same
         // place by the same route.
         if (proxyPlanned && options.egress) {
+            // Before anything is started, and only when there are port rules:
+            // an image that cannot read them is refused by name here, rather
+            // than started and left to exit after the readiness check passed.
+            if (usesPortRules(config)) {
+                await assertEgressProxyImageReadsPortRules(docker, config.egressProxyImage, options.signal);
+            }
             egressProxyContainer = egressProxyContainerName(id);
             // Resolved once, here, rather than per request — see
             // `egressProxyContainerConfig` for what that costs and why it is paid.
@@ -1029,6 +1085,7 @@ async function spawnDockerSandbox(config, options, readiness) {
                 allowedHosts,
                 signal: options.signal,
             });
+            appliedHosts = Object.freeze([...allowedHosts]);
             options.signal?.throwIfAborted();
         }
         const args = buildDockerRunArgs({
@@ -1063,6 +1120,11 @@ async function spawnDockerSandbox(config, options, readiness) {
     let teardownPromise;
     let teardownComplete = false;
     const workerClient = new HttpWorkerClient(baseUrl, workerToken);
+    /**
+     * The tail of this sandbox's `setNetworkPolicy` calls. Each call chains
+     * onto it, so at most one swap is in flight. See `setNetworkPolicy`.
+     */
+    let policyQueue = Promise.resolve();
     const assertActive = () => {
         if (lifecycle !== 'active') {
             throw new Error(`Sandbox ${id} is ${lifecycle}; no new worker operation can be admitted`);
@@ -1192,58 +1254,103 @@ async function spawnDockerSandbox(config, options, readiness) {
             // 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,
+            // Copied now, so a caller that mutates its array while the call waits
+            // its turn does not change what the call applies.
+            const requested = Object.freeze([...policy.allowedHosts]);
+            // Under a profile, a live change narrows within it and never widens
+            // past it: the profile is what the host declared this sandbox may
+            // reach, and a call that names more is refused before it is queued.
+            const profile = config.egressProfile;
+            if (profile !== undefined) {
+                requested.forEach((entry, index) => {
+                    if (egressProfileCoversEntry(profile, entry))
+                        return;
+                    throw new SandboxEgressProfileError('invalid-host', `allowedHosts[${index}]`, `${JSON.stringify(entry)} is outside egress profile ${JSON.stringify(profile.name)}; setNetworkPolicy may narrow within the profile, not widen past it`, config.runtime === 'runsc' ? 'runsc' : 'docker');
                 });
-                // 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);
+            // Calls are SERIALIZED per sandbox, first in first out, and each one
+            // applies and verifies its OWN policy. Overlapping swaps used to
+            // interleave remove, run, attach and inspect against one container
+            // name: one call's pre-start removal, or a failure path's removal by
+            // name, could land on the other call's container after that call had
+            // resolved, leaving no proxy at all; and one call's readiness inspect
+            // could read the other's container as running and resolve claiming a
+            // policy that was not in force. There is no coalescing ("last writer
+            // wins") on purpose: a call replaced by a later one would then resolve
+            // while a different policy was in force, which is the same misreport.
+            // The kubernetes backend's per-sandbox setter follows the same rule
+            // (`per-sandbox-policy.ts`).
+            const step = policyQueue.then(async () => {
+                // Again, because a teardown may have landed while this call waited
+                // behind another.
+                assertActive();
+                // A repeat of the policy the running container already enforces is a
+                // no-op. This backend has no adopt path, so the sandbox handle is the
+                // only owner of its proxy and this record is authoritative. It is
+                // cleared before every swap and set again only when the swap
+                // succeeds, because after a failure the state is unknown and the next
+                // call must swap.
+                if (appliedHosts !== undefined && sameHostList(appliedHosts, requested))
+                    return;
+                appliedHosts = undefined;
+                try {
+                    await restartEgressProxyContainer({
+                        docker,
+                        config,
+                        containerName: proxyContainer,
+                        internalNetwork: network,
+                        allowedHosts: requested,
+                    });
+                    // 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);
+                    }
+                }
+                appliedHosts = requested;
+            });
+            // The chain continues past a rejection: one caller's failed swap is
+            // that caller's error, not a reason to refuse every later call.
+            policyQueue = step.then(() => undefined, () => undefined);
+            await step;
         },
         async writeFile(path, content) {
             assertActive();
@@ -1432,7 +1539,7 @@ async function startEgressProxyContainer(input) {
     // `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)),
+        [egressProxyConfigEnvName(config)]: JSON.stringify(egressProxyContainerConfig(config, allowedHosts, EGRESS_PROXY_PORT_INSIDE_CONTAINER)),
     };
     try {
         await runOnce(docker, renderEgressProxyRunArgs(argvInput), signal, proxyEnvironment);
@@ -1511,6 +1618,35 @@ async function assertEgressProxyContainerIsRunning(docker, containerName, signal
         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.');
 }
+/**
+ * Refuse an egress proxy image that does not declare it reads port rules.
+ *
+ * Reads {@link EGRESS_PROXY_IMAGE_CONFIG_LABEL} off the image with `docker
+ * image inspect`, which needs the image to be present on the daemon: `docker
+ * run` would pull a missing image, and this check does not, so an image that
+ * has never been pulled is refused with that in the hint. Anything other than
+ * `2` or higher, including an unreadable answer, is a refusal.
+ */
+async function assertEgressProxyImageReadsPortRules(docker, image, signal) {
+    let label = '';
+    try {
+        label = await runOnce(docker, [
+            'image',
+            'inspect',
+            '--format',
+            `{{ index .Config.Labels "${EGRESS_PROXY_IMAGE_CONFIG_LABEL}" }}`,
+            image,
+        ], signal);
+    }
+    catch {
+        signal?.throwIfAborted();
+        label = '';
+    }
+    const version = Number(label.trim());
+    if (Number.isInteger(version) && version >= 2)
+        return;
+    throw withHint(new Error(`The egress proxy image '${image}' does not declare that it reads port rules (label ${EGRESS_PROXY_IMAGE_CONFIG_LABEL} is ${JSON.stringify(label.trim())}, and 2 is needed), and this sandbox's egress profile carries ports. Refusing rather than starting a proxy that would exit on a configuration it cannot read.`), 'Rebuild the image from packages/sandbox/egress-proxy/Dockerfile (`pnpm --filter @namzu/sandbox build`, then `docker build -f packages/sandbox/egress-proxy/Dockerfile -t <tag> packages/sandbox`), and pull it onto the daemon first if it lives in a registry. A profile without ports needs no rebuild.');
+}
 /**
  * Ask Docker which host port it bound to the worker port. Used
  * instead of the pre-reserve-then-publish pattern (which had a