@namzu/sandbox 14.0.0 → 16.0.0

package/dist/backends/docker/index.js

@@ -37,6 +37,13 @@ const WORKER_PORT_INSIDE_CONTAINER = 2024;
  * `create()` call.
  */
 export function buildDockerBackend(config) {
+    // Refused here rather than at the first spawn, so a config that cannot be
+    // rendered — a CPU limit that cannot mean anything, or writable paths
+    // beside a writable root filesystem — surfaces during host wiring instead
+    // of as a container that failed to come up. The same checks run where the
+    // argv is built, because that is the only place a caller cannot skip them.
+    assertCpuLimitIsRenderable(config.cpuLimit);
+    assertRootfsOptionsAreCoherent(config);
     const readiness = resolveReadinessOptions('docker', config.readyTimeoutMs, config.readyPollIntervalMs, {
         timeoutMs: DEFAULT_READY_TIMEOUT_MS,
         pollIntervalMs: DEFAULT_READY_POLL_MS,
@@ -181,9 +188,11 @@ export function egressProxyOptions(config, policy) {
  * are the defaults every container runtime hardening guide starts with,
  * and none of them were present.
  *
- * `--cap-drop=ALL` is deliberately not softened by a re-add list: a
- * workload that genuinely needs a capability should say so through
- * `extraRunArgs` and be visible in review.
+ * `--cap-drop=ALL` is deliberately not softened by a re-add list, and there is
+ * no config field that could soften it either: a workload that genuinely needs
+ * a capability needs a change to this file, where the diff says which
+ * capability and why. A re-add list on the config would grant it to every
+ * sandbox the host spawns, quietly, which is how a baseline stops being one.
  *
  * **It carries a second, independent load, and this is the one that would
  * survive being forgotten.** An egress policy of `deny-all` is enforced by
@@ -208,10 +217,471 @@ export function egressProxyOptions(config, policy) {
  *
  * Recorded here because the first justification above would survive
  * softening this flag and the second would not.
+ *
+ * `--ipc private` closes a door that is not the one its name suggests, and the
+ * difference is worth being exact about. Moby runs `private`, `shareable` and
+ * `none` through the SAME branch (`daemon/oci_linux.go`, `WithNamespaces`), so
+ * `shareable` already gives every container an IPC namespace of its own: a
+ * daemon whose `default-ipc-mode` is `shareable` does not merge anybody's
+ * namespaces, and what an unset flag buys on such a daemon is not a shared one
+ * either. What separates the modes is reachability. Docker's run reference
+ * defines `shareable` as "Own private IPC namespace, with a possibility to
+ * share it with other containers", and that possibility is `--ipc
+ * container:<name>`, which joins another container's IPC namespace — and what
+ * that join needs from the target is a shared-memory directory to enter:
+ * `daemon.getIPCContainer` resolves the target by name and is gated on its
+ * `ShmPath`, which a container created `private` does not have. So on a
+ * daemon defaulting to `shareable` this container's namespace, and the System V
+ * shared memory, semaphores and message queues namespaced with it, are joinable
+ * by anything else on that host which knows the container's name; `--ipc
+ * private` removes that reachability. Creating the joining container still takes
+ * access to the same daemon, so this is not a boundary against an unprivileged
+ * attacker, and it is not claimed as one here. What it buys is that the answer
+ * is in THIS argv rather than in the host's `daemon.json`, which is the only
+ * place the daemon's default is written down. `--ipc none` is deliberately not
+ * used: it takes `/dev/shm` away, and chromium — which the reference image
+ * ships for browser automation — uses it for every renderer process.
+ *
+ * `--read-only` makes the image itself not a place the workload can write. It
+ * is rendered by {@link renderHardeningArgs} rather than listed below, because
+ * it is the one flag here a host can turn off (`readOnlyRootfs: false`), and a
+ * flag in this array would keep being applied after the field said it was not —
+ * a control accepted and not applied, which is the failure this file refuses
+ * everywhere else. The layout's own RW binds (`outputs`, `scratch`) are
+ * separate mounts and are unaffected; what stays writable inside the
+ * container's filesystem is named, path by path and with the reason, in
+ * {@link renderWritableRootfsArgs}. A host whose image needs a path that list
+ * does not name adds it through `writableRootfsPaths`.
+ *
+ * Three controls from the published container-hardening guidance are
+ * deliberately absent, and the reason is here rather than implied:
+ *
+ *  - **A seccomp profile.** Docker already applies its built-in profile to
+ *    every container unless something passes `seccomp=unconfined`, and nothing
+ *    in this backend does — so the tier is filtered, and what is missing is a
+ *    profile TIGHTER than docker's default. Shipping one means shipping a
+ *    hand-written file whose deny list has to be correct for whatever image
+ *    the host names, and this repository cannot test it against the reference
+ *    image's own toolchain (chromium, LibreOffice, the numpy/scipy/duckdb
+ *    stack). A profile that blocks a syscall one of those needs breaks the
+ *    sandbox at a point no test here would catch, which is worse than the gap
+ *    it closes. A host that needs a tighter profile sets `seccomp-profile` in
+ *    the daemon's `daemon.json`, where it applies to this container and every
+ *    other one; `--security-opt seccomp=<file>` is the per-container form, and
+ *    it is not offered as a config field because a path in a config field is a
+ *    file the daemon reads from the HOST, which is a different machine from
+ *    the one this backend runs on whenever it drives a remote daemon.
+ *  - **`--userns-remap`.** It is not a `docker run` flag at all: it is a
+ *    daemon property (`userns-remap` in `daemon.json`, or `dockerd
+ *    --userns-remap=`), and per container the CLI only chooses between the
+ *    namespaces the daemon already made (`--userns=host|private`). Whether a
+ *    remapped namespace exists is therefore settled before this argv is read,
+ *    and a flag here could not settle it — which is the whole reason the
+ *    control is absent rather than configurable: this backend has nothing to
+ *    say about a mapping that belongs to the machine the daemon runs on.
+ *    Enabling it on the host is a real upgrade to this tier (uid 0 inside maps
+ *    to an unprivileged uid outside) and costs this backend nothing; the README
+ *    says so.
+ *  - **`--user`.** Supported, and unset by default on purpose — see the
+ *    `runAsUser` field, which is where a host that knows its image sets it.
  */
-const HARDENING_ARGS = ['--cap-drop=ALL', '--security-opt=no-new-privileges'];
+const HARDENING_ARGS = [
+    '--cap-drop=ALL',
+    '--security-opt=no-new-privileges',
+    '--ipc',
+    'private',
+];
 /** Name the container reaches the host-side egress proxy by. */
 const PROXY_HOST_ALIAS = 'namzu-egress';
+/**
+ * Mount options for every scratch mount this backend creates.
+ *
+ * `exec` is the load-bearing one and the reason this is a named constant
+ * rather than a literal at the call site. Docker does NOT default a `--tmpfs`
+ * mount to a usable scratch directory: `withMounts` in moby's
+ * `daemon/oci_linux.go` starts every user tmpfs from
+ * `["noexec", "nosuid", "nodev", <propagation>]` and appends whatever the
+ * caller passed, so `--tmpfs /tmp` on its own is **noexec**. A workload that
+ * compiles a program into `/tmp` and runs it — `gcc -o /tmp/a.out … &&
+ * /tmp/a.out`, or a python `ctypes.CDLL` of a library it just built there —
+ * would meet `Permission denied` on an executable file, an error that reads
+ * as a broken sandbox rather than as a mount option. Scratch here is as
+ * executable as it was before this backend mounted a tmpfs over it.
+ *
+ * `nosuid` and `nodev` are kept from docker's defaults: the tmpfs is the one
+ * place inside the container a workload can write an arbitrary file to, and
+ * neither a setuid binary nor a device node there has any use that is worth
+ * the escalation path — with `--cap-drop=ALL` no device node could be created
+ * there anyway.
+ *
+ * `mode=1777` is stated rather than inherited from the kernel's tmpfs default
+ * (which is the same value): the mounts have to be writable by whichever uid
+ * the image runs as, and the backend does not know that uid. A sticky,
+ * world-writable scratch directory is what `/tmp` is, and `--read-only` here
+ * is about the image, not about the uid.
+ */
+const TMPFS_MOUNT_OPTIONS = 'nosuid,nodev,exec,mode=1777';
+/**
+ * Paths the reference image needs writable under `--read-only`, as `--tmpfs`.
+ *
+ * `--read-only` says the image is not the workload's disk. It does not say
+ * nothing may be written, and the difference is the sandbox: the layout's own
+ * RW binds (`outputs`, `scratch`) are separate mounts and are unaffected, but
+ * the image's toolchain writes inside the container's own filesystem, and a
+ * `--read-only` that stops it is worse than the gap it closes. Read off
+ * `worker/Dockerfile`, whose whole purpose is producing DOCX/XLSX/PPTX/PDF
+ * deliverables:
+ *
+ *  - `/tmp` — `TMPDIR` for python's `tempfile`, for LibreOffice's extraction
+ *    and for pip's wheel builds, and the conventional place to build and run
+ *    something disposable. Every scratch mount takes
+ *    {@link TMPFS_MOUNT_OPTIONS}, which is where the `exec` docker would not
+ *    have given us is argued for.
+ *  - `/var/tmp` — the second location the temp-file conventions fall back to,
+ *    for a temp file that is meant to outlive an interrupted run.
+ *  - `/home/namzu` — the image's `HOME` (`useradd --create-home namzu`, uid
+ *    1001; docker sets `HOME` from the image's passwd entry). LibreOffice
+ *    refuses a headless conversion without a writable user profile
+ *    (`~/.config/libreoffice`), matplotlib builds a font cache in
+ *    `~/.cache/matplotlib`, fontconfig keeps a user cache, npm's cache is
+ *    `~/.npm`, and `pip install --user` needs `~/.local`.
+ *  - `/workspace` — the image's `WORKDIR`, chowned to `namzu` on purpose
+ *    (`chown -R namzu:namzu /workspace`). Leaving it out would make the
+ *    Dockerfile's own guarantee false.
+ *
+ * These four are the REFERENCE image's needs, not a claim about anyone else's.
+ * A host that points `image` at its own build names what that image needs in
+ * `writableRootfsPaths`, which is why the field exists at all: the backend
+ * cannot read an image's writable set, and the alternative to asking is
+ * guessing. A path a root-running image wants (its `HOME` is `/root`) is a
+ * `writableRootfsPaths` entry for exactly that reason — `/root` is not in this
+ * list, because the shipped image does not run as root and a tmpfs nobody
+ * writes to is a claim that something does.
+ *
+ * A path the LAYOUT already mounts is skipped rather than mounted twice:
+ * docker refuses two mounts at one destination (`Duplicate mount point`), and
+ * the bind the host asked for is the one that must win. A path the HOST names
+ * that the layout also mounts is refused instead of skipped, because there the
+ * two requests contradict each other and nothing should choose between them
+ * silently.
+ *
+ * No `size=` is set. The kernel caps a tmpfs at half the host's RAM, and tmpfs
+ * pages are accounted to the container's memory cgroup, so a run that sets
+ * `--memory` already bounds scratch with the limit the host chose — while any
+ * number picked here would fail a workload that writes a bigger temp file than
+ * we guessed, with `ENOSPC` rather than a diagnosis.
+ *
+ * **The other half of that trade, said out loud because a host will meet it.**
+ * Scratch now lives in RAM instead of on the container's writable layer, so a
+ * temp file larger than half the host's RAM — or larger than `--memory`, which
+ * is the tighter of the two whenever the host set one — fails with `ENOSPC` or
+ * is OOM-killed, where writing it to disk used to succeed. That is the cost of
+ * not leaving the root filesystem writable, and it is not a bug to be reported.
+ * The remedy that keeps the baseline is the layout's own `scratch`, which is a
+ * bind to a host directory and therefore still disk-backed: a host with room on
+ * disk gives the layout one there and points `TMPDIR` at its container path
+ * through the per-call `env` option, so the spill lands on that disk instead of
+ * on a tmpfs. `readOnlyRootfs: false` is the other way, and the one to reach for
+ * second: it puts scratch back on the container's writable layer and gives up
+ * the rest of the baseline with it.
+ */
+const DEFAULT_WRITABLE_ROOTFS_PATHS = [
+    '/tmp',
+    '/var/tmp',
+    '/workspace',
+    '/home/namzu',
+];
+/**
+ * The spelling docker compares a container path by.
+ *
+ * Docker cleans a mount destination before it uses it, so `/tmp/`, `//tmp` and
+ * `/tmp/.` are one directory to it and to the kernel. The check below is an
+ * exact-string comparison, so without this a layout that spelled one of its
+ * mounts any of those ways would not match the tmpfs default at the same
+ * directory: the argv would carry both a `--tmpfs /tmp:...` and a bind at
+ * `/tmp/`, and moby would clean the two destinations into one and refuse the
+ * container at spawn with `Duplicate mount point: /tmp` — the failure the check
+ * exists to prevent, on the one path no test in this repository can reach.
+ * `resolveLayout` does not normalise these (it fills in defaults and compares
+ * spellings as written), so the cleaning has to happen here, where the
+ * comparison does.
+ */
+function cleanContainerPath(path) {
+    const kept = [];
+    for (const segment of path.split('/')) {
+        // Empty segments are `//`, `.` is the directory itself; `..` cancels the
+        // segment before it, which is what the kernel does with it too.
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..')
+            kept.pop();
+        else
+            kept.push(segment);
+    }
+    return `/${kept.join('/')}`;
+}
+/**
+ * Every destination the layout mounts something at, in the spelling docker
+ * itself compares them by.
+ *
+ * The collision check below is exact-string, so a layout path spelled `/tmp/`
+ * would slip past it and docker would then refuse the container with
+ * `Duplicate mount point` — a failure at spawn, on the one path that cannot be
+ * tested without a daemon. Cleaning each path to the spelling moby reduces it
+ * to is what makes the check cover every way of writing the same directory;
+ * see {@link cleanContainerPath}.
+ */
+function mountedContainerPaths(layout) {
+    return [
+        layout.outputs.containerPath,
+        layout.uploads?.containerPath,
+        layout.scratch?.containerPath,
+        layout.toolResults?.containerPath,
+        layout.transcripts?.containerPath,
+        ...(layout.skills?.map((skill) => skill.containerPath) ?? []),
+    ]
+        .filter((path) => Boolean(path))
+        .map(cleanContainerPath);
+}
+/**
+ * Refuse rootfs options that cannot both be honoured.
+ *
+ * `writableRootfsPaths` beside `readOnlyRootfs: false` is a contradiction: with
+ * a writable root filesystem every path is already writable, so the tmpfs
+ * mounts would either be dropped (a control accepted and not applied) or take a
+ * directory off the image for no reason. Refusing is the honest answer, and it
+ * is the same one the sibling backends give a per-sandbox control they cannot
+ * express.
+ *
+ * Called at construction and again where the argv is built, so a config that
+ * reaches `create()` by some path other than `buildDockerBackend` is refused
+ * too.
+ */
+export function assertRootfsOptionsAreCoherent(config) {
+    const paths = config.writableRootfsPaths;
+    if (config.readOnlyRootfs !== false || paths === undefined || paths.length === 0)
+        return;
+    throw new Error('writableRootfsPaths was set on a docker backend configured with readOnlyRootfs: false. With a writable root filesystem every path inside the container is already writable, so these --tmpfs mounts would add nothing and take the named directories off the image. Refusing rather than accepting a control that cannot be applied: drop the paths, or drop readOnlyRootfs: false and let the read-only baseline stand.');
+}
+/**
+ * Refuse a `--cpus` value that cannot mean what it says.
+ *
+ * This covers non-finite and non-positive values and does NOT claim to cover
+ * every bound the daemon would refuse. The difference is worth stating, because
+ * the two classes fail in different places and only one of them is decidable
+ * here. A negative, `NaN` or `Infinity` renders into the argv as text the
+ * daemon either rejects or turns into a bound nobody asked for, and `0` is the
+ * opposite of a bound (`NanoCPUs` of zero is how a container says "no CPU
+ * limit"), so a host that wrote one of those hears about it during wiring
+ * rather than as a container that never came up.
+ *
+ * The upper bound is not ours to check. Moby's `verifyPlatformContainerResources`
+ * refuses `NanoCPUs` above the DAEMON host's CPU count (`"range of CPUs is from
+ * 0.01 to N.00, as there are only N CPUs available"`), and the same function
+ * deliberately sets no floor of its own on Linux, leaving that to the kernel.
+ * Neither number is knowable from here: the `docker` binary this backend drives
+ * can be pointed at a daemon on another machine (`DOCKER_HOST`), and even
+ * locally `os.cpus().length` is this machine's view rather than the daemon's
+ * own `runtime.NumCPU()`. Refusing on a guess at it would break a host whose
+ * daemon has more cores than the process driving it, which is a worse failure
+ * than the one it would catch — those arrive from the daemon with its own
+ * message, at spawn, where every other daemon-side refusal arrives too.
+ */
+export function assertCpuLimitIsRenderable(cpuLimit) {
+    if (cpuLimit === undefined)
+        return;
+    if (!Number.isFinite(cpuLimit) || cpuLimit <= 0) {
+        throw new Error(`cpuLimit must be a finite number greater than 0 (docker's --cpus takes a decimal, e.g. 1.5); got ${String(cpuLimit)}. Refusing rather than rendering an argv whose value means something other than what was written.`);
+    }
+}
+/**
+ * `--tmpfs` flags for the paths that stay writable under `--read-only`.
+ *
+ * See {@link DEFAULT_WRITABLE_ROOTFS_PATHS} for the paths themselves and why
+ * each is there. Returns nothing when the read-only root filesystem is off, and
+ * the two ways a host names paths that cannot be mounted — a contradiction with
+ * `readOnlyRootfs: false`, or a path the layout already mounts — are refusals
+ * rather than a silently shorter list.
+ */
+export function renderWritableRootfsArgs(config) {
+    assertRootfsOptionsAreCoherent(config);
+    if (config.readOnlyRootfs === false)
+        return [];
+    const mounted = new Set(mountedContainerPaths(config.layout));
+    const requested = config.writableRootfsPaths ?? [];
+    for (const path of requested) {
+        // Every segment non-empty and none of them `.` or `..`: an absolute path
+        // with at least one component. Anything else is refused because each
+        // rejected shape is a directory this file's exact-string checks could
+        // hold two spellings of — `/tmp/`, `//tmp` and `/tmp/.` are all `/tmp` to
+        // the kernel, so a default that mounted `/tmp` and a host entry that
+        // mounted `/tmp/` would each pass the duplicate-mount check and then be
+        // refused by docker at spawn, on the one path no test here can reach.
+        // `/` itself is refused as well, and for its own reason: it would make
+        // the whole read-only root filesystem writable again.
+        const segments = path.split('/');
+        const wellFormed = path.startsWith('/') &&
+            segments.length > 1 &&
+            segments.slice(1).every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+        if (!wellFormed) {
+            throw new Error(`writableRootfsPaths entry ${JSON.stringify(path)} is not a normalised absolute path inside the container. Docker requires an absolute mount path with no empty, '.' or '..' segment and no trailing slash, and '/' would make the whole filesystem writable again rather than adding a scratch directory.`);
+        }
+        if (mounted.has(path)) {
+            throw new Error(`writableRootfsPaths names ${path}, which this layout already mounts. Docker refuses two mounts at one destination ("Duplicate mount point"), so which one won would be decided by argument order rather than by anyone's intent. Drop the entry, or change the layout's own mount to the mode you want.`);
+        }
+    }
+    // The set collapses a host entry that repeats a default, which would
+    // otherwise emit the same destination twice and be refused by docker.
+    const paths = [
+        ...new Set([
+            ...DEFAULT_WRITABLE_ROOTFS_PATHS.filter((path) => !mounted.has(path)),
+            ...requested,
+        ]),
+    ];
+    return paths.flatMap((path) => ['--tmpfs', `${path}:${TMPFS_MOUNT_OPTIONS}`]);
+}
+/**
+ * The confinement preamble for one container, in argv order.
+ *
+ * A function rather than a bare constant because `--read-only` is switchable
+ * and the flags that follow it describe what stays writable while it is on:
+ * `readOnlyRootfs: false` removes both the flag and the mounts. That is the only
+ * thing it removes. Everything in {@link HARDENING_ARGS} is applied
+ * unconditionally and no field can turn one of those off, so the argv for
+ * `readOnlyRootfs: false` is the argv this backend produced before any of this
+ * existed PLUS `--ipc private` — those two flags are the whole previous argv,
+ * and `--ipc private` is now unconditional. `--ipc` is not folded under this
+ * switch, because the field names the root filesystem: a host that turned the
+ * read-only rootfs off would be turning IPC isolation off as well, silently,
+ * for a reason the name of the field does not say. A switch has to mean one
+ * thing.
+ */
+export function renderHardeningArgs(config) {
+    return [
+        ...HARDENING_ARGS,
+        ...(config.readOnlyRootfs === false ? [] : ['--read-only']),
+        ...renderWritableRootfsArgs(config),
+    ];
+}
+/**
+ * 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
+ * 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`
+ * and reading back what it was handed proves what the fake was told and nothing
+ * about the container the daemon would build. Here the whole baseline is one
+ * array, and an edit that drops a flag fails a test rather than a deployment.
+ *
+ * Order matters in exactly two places, and both are asserted by the test that
+ * pins this: the image is the last argument, because everything after it is a
+ * command for the container rather than a flag for docker; and every flag that
+ * takes a value is pushed as two argv entries rather than one string, so no
+ * value is ever re-split by anything downstream.
+ */
+export function buildDockerRunArgs(input) {
+    const { config, options, containerName, network, hostReachability, egressProxyPort } = input;
+    const layout = config.layout;
+    assertRootfsOptionsAreCoherent(config);
+    assertCpuLimitIsRenderable(config.cpuLimit);
+    const args = [
+        'run',
+        '--detach',
+        '--rm',
+        '--name',
+        containerName,
+        '--network',
+        network,
+        ...renderHardeningArgs(config),
+    ];
+    if (config.runAsUser) {
+        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(...renderLayoutMountArgs(layout));
+    // Forward only the workspace root so the worker's lexical
+    // resolver agrees with the bind target. The full layout used
+    // to ride along as `NAMZU_SANDBOX_LAYOUT`, but the worker
+    // never branched on it; the manifest's only consumer was a
+    // log line. A skill loader that needs the manifest will
+    // 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`);
+        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.
+        for (const key of ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy']) {
+            args.push('--env', `${key}=${proxyUrl}`);
+        }
+        // Loopback must not be proxied, or the worker cannot talk to
+        // itself.
+        args.push('--env', 'NO_PROXY=localhost,127.0.0.1');
+        args.push('--env', 'no_proxy=localhost,127.0.0.1');
+    }
+    // `outputs` is required by validation, so its containerPath is always
+    // available — the worker uses it as its workspace root.
+    args.push('--env', `NAMZU_SANDBOX_WORKSPACE=${layout.outputs.containerPath}`);
+    args.push('--env', `NAMZU_SANDBOX_READ_ROOTS=${renderLayoutReadRootsEnv(layout)}`);
+    args.push('--env', `NAMZU_SANDBOX_WRITE_ROOTS=${renderLayoutWriteRootsEnv(layout)}`);
+    // Only publish a host port when the consumer is going to reach
+    // the worker through the docker host's loopback (CLI / direct
+    // dev). For `container-network` reachability we leave the port
+    // unpublished — sibling containers reach the worker by its DNS
+    // name on the shared bridge, no host port required.
+    //
+    // Let Docker pick the host port instead of pre-reserving one
+    // in this process. The reservePort()-then-publish-fixed-port
+    // pattern had a TOCTOU window: the OS could hand the port to
+    // another process between our `server.close()` and Docker's
+    // `bind()`. Letting Docker pick (`--publish-all`) and reading
+    // the mapping back via `docker inspect` removes the race.
+    if (hostReachability === 'host-port') {
+        args.push('--publish', `127.0.0.1::${WORKER_PORT_INSIDE_CONTAINER}`);
+    }
+    if (config.runtime) {
+        args.push('--runtime', config.runtime);
+    }
+    // The three bounds the host can set, together and in one order, so a
+    // reader of a `docker inspect` sees them side by side. `--memory` and
+    // `--pids-limit` keep their existing treatment (a non-positive or absent
+    // value means "not set"); `--cpus` refuses a value that would mean
+    // something else, which is why it is the one with a check in front of it.
+    if (options.memoryLimitMb && options.memoryLimitMb > 0) {
+        args.push('--memory', `${options.memoryLimitMb}m`);
+    }
+    if (options.maxProcesses && options.maxProcesses > 0) {
+        args.push('--pids-limit', String(options.maxProcesses));
+    }
+    if (config.cpuLimit !== undefined) {
+        args.push('--cpus', String(config.cpuLimit));
+    }
+    for (const [key, value] of Object.entries(options.env ?? {})) {
+        args.push('--env', `${key}=${value}`);
+    }
+    args.push(config.image);
+    return args;
+}
 async function spawnDockerSandbox(config, options, readiness) {
     options.signal?.throwIfAborted();
     const resolvedLayout = config.layout;
@@ -251,7 +721,6 @@ async function spawnDockerSandbox(config, options, readiness) {
         await egressProxy?.close().catch(() => undefined);
         throw err;
     }
-    const runtime = config.runtime;
     const containerName = `namzu-sandbox-${id}`;
     // All bind sources come from the consumer-supplied layout. The
     // backend never allocates host directories and never removes them
@@ -287,87 +756,14 @@ async function spawnDockerSandbox(config, options, readiness) {
     // always available — the worker uses it as its workspace root.
     const rootDir = resolvedLayout.outputs.containerPath;
     try {
-        // Let Docker pick the host port instead of pre-reserving one
-        // in this process. The reservePort()-then-publish-fixed-port
-        // pattern had a TOCTOU window: the OS could hand the port to
-        // another process between our `server.close()` and Docker's
-        // `bind()`. Letting Docker pick (`--publish-all`) and reading
-        // the mapping back via `docker inspect` removes the race.
-        const args = [
-            'run',
-            '--detach',
-            '--rm',
-            '--name',
+        const args = buildDockerRunArgs({
+            config,
+            options,
             containerName,
-            '--network',
             network,
-            ...HARDENING_ARGS,
-            ...(config.runAsUser ? ['--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(...renderLayoutMountArgs(resolvedLayout));
-        // Forward only the workspace root so the worker's lexical
-        // resolver agrees with the bind target. The full layout used
-        // to ride along as `NAMZU_SANDBOX_LAYOUT`, but the worker
-        // never branched on it; the manifest's only consumer was a
-        // log line. A skill loader that needs the manifest will
-        // write it to a bind path the worker reads at startup —
-        // avoids env-size limits, keeps the wire shape minimal.
-        if (egressProxy) {
-            // `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`);
-            const proxyUrl = `http://${PROXY_HOST_ALIAS}:${egressProxy.port}`;
-            // 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.
-            for (const key of ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy']) {
-                args.push('--env', `${key}=${proxyUrl}`);
-            }
-            // Loopback must not be proxied, or the worker cannot talk to
-            // itself.
-            args.push('--env', 'NO_PROXY=localhost,127.0.0.1');
-            args.push('--env', 'no_proxy=localhost,127.0.0.1');
-        }
-        args.push('--env', `NAMZU_SANDBOX_WORKSPACE=${rootDir}`);
-        args.push('--env', `NAMZU_SANDBOX_READ_ROOTS=${renderLayoutReadRootsEnv(resolvedLayout)}`);
-        args.push('--env', `NAMZU_SANDBOX_WRITE_ROOTS=${renderLayoutWriteRootsEnv(resolvedLayout)}`);
-        // Only publish a host port when the consumer is going to reach
-        // the worker through the docker host's loopback (CLI / direct
-        // dev). For `container-network` reachability we leave the port
-        // unpublished — sibling containers reach the worker by its DNS
-        // name on the shared bridge, no host port required.
-        if (hostReachability === 'host-port') {
-            args.push('--publish', `127.0.0.1::${WORKER_PORT_INSIDE_CONTAINER}`);
-        }
-        if (runtime) {
-            args.push('--runtime', runtime);
-        }
-        if (options.memoryLimitMb && options.memoryLimitMb > 0) {
-            args.push('--memory', `${options.memoryLimitMb}m`);
-        }
-        if (options.maxProcesses && options.maxProcesses > 0) {
-            args.push('--pids-limit', String(options.maxProcesses));
-        }
-        for (const [key, value] of Object.entries(options.env ?? {})) {
-            args.push('--env', `${key}=${value}`);
-        }
-        args.push(config.image);
+            hostReachability,
+            ...(egressProxy ? { egressProxyPort: egressProxy.port } : {}),
+        });
         await runOnce(docker, args, options.signal);
         if (hostReachability === 'host-port') {
             hostPort = await readMappedPort(docker, containerName, options.signal);
@@ -528,12 +924,30 @@ async function spawnDockerSandbox(config, options, readiness) {
                 throw new Error(`write-file failed: HTTP ${res.status} ${await res.text()}`);
             }
         },
-        async readFile(path) {
+        /**
+         * The worker's `/read-file` has no range, so a caller asking for one
+         * is REFUSED rather than handed the whole file.
+         *
+         * {@link Sandbox.readFile} draws that line: a backend that takes
+         * `offset`/`length` and answers with everything has given a wrong
+         * answer, not a degraded one, and the caller stops looking. Declaring
+         * the one-parameter form would not close it — through the `Sandbox`
+         * type a caller can still pass options — so the refusal is explicit.
+         *
+         * `options.signal` IS honoured: the contract says it aborts the read,
+         * and one HTTP request is the whole read here, so it is handed to
+         * `fetch`.
+         */
+        async readFile(path, options) {
             assertActive();
+            if (options?.offset !== undefined || options?.length !== undefined) {
+                throw new Error('readFile: the docker worker serves whole files only, so offset/length cannot be honoured. Read the file whole, or use a backend that streams.');
+            }
             const res = await fetch(`${baseUrl}/read-file`, {
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
                 body: JSON.stringify({ path, encoding: 'base64' }),
+                signal: options?.signal,
             });
             if (!res.ok) {
                 throw new Error(`read-file failed: HTTP ${res.status} ${await res.text()}`);