@boldblackai/harness 1.10.4 → 1.11.0

package/README.md

@@ -221,6 +221,35 @@ One-shot runs (`-p` or piped stdin) are implicitly ephemeral — no persistence
 
 If an old `.harness/` directory exists in your working directory, harness will emit a deprecation warning with migration instructions.
 
+## Egress control
+
+By default the agent container runs on the default bridge with unrestricted outbound access. `--network` lets you attach it to an existing network instead — for example a network wired to an existing corporate proxy — bringing your own egress topology.
+
+```bash
+harness --network corp-proxy-net
+```
+
+The value is forwarded verbatim to the container runtime (`docker run --network <name>` / `container run --network <name>`); no harness-side validation beyond non-empty. `--network host` proceeds with a warning that host networking removes network isolation.
+
+**Tier 2 — `--egress <allowlist>` managed enforcement** (per [RFC: opt-in egress allowlisting](https://github.com/boldblackai/harness/blob/main/rfcs/2026-10-08_egress_allowlist.md)). Harness creates a per-run `--internal` network (no external route) plus an egress gateway container (squid, CONNECT-only) that is the only container with a route off-host. The agent container reaches the internet **only** through the gateway, and the gateway forwards only allowlisted destination hostnames. Allowlist syntax:
+
+```text
+--egress "api.anthropic.com,api.openai.com,openrouter.ai,.amazonaws.com"
+--egress @/etc/harness/egress-allowlist.txt   # one entry per line, # comments
+--egress none                                  # local-only: no gateway, host reachable
+```
+
+| Entry | Meaning |
+|-------|---------|
+| `host` | exact hostname, HTTPS (443) via CONNECT |
+| `.domain` or `*.domain` | any host under `domain` (e.g. `.amazonaws.com` covers regional endpoints) |
+| `host.docker.internal[:port]` | host-local destination: direct connection, never proxied (port advisory in v1) |
+| `host:port` | rejected in v1 — the raw-TCP extension is deferred (see the RFC) |
+
+`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` (and `NODE_USE_ENV_PROXY=1` — a Node ≥24 built-in that makes `fetch`/undici honor the proxy env vars) are injected after `--env-file`, so they take precedence over same-key values in a user env file. **The boundary is the network topology, not the env vars** — an agent that ignores the proxy env vars can still only reach the gateway. On Linux, harness maps `host.docker.internal` to the egress network's own gateway to keep the host reachable from the internal network (Docker Desktop provides `host.docker.internal` natively). The egress subnet pool defaults to `192.0.2.0/24` split into /29s; override with `HARNESS_EGRESS_SUBNET=<cidr>` when it collides with your networks. `--egress` is docker-only in v1 (the apple/container runtime fails closed with an error) and mutually exclusive with `--network`.
+
+Local-only mode pairs naturally with local mode: `harness --local --egress none` runs the agent against `host.docker.internal:1234` (LM Studio) with no route anywhere else — unlike `docker run --network none`, which would break local-LLM usage too. On Linux the host is reached via the egress network's own gateway (harness maps `host.docker.internal` to it automatically).
+
 ## Reference
 
 ### CLI flags
@@ -240,6 +269,8 @@ If an old `.harness/` directory exists in your working directory, harness will e
 | `--ephemeral` |       | Disable session persistence (implied by `-p` and piped stdin) |
 | `--local`     |       | Force local mode even with `-e` (use LM Studio / local defaults) |
 | `--mount-entire-home` | | Allow running from your home directory (mounts all of `$HOME` as the workspace) |
+| `--network`    |       | Attach the container to an existing network (e.g. one wired to a corp proxy); see [Egress control](#egress-control) |
+| `--egress`     |       | Restrict outbound traffic to an allowlist (hosts, `.suffix` domains, `@file`, or `none` for local-only); see [Egress control](#egress-control) |
 | `--help`      | `-h`  | Show help |
 
 ### Environment variables
@@ -248,6 +279,7 @@ If an old `.harness/` directory exists in your working directory, harness will e
 |-----------------------------|-------------|
 | `HARNESS_IMAGE_TAG`         | Override the Docker image tag (defaults to the package version). Setting this implies `--no-verify`. |
 | `HARNESS_CONTAINER_RUNTIME` | Container runtime: `auto` (default — on macOS, prefers Apple's `container` CLI if on PATH; docker everywhere else), `docker` (force docker), or `apple` (deprecated explicit alias; warns). |
+| `HARNESS_EGRESS_SUBNET`     | Override the egress network subnet (IPv4 CIDR; default pool `192.0.2.0/24` split into /29s). |
 | `XDG_DATA_HOME`             | Override the base directory for persistence data (defaults to `~/.local/share`). |
 | `XDG_CACHE_HOME`            | Override the base directory for the cosign cache (defaults to `~/.cache`). |
 

package/bin/harness.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -49,6 +50,8 @@ class DockerRuntime {
             "no-new-privileges:true",
             "--security-opt",
             `seccomp=${SECCOMP_PROFILE}`,
+            ...(input.network ? ["--network", input.network] : []),
+            ...input.addHostArgs,
             ...input.envFileArgs,
             ...input.envArgs,
             ...input.volumeArgs,
@@ -137,6 +140,8 @@ class AppleContainerRuntime {
         // is only a minor in-guest defense-in-depth loss. Capability
         // restrictions ARE supported, so --cap-drop=ALL --cap-add=NET_RAW stays.
         const ttyFlags = input.interactive ? ["-i", "-t"] : ["-i"];
+        // --network is forwarded identically under both runtimes (Tier 1
+        // passthrough; apple/container accepts --network natively).
         return [
             "run",
             "--rm",
@@ -145,6 +150,8 @@ class AppleContainerRuntime {
             "ALL",
             "--cap-add",
             "NET_RAW",
+            ...(input.network ? ["--network", input.network] : []),
+            ...input.addHostArgs,
             ...input.envFileArgs,
             ...input.envArgs,
             ...input.volumeArgs,
@@ -431,12 +438,16 @@ Options:
   --ephemeral            Disable session persistence (implied by -p and piped stdin)
   --local                Force local mode even with -e (use LM Studio / local defaults)
   --mount-entire-home    Allow running from your home directory (mounts all of $HOME as the workspace)
+  --network <name>       Attach the container to an existing network (e.g. one wired to a corp proxy)
+  --egress <list>        Restrict outbound traffic to an allowlist (comma-separated hosts, .suffix domains,
+                         host.docker.internal, @file, or "none" for airgap); managed proxy network
   -h, --help             Show this help message
 
 Environment variables:
   HARNESS_IMAGE_TAG           Override the Docker image tag (defaults to package version)
   HARNESS_REGISTRY            Override the container registry (defaults to ghcr.io/boldblackai/harness)
   HARNESS_CONTAINER_RUNTIME   Container runtime: auto (default; prefers Apple container on macOS), docker, apple (deprecated)
+  HARNESS_EGRESS_SUBNET       Override the egress network subnet pool (IPv4 CIDR, default 192.0.2.0/24 split into /29s)
   XDG_DATA_HOME              Override the base directory for persistence data (defaults to ~/.local/share)
   XDG_CACHE_HOME             Override the base directory for cosign cache (defaults to ~/.cache)
 
@@ -483,6 +494,8 @@ const MINIMIST_OPTS = {
         "a",
         "volumes",
         "port",
+        "network",
+        "egress",
     ],
     alias: {
         e: "env-file",
@@ -614,10 +627,529 @@ for (const spec of portArgList) {
         process.exit(1);
     }
 }
+// ---------------------------------------------------------------------------
+// Egress control (rfcs/2026-10-08_egress_allowlist.md), Tier 1: pass an
+// existing container network through to the runtime. Brings your own
+// topology (e.g. a network wired to an existing corp proxy). Strictly
+// opt-in; without the flag the argv is unchanged.
+// ---------------------------------------------------------------------------
+const networkArg = (() => {
+    const flag = argv.network ?? null;
+    if (flag !== null && flag.trim() === "") {
+        console.error("harness: --network requires a non-empty network name");
+        process.exit(1);
+    }
+    return flag;
+})();
+if (networkArg === "host") {
+    console.error("harness: WARNING: --network host removes network isolation between the container and the host.");
+}
+const HOST_LOCAL_NAME = "host.docker.internal";
+function fail(message) {
+    console.error(`harness: ${message}`);
+    process.exit(1);
+}
+/**
+ * Like fail(), but for errors raised inside egress bring-up after the
+ * managed network exists: the network must be removed before exiting, or
+ * it is orphaned until the next --egress run's stale sweep.
+ */
+function failWithNetworkCleanup(message, network) {
+    console.error(`harness: ${message}`);
+    try {
+        (0, node_child_process_1.execFileSync)("docker", ["network", "rm", network], {
+            stdio: "ignore",
+            timeout: 10000,
+        });
+    }
+    catch {
+        // best-effort; the stale sweep catches survivors
+    }
+    process.exit(1);
+}
+/**
+ * Parse a raw --egress entry into its typed form, or fail with RFC-cited
+ * error copy. Grammar: `host`, `.domain`/`*.domain` (suffix),
+ * `host.docker.internal[:port]` (host-local, advisory port), `host:port`
+ * (rejected in v1, deferred raw-TCP extension).
+ */
+function parseEgressEntry(raw) {
+    const entry = raw.trim();
+    if (entry === "") {
+        fail("--egress entry is empty.");
+    }
+    const portMatch = entry.match(/^(.*):(\d+)$/);
+    const hasPort = portMatch !== null;
+    const body = hasPort ? portMatch[1] : entry;
+    const port = hasPort ? Number.parseInt(portMatch[2], 10) : null;
+    if (hasPort && (port === null || port < 1 || port > 65535)) {
+        fail(`--egress entry "${entry}" has an invalid port.`);
+    }
+    const hostLocal = body === HOST_LOCAL_NAME;
+    if (hasPort && !hostLocal) {
+        fail(`--egress entry "${entry}": non-443 ports are not supported in v1 (HTTPS CONNECT proxying only). Host and suffix entries default to port 443; the raw-TCP extension is deferred (see rfcs/2026-10-08_egress_allowlist.md).`);
+    }
+    let host = body;
+    let suffix = false;
+    if (host.startsWith("*.") && host.length > 2) {
+        suffix = true;
+        host = host.slice(2);
+    }
+    else if (host.startsWith(".") && host.length > 1) {
+        suffix = true;
+        host = host.slice(1);
+    }
+    if (host === "" || host === "." || host.includes("/") || host.includes(" ")) {
+        fail(`--egress entry "${entry}" is not a valid hostname.`);
+    }
+    return { host, suffix, hostLocal, port };
+}
+/**
+ * Parse the full --egress value: comma-separated entries, `@file` form, or
+ * the literal `none` (airgap). Empty/whitespace items between commas are
+ * tolerated; a file whose entries are all comments selects airgap.
+ */
+function parseEgressValue(value) {
+    let rawEntries;
+    const v = value.trim();
+    if (v === "") {
+        return fail('--egress requires a value: a comma-separated list, "@file", or "none" (airgap).');
+    }
+    if (v === "none") {
+        rawEntries = [];
+    }
+    else if (v.startsWith("@")) {
+        const file = v.slice(1);
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(file, "utf8");
+        }
+        catch {
+            return fail(`--egress: cannot read allowlist file ${file}`);
+        }
+        rawEntries = content
+            .split("\n")
+            .map((l) => l.replace(/#.*$/, "").trim())
+            .filter((l) => l !== "");
+    }
+    else {
+        rawEntries = v.split(",").map((e) => e.trim());
+    }
+    const seen = new Set();
+    const entries = [];
+    for (const raw of rawEntries) {
+        if (raw === "")
+            continue;
+        const parsed = parseEgressEntry(raw);
+        const key = `${parsed.suffix ? "." : ""}${parsed.host}${parsed.port !== null ? `:${parsed.port}` : ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        entries.push(parsed);
+    }
+    const hostLocal = entries.filter((e) => e.hostLocal);
+    const proxied = entries.filter((e) => !e.hostLocal);
+    // Local-only (formerly "airgap") means literally nothing allowlisted — the
+    // `none` literal or a file whose entries are all comments. A host-local-only
+    // list is NOT airgap: it keeps the internal network (so the host, and only
+    // the host, is reachable) but starts no gateway. Collapsing such lists into
+    // airgap made `--egress "host.docker.internal:1234"` useless (reported in
+    // the PR review) — and it's the natural pairing with `--local`.
+    return { entries, proxied, hostLocal, airgap: entries.length === 0 };
+}
+// Subnet allocation from the documentation pool 192.0.2.0/24 broken into
+// /29s (32 subnets, gateway .1, egress gateway static .2). Overridable via
+// HARNESS_EGRESS_SUBNET=<cidr>. Collisions with live docker networks are
+// detected before create; a fully exhausted pool is a hard error.
+const EGRESS_SUBNET_POOL = "192.0.2.0/24";
+const EGRESS_SUBNET_SIZE = 29; // 6 usable hosts each, plenty for one run
+/** List docker networks as [{name, subnet}] (best-effort; [] on failure). */
+function dockerNetworks() {
+    try {
+        const out = (0, node_child_process_1.execFileSync)("docker", ["network", "ls", "--format", "{{.Name}}"], { stdio: ["ignore", "pipe", "ignore"], timeout: 5000 })
+            .toString()
+            .trim();
+        if (out === "")
+            return [];
+        return out
+            .split("\n")
+            .map((name) => ({ name, subnet: dockerNetworkSubnet(name) }));
+    }
+    catch {
+        return [];
+    }
+}
+/** Inspect one network's IPv4 subnet (empty string on failure). */
+function dockerNetworkSubnet(name) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)("docker", [
+            "network",
+            "inspect",
+            "--format",
+            "{{if .IPAM.Config}}{{(index .IPAM.Config 0).Subnet}}{{end}}",
+            name,
+        ], { stdio: ["ignore", "pipe", "ignore"], timeout: 5000 })
+            .toString()
+            .trim();
+        return out;
+    }
+    catch {
+        return "";
+    }
+}
+function cidrToIpInt(cidr) {
+    const m = cidr.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\/(\d{1,2})$/);
+    if (!m)
+        return null;
+    const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+    if (octets.some((o) => o > 255))
+        return null;
+    return ((((octets[0] << 24) >>> 0) +
+        (octets[1] << 16) +
+        (octets[2] << 8) +
+        octets[3]) >>>
+        0);
+}
+function ipIntToString(int) {
+    return [
+        (int >>> 24) & 0xff,
+        (int >>> 16) & 0xff,
+        (int >>> 8) & 0xff,
+        int & 0xff,
+    ].join(".");
+}
+/**
+ * Pick a free /29 from the pool, skipping subnets already in use by any
+ * docker network. Returns e.g. "192.0.2.8/29" or exits with an error.
+ */
+function allocateEgressSubnet() {
+    const custom = process.env.HARNESS_EGRESS_SUBNET;
+    if (custom) {
+        if (cidrToIpInt(custom) === null || !custom.includes("/")) {
+            fail(`HARNESS_EGRESS_SUBNET must be an IPv4 CIDR (got "${custom}").`);
+        }
+        return custom;
+    }
+    const poolBase = cidrToIpInt(EGRESS_SUBNET_POOL);
+    if (poolBase === null)
+        return fail("internal: bad egress subnet pool");
+    const used = new Set(dockerNetworks()
+        .map((n) => n.subnet)
+        .filter(Boolean));
+    // 32 /29s in a /24
+    for (let i = 0; i < 32; i++) {
+        const candidate = (poolBase + i * 8) >>> 0;
+        const cidr = `${ipIntToString(candidate)}/${EGRESS_SUBNET_SIZE}`;
+        if (!used.has(cidr))
+            return cidr;
+    }
+    return fail(`--egress: no free subnet in the ${EGRESS_SUBNET_POOL} pool; set HARNESS_EGRESS_SUBNET to a free private /29.`);
+}
+/**
+ * Generate squid.conf from the allowlist, deny-by-default. Only called when
+ * proxied entries exist (local-only mode starts no gateway).
+ *
+ * Exact hosts and dot-suffixed domains go in SEPARATE dstdomain ACLs: squid
+ * 6.x rejects a single ACL mixing bare hosts with `.suffix` entries
+ * ("Bungled ... acl" — verified live against the pinned 6.13 image; the
+ * RFC's flagship example list is exactly such a mixed list). ACLs must
+ * precede the http_access lines that reference them (squid parses
+ * sequentially).
+ * All writable paths point at /tmp: the gateway runs as the unprivileged
+ * `proxy` user, and Debian squid's defaults (/run/squid.pid, /var/log/squid)
+ * are root-owned — a fatal startup error without this.
+ */
+function generateSquidConfig(allowlist) {
+    const exact = allowlist.proxied.filter((e) => !e.suffix).map((e) => e.host);
+    const suffix = allowlist.proxied
+        .filter((e) => e.suffix)
+        .map((e) => `.${e.host}`);
+    return [
+        "# generated by harness --egress; do not edit",
+        "http_port 3128",
+        "pid_filename /tmp/squid.pid",
+        "cache deny all",
+        "coredump_dir /tmp",
+        ...(exact.length ? [`acl exact-domains dstdomain ${exact.join(" ")}`] : []),
+        ...(suffix.length
+            ? [`acl suffix-domains dstdomain ${suffix.join(" ")}`]
+            : []),
+        ...(exact.length ? ["http_access allow exact-domains"] : []),
+        ...(suffix.length ? ["http_access allow suffix-domains"] : []),
+        "http_access deny all",
+        "access_log stdio:stderr",
+        "cache_log stdio:stderr",
+        "",
+    ].join("\n");
+}
+/** Parse `--egress` CLI value; null when the flag is absent. */
+const egressArg = argv.egress ?? null;
+let egressAllowlist = null;
+if (egressArg !== null) {
+    if (networkArg !== null) {
+        fail("--egress and --network are mutually exclusive (the managed network is the point).");
+    }
+    egressAllowlist = parseEgressValue(egressArg);
+}
+// ---------------------------------------------------------------------------
+// Egress lifecycle helpers (docker-only; the apple runtime fails closed).
+// All output is captured/discarded on stdout so e2e shim assertions on the
+// final `run` argv stay clean; runtime errors surface on stderr.
+// ---------------------------------------------------------------------------
+function dockerSync(args, what, timeoutMs = 30000, cleanupNetwork) {
+    try {
+        return (0, node_child_process_1.execFileSync)("docker", args, {
+            stdio: ["ignore", "pipe", "inherit"],
+            timeout: timeoutMs,
+        }).toString();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const message = `--egress: ${what} failed: ${msg}`;
+        if (cleanupNetwork) {
+            failWithNetworkCleanup(message, cleanupNetwork);
+        }
+        fail(message);
+    }
+}
+/**
+ * Remove harness-egress-* networks left behind by crashed runs.
+ *
+ * A crashed run (e.g. SIGTERM during the agent run) leaves its detached
+ * gateway container attached, so the network is never empty and the
+ * empty-only check would never reclaim it — while its /29 blocks the pool
+ * ("Pool overlaps") for every later run. Staleness test: a live run's
+ * network holds the gateway PLUS the agent container; a crashed run's holds
+ * only the gateway (the agent ran with --rm). Networks whose only container
+ * is a harness-egress-gw-* are stale: kill the gateway, then the network.
+ * (Best-effort: a concurrent run mid-bring-up — gateway attached, agent not
+ * yet started — is indistinguishable and may be swept; runs are expected to
+ * be sequential, matching the empty-network sweep's existing race.)
+ */
+function sweepStaleEgressNetworks() {
+    for (const net of dockerNetworks()) {
+        if (!net.name.startsWith("harness-egress-"))
+            continue;
+        try {
+            const out = (0, node_child_process_1.execFileSync)("docker", [
+                "network",
+                "inspect",
+                "--format",
+                "{{range .Containers}}{{.Name}} {{end}}",
+                net.name,
+            ], { stdio: ["ignore", "pipe", "ignore"], timeout: 5000 })
+                .toString()
+                .trim();
+            const members = out === "" ? [] : out.trim().split(/\s+/);
+            const stale = members.every((m) => m.startsWith("harness-egress-gw-"));
+            if (!stale)
+                continue;
+            for (const gw of members) {
+                try {
+                    (0, node_child_process_1.execFileSync)("docker", ["rm", "-f", gw], {
+                        stdio: ["ignore", "pipe", "ignore"],
+                        timeout: 15000,
+                    });
+                    console.error(`harness: swept stale egress gateway ${gw}`);
+                }
+                catch {
+                    // best-effort; an un-removable gateway just leaves the network
+                }
+            }
+            (0, node_child_process_1.execFileSync)("docker", ["network", "rm", net.name], {
+                stdio: ["ignore", "pipe", "inherit"],
+                timeout: 5000,
+            });
+            console.error(`harness: swept stale egress network ${net.name}`);
+        }
+        catch {
+            // best-effort; a busy/in-use network survives
+        }
+    }
+}
+/**
+ * Wait until the gateway's squid is up (pid file exists and responds to
+ * `squid -k check`). If the container exits first, dump its logs and fail —
+ * a dead gateway must never be treated as "slow to start".
+ */
+function waitForGateway(container) {
+    for (let i = 0; i < 20; i++) {
+        let running = "true";
+        try {
+            running = (0, node_child_process_1.execFileSync)("docker", ["inspect", "--format", "{{.State.Running}}", container], { stdio: ["ignore", "pipe", "ignore"], timeout: 5000 })
+                .toString()
+                .trim();
+        }
+        catch {
+            // inspect races with --rm removal; treat as not-yet-running
+        }
+        if (running === "false") {
+            let logs = "";
+            try {
+                logs = (0, node_child_process_1.execFileSync)("docker", ["logs", "--tail", "40", container], {
+                    stdio: ["ignore", "pipe", "ignore"],
+                    timeout: 5000,
+                }).toString();
+            }
+            catch {
+                // container already reaped by --rm
+            }
+            fail(`--egress: egress gateway exited during startup.\n${logs.trim()}`);
+        }
+        try {
+            (0, node_child_process_1.execFileSync)("docker", ["exec", container, "squid", "-k", "check"], {
+                stdio: "ignore",
+                timeout: 5000,
+            });
+            return;
+        }
+        catch {
+            syncSleep(250);
+        }
+    }
+    console.error("harness: WARNING: egress gateway did not confirm readiness in 5s; continuing.");
+}
+/** Synchronous sleep (Atomics.wait on a shared buffer). */
+function syncSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Bring up the managed egress topology: --internal network, gateway (unless
+ * airgap), proxy env. Returns state the run() flow merges into RunInput and
+ * a cleanup closure to invoke after the agent container exits.
+ */
+async function startEgress(runtime, allowlist, noVerifyFlag) {
+    const runId = (0, node_crypto_1.randomUUID)().slice(0, 8);
+    const network = `harness-egress-${runId}`;
+    const subnet = allocateEgressSubnet();
+    const subnetBase = cidrToIpInt(subnet);
+    if (subnetBase === null)
+        fail(`--egress: bad subnet "${subnet}".`);
+    const gatewayIp = ipIntToString((subnetBase + 2) >>> 0);
+    sweepStaleEgressNetworks();
+    dockerSync(["network", "create", "--internal", "--subnet", subnet, network], `creating egress network (${subnet})`);
+    return bringUpEgress(network, runId, subnetBase, allowlist, noVerifyFlag, runtime);
+}
+async function bringUpEgress(network, runId, subnetBase, allowlist, noVerifyFlag, runtime) {
+    // All failure paths below must go through failWithNetworkCleanup so the
+    // network created by startEgress is not orphaned.
+    const gatewayIp = ipIntToString((subnetBase + 2) >>> 0);
+    const envArgs = [];
+    let gatewayContainer = null;
+    // The gateway exists to proxy outbound destinations — start it only when
+    // proxied entries exist. Local-only mode (`none`, or host-local-only lists)
+    // has nothing to proxy and runs gateway-free on the internal network.
+    if (allowlist.proxied.length > 0) {
+        const gatewayImage = `${REGISTRY}:egress-proxy-${IMAGE_TAG}`;
+        if (!noVerifyFlag && !process.env.HARNESS_IMAGE_TAG) {
+            try {
+                await verifyImage(runtime, gatewayImage);
+            }
+            catch {
+                failWithNetworkCleanup(`--egress: gateway image verification failed for ${gatewayImage} (pass --no-verify or build the image locally)`, network);
+            }
+        }
+        gatewayContainer = `harness-egress-gw-${runId}`;
+        const confFile = node_path_1.default.join(node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "harness-egress-")), "squid.conf");
+        node_fs_1.default.writeFileSync(confFile, generateSquidConfig(allowlist), {
+            mode: 0o644,
+        });
+        dockerSync([
+            "run",
+            "--rm",
+            "-d",
+            "--name",
+            gatewayContainer,
+            "--cap-drop=ALL",
+            "--security-opt",
+            "no-new-privileges:true",
+            "--security-opt",
+            `seccomp=${SECCOMP_PROFILE}`,
+            "--network",
+            network,
+            "--ip",
+            gatewayIp,
+            "-v",
+            `${confFile}:/etc/squid/squid.conf:ro`,
+            gatewayImage,
+        ], "starting egress gateway", 120000, network);
+        // External leg: the gateway is the only container with a route off-host.
+        dockerSync(["network", "connect", "bridge", gatewayContainer], "attaching gateway to the default bridge", 30000, network);
+        waitForGateway(gatewayContainer);
+        const proxyUrl = `http://${gatewayIp}:3128`;
+        envArgs.push("-e", `HTTPS_PROXY=${proxyUrl}`, "-e", `HTTP_PROXY=${proxyUrl}`, "-e", `NO_PROXY=localhost,127.0.0.1,${HOST_LOCAL_NAME}`, 
+        // Node's fetch/http ignore proxy env vars without this (Node 24+);
+        // inert for non-Node agents.
+        "-e", "NODE_USE_ENV_PROXY=1");
+        console.error(`harness: egress allowlist active — ${allowlist.proxied.length} destination(s) via gateway ${gatewayIp}`);
+    }
+    else {
+        envArgs.push("-e", `NO_PROXY=localhost,127.0.0.1,${HOST_LOCAL_NAME}`);
+        console.error("harness: egress local-only mode — host reachable, no gateway, no external route");
+    }
+    // Host reachability from an --internal network. Docker Desktop provides
+    // host.docker.internal natively. On Linux engines, host-gateway (the default
+    // bridge's gateway) is OFF-SUBNET for the egress network and --internal
+    // drops the forward — measured "Network unreachable" (docker 29.9.1).
+    // Mapping host.docker.internal to the egress network's OWN gateway (the
+    // subnet's .1) works: --internal blocks forwarding off the bridge, not the
+    // host's own endpoint on it (measured HTTP 200). Harness reserves .2 for
+    // the squid container; .1 is the docker-assigned network gateway = the host.
+    const addHostArgs = process.platform === "linux"
+        ? [
+            "--add-host",
+            `${HOST_LOCAL_NAME}:${ipIntToString((subnetBase + 1) >>> 0)}`,
+        ]
+        : [];
+    const gw = gatewayContainer;
+    const cleanup = () => {
+        if (gw !== null) {
+            try {
+                (0, node_child_process_1.execFileSync)("docker", ["rm", "-f", gw], {
+                    stdio: ["ignore", "pipe", "inherit"],
+                    timeout: 15000,
+                });
+            }
+            catch {
+                // best-effort; --rm cleans up on stop, and the stale sweep catches it
+            }
+        }
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                (0, node_child_process_1.execFileSync)("docker", ["network", "rm", network], {
+                    stdio: ["ignore", "pipe", "inherit"],
+                    timeout: 10000,
+                });
+                return;
+            }
+            catch {
+                syncSleep(500); // gateway may still be detaching
+            }
+        }
+    };
+    return {
+        network,
+        gatewayContainer,
+        gatewayIp,
+        envArgs,
+        addHostArgs,
+        cleanup,
+    };
+}
 async function run(prompt) {
     const runtime = selectRuntime();
     runtime.ensureReady();
     const image = getImage(agentName);
+    // --egress is docker-only in v1: whether apple/container supports --internal
+    // networks and multi-network attach is unverified; fail closed (RFC D5).
+    let egress = null;
+    if (egressAllowlist !== null) {
+        if (!(runtime instanceof DockerRuntime)) {
+            fail("--egress is not yet supported under the apple/container runtime " +
+                "(--internal networks / multi-network attach unverified); use HARNESS_CONTAINER_RUNTIME=docker.");
+        }
+        egress = await startEgress(runtime, egressAllowlist, noVerify);
+    }
     if (!noVerify) {
         if (process.env.HARNESS_IMAGE_TAG) {
             console.error(`harness: HARNESS_IMAGE_TAG is set; skipping cosign verification for ${image}`);
@@ -731,16 +1263,25 @@ async function run(prompt) {
     const args = runtime.runArgs({
         interactive,
         envFileArgs,
-        envArgs: [...cloudModeEnv, ...adapterDockerArgs],
+        envArgs: [
+            ...cloudModeEnv,
+            ...adapterDockerArgs,
+            ...(egress?.envArgs ?? []),
+        ],
         volumeArgs,
         userVolumeArgs,
         portArgs,
+        network: egress ? egress.network : networkArg,
+        addHostArgs: egress?.addHostArgs ?? [],
         workdir: "/workspace",
         image,
         containerCmd,
     });
     const child = (0, node_child_process_1.spawn)(runtime.binary(), args, { stdio: "inherit" });
-    child.on("exit", (code) => process.exit(code ?? 1));
+    child.on("exit", (code) => {
+        egress?.cleanup();
+        process.exit(code ?? 1);
+    });
 }
 if (!process.stdin.isTTY && promptArg === null) {
     let input = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boldblackai/harness",
-  "version": "1.10.4",
+  "version": "1.11.0",
   "description": "Portable environment for running coding agents in a container",
   "bin": {
     "harness": "bin/harness.js"
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/boldblackai/harness.git"
   },
-  "packageManager": "pnpm@12.7.0",
+  "packageManager": "pnpm@12.12.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,7 @@
     "lint:ts": "biome check .",
     "lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\"",
     "lint:sh": "shellcheck setup-env.sh entrypoint.sh entrypoint-opencode.sh entrypoint-hermes.sh",
-    "lint:docker": "hadolint Dockerfile Dockerfile.opencode Dockerfile.hermes",
+    "lint:docker": "hadolint Dockerfile Dockerfile.opencode Dockerfile.hermes Dockerfile.egress-proxy",
     "lint:actions": "actionlint",
     "format": "biome format --write .",
     "test:e2e:cli": "node --test tests/e2e/*.test.mjs",