@boldblackai/harness 1.9.13 → 1.10.0

package/README.md

@@ -5,7 +5,7 @@
 Harness conveniently wraps Docker around three open-source coding agents — [`pi`](https://pi.dev/), [`opencode`](https://opencode.ai),
 and [`hermes`](https://github.com/NousResearch/hermes-agent) — so you can point one at a directory (or file) without giving it access to your entire machine.
 
-> **Documentation:** [boldblackai.github.io/harness](https://boldblackai.github.io/harness/)
+> **Documentation:** [harness.boldblack.ai/docs](https://harness.boldblack.ai/docs/)
 
 ## Features
 
@@ -20,7 +20,7 @@ and [`hermes`](https://github.com/NousResearch/hermes-agent) — so you can poin
 
 ## Quickstart
 
-A container runtime is required. By default harness uses [Docker](https://www.docker.com); on macOS 26 / Apple Silicon you can also use Apple's native [`container`](https://github.com/apple/container) CLI — see [Container runtime](#container-runtime). With the default runtime and LM Studio locally:
+A container runtime is required. By default harness uses [Docker](https://www.docker.com); on macOS 26 / Apple Silicon, Apple's native [`container`](https://github.com/apple/container) CLI is preferred automatically if installed — see [Container runtime](#container-runtime). With the default runtime and LM Studio locally:
 
 ```bash
 lms daemon up
@@ -188,7 +188,7 @@ Each run starts the container with:
 
 Running harness from your home directory is blocked by default, since that would mount all of `$HOME` into the container — exposing dotfiles, credentials, and SSH keys to the agent and giving it a noisy, unfocused workspace. If the resolved working directory equals your home, harness exits with an error. Pass `--mount-entire-home` to opt in for the rare case where mounting all of `$HOME` is genuinely intended. `--file` mode is unaffected (it mounts a single file, not the working directory).
 
-These hardening flags are docker-specific. Under `HARNESS_CONTAINER_RUNTIME=apple`, `--security-opt` is not applied (apple/container workloads are microVMs with their own guest kernel, so the seccomp profile's host-kernel role is subsumed by the VM boundary); capability restrictions remain. See [Container runtime](#container-runtime).
+These hardening flags are docker-specific. When running under Apple's `container` CLI (auto-detected on macOS 26 / Apple Silicon), `--security-opt` is not applied (apple/container workloads are microVMs with their own guest kernel, so the seccomp profile's host-kernel role is subsumed by the VM boundary); capability restrictions remain. See [Container runtime](#container-runtime).
 
 ### Image verification
 
@@ -228,11 +228,12 @@ If an old `.harness/` directory exists in your working directory, harness will e
 | Flag          | Alias | Description |
 |---------------|-------|-------------|
 | `--prompt`    | `-p`  | Pass a prompt directly to the agent |
-| `--env-file`  | `-e`  | Load environment variables into the container |
+| `--env-file`  | `-e`  | Load environment variables into the container; may be repeated |
 | `--file`      | `-f`  | Mount a single file instead of the current directory |
 | `--model`     | `-m`  | Override the model used by the agent |
 | `--agent`     | `-a`  | Select agent: `pi`, `opencode`, `hermes` (default: `pi`) |
 | `--volumes`   | `-v`  | Additional volume mount (`host:container[:opts]`); may be repeated |
+| `--port`      |       | Publish a container port to the host (`[host-ip:]host-port:container-port[/protocol]`); may be repeated |
 | `--no-verify` |       | Skip cosign signature and provenance verification |
 | `--no-skills` |       | Disable mounting user skills directories (`~/.agents/skills`, `~/.claude/skills`) |
 | `--no-context-files` | `-nc` | Disable mounting global context files (`~/.agents/AGENTS.md`, `~/.claude/CLAUDE.md`) |
@@ -246,27 +247,34 @@ If an old `.harness/` directory exists in your working directory, harness will e
 | Variable                    | Description |
 |-----------------------------|-------------|
 | `HARNESS_IMAGE_TAG`         | Override the Docker image tag (defaults to the package version). Setting this implies `--no-verify`. |
-| `HARNESS_CONTAINER_RUNTIME` | Container runtime to use: `docker` (default) or `apple` (Apple's [`container`](https://github.com/apple/container) CLI). |
+| `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). |
 | `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`). |
 
 #### Container runtime
 
-By default harness runs images with `docker`. On macOS 26 / Apple Silicon you can opt into Apple's native [`container`](https://github.com/apple/container) CLI (v1.0.0+) instead, which runs OCI images as lightweight Linux microVMs:
+By default harness auto-detects the container runtime: on macOS, if Apple's native [`container`](https://github.com/apple/container) CLI (v1.0.0+) is on PATH, it is preferred; on every other platform docker is used. Auto-detection is gated to macOS because apple/container ships for macOS only — a binary named `container` on a Linux PATH is an unrelated tool and is ignored. No configuration is needed.
 
 ```bash
 brew install container     # install Apple's container CLI (v1.0.0+)
 container system start     # one-time: start the container system service
 container system kernel set --recommended --arch arm64   # one-time on Apple Silicon (required before first run)
-export HARNESS_CONTAINER_RUNTIME=apple
 harness -p "write me a fizzbuzz in Go"
 ```
 
 On arm64 Macs, `container system kernel set --recommended` is required — without it the first `harness` run fails with `default kernel not configured for architecture arm64`. See [apple/container](https://github.com/apple/container) for details.
 
-The value is **named, not boolean** (`apple` or `docker`, case-insensitive); any other value is a hard error. harness never auto-detects the runtime — you must opt in. Image verification (cosign + SLSA provenance) works identically under both runtimes; the verified-digest cache is keyed by digest, so a digest verified under one runtime is a cache hit under the other.
+To force docker even when `container` is available, set:
 
-**Security note.** Under `=apple`, harness does not apply the `--security-opt no-new-privileges` and `--security-opt seccomp=...` flags it uses under docker, because `apple/container` has no `--security-opt` option. This is not a security regression: each apple/container workload is a microVM with its own ephemeral guest kernel (Apple Virtualization framework), so the `block-af-alg.json` profile's host-kernel role — blocking `socket(AF_ALG)` — is subsumed by the VM boundary itself (hardware-assisted isolation, strictly stronger than a syscall filter). Capability restrictions (`--cap-drop=ALL --cap-add=NET_RAW`) **are** supported and stay on. Only `ro`/`readonly` is honored for volume options under the apple path (SELinux relabel flags like `:Z` are meaningless under macOS virtiofs).
+```bash
+export HARNESS_CONTAINER_RUNTIME=docker
+```
+
+`HARNESS_CONTAINER_RUNTIME=apple` (the pre-auto-detect opt-in) still works but is deprecated: it selects the apple runtime explicitly, prints a deprecation warning, and will be removed in a future release.
+
+Image verification (cosign + SLSA provenance) works identically under both runtimes; the verified-digest cache is keyed by digest, so a digest verified under one runtime is a cache hit under the other.
+
+**Security note.** When running under Apple's `container` CLI, harness does not apply the `--security-opt no-new-privileges` and `--security-opt seccomp=...` flags it uses under docker, because `apple/container` has no `--security-opt` option. This is not a security regression: each apple/container workload is a microVM with its own ephemeral guest kernel (Apple Virtualization framework), so the `block-af-alg.json` profile's host-kernel role — blocking `socket(AF_ALG)` — is subsumed by the VM boundary itself (hardware-assisted isolation, strictly stronger than a syscall filter). Capability restrictions (`--cap-drop=ALL --cap-add=NET_RAW`) **are** supported and stay on. Only `ro`/`readonly` is honored for volume options under the apple path (SELinux relabel flags like `:Z` are meaningless under macOS virtiofs).
 
 **Optional tuning — resource limits.** Apple's container CLI reads defaults from `~/.config/container/config.toml`. Create this file to control CPU and memory allocation for all containers (see [container-system-config.md](https://github.com/apple/container/blob/main/docs/container-system-config.md) for the full schema):
 
@@ -277,6 +285,14 @@ cpus = 8
 memory = "4g"
 ```
 
+**Container → host (`host.docker.internal`).** Docker Desktop provides `host.docker.internal` automatically; Apple's `container` CLI does not. Local-mode agents (pi, opencode, hermes without `-e`) reach LM Studio and other host services via that hostname. One-time setup on Apple Silicon (requires administrator):
+
+```bash
+sudo container system dns create host.docker.internal --localhost 203.0.113.113
+```
+
+Harness prints a reminder on `HARNESS_CONTAINER_RUNTIME=apple` runs if this mapping is missing. See [apple/container — access a host service](https://github.com/apple/container/blob/main/docs/how-to.md#access-a-host-service-from-a-container).
+
 ### Agent-specific behavior
 
 - **pi** — `-m` is passed straight to the binary as `--model`.

package/bin/harness.js

@@ -53,6 +53,7 @@ class DockerRuntime {
             ...input.envArgs,
             ...input.volumeArgs,
             ...input.userVolumeArgs,
+            ...input.portArgs,
             "-w",
             input.workdir,
             input.image,
@@ -60,10 +61,28 @@ class DockerRuntime {
         ];
     }
     ensureReady() {
-        // docker is the default; assume present. (A missing docker surfaces as a
+        // docker is the fallback; assume present. (A missing docker surfaces as a
         // clear spawn ENOENT at run time, same as pre-runtime-abstraction behavior.)
     }
 }
+const HOST_DOCKER_INTERNAL = "host.docker.internal";
+// Documentation-range IP apple/container uses to route a custom DNS name to the
+// host's localhost. See apple/container how-to: "Access a host service from a
+// container".
+const APPLE_HOST_LOCALHOST_IP = "203.0.113.113";
+function appleHostDockerInternalDnsConfigured() {
+    try {
+        const out = (0, node_child_process_1.execFileSync)("container", ["system", "dns", "list"], {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        }).toString();
+        return out.includes(HOST_DOCKER_INTERNAL);
+    }
+    catch {
+        // If we cannot inspect DNS config, do not block the run.
+        return true;
+    }
+}
 class AppleContainerRuntime {
     binary() {
         return "container";
@@ -130,6 +149,7 @@ class AppleContainerRuntime {
             ...input.envArgs,
             ...input.volumeArgs,
             ...input.userVolumeArgs,
+            ...input.portArgs,
             "-w",
             input.workdir,
             input.image,
@@ -137,38 +157,75 @@ class AppleContainerRuntime {
         ];
     }
     ensureReady() {
+        // selectRuntime() already probed `container --version` (memoized); a false
+        // here means the probe failed there too — same evidence, one exec.
+        if (!appleContainerAvailable()) {
+            console.error("harness: the `container` CLI failed its version probe (Apple container, v1.0.0+). Install from https://github.com/apple/container/releases and run `container system start`, or set HARNESS_CONTAINER_RUNTIME=docker to use docker instead.");
+            process.exit(1);
+        }
+        if (!appleHostDockerInternalDnsConfigured()) {
+            console.error(`harness: ${HOST_DOCKER_INTERNAL} is not configured for Apple's container runtime.\nLocal services on the Mac (e.g. LM Studio on :1234) will not be reachable from the container.\nOne-time fix (requires administrator):\n  sudo container system dns create ${HOST_DOCKER_INTERNAL} --localhost ${APPLE_HOST_LOCALHOST_IP}\nSee https://github.com/apple/container/blob/main/docs/how-to.md#access-a-host-service-from-a-container`);
+        }
+    }
+}
+function selectRuntime() {
+    const raw = (process.env.HARNESS_CONTAINER_RUNTIME ?? "").toLowerCase();
+    if (raw === "docker") {
+        return new DockerRuntime();
+    }
+    if (raw === "apple") {
+        // Deprecated: the apple runtime is now auto-detected on macOS. Keep the
+        // value working (with a warning) so existing configs don't hard-fail.
+        console.error('harness: HARNESS_CONTAINER_RUNTIME=apple is deprecated (the apple runtime is now auto-detected on macOS); unset the variable, or use "auto" or "docker".');
+        return new AppleContainerRuntime();
+    }
+    if (raw !== "" && raw !== "auto") {
+        console.error(`harness: unknown HARNESS_CONTAINER_RUNTIME="${raw}". Valid values: auto (default), docker, apple (deprecated) — or unset for auto-detect.`);
+        process.exit(1);
+    }
+    // Auto-detect: prefer Apple's container CLI when it actually executes —
+    // but only on macOS. apple/container ships for macOS only, so on any other
+    // platform a binary named `container` is an unrelated tool and docker stays
+    // default. Probing `--version` (not just a PATH lookup) proves the binary
+    // runs at all; broken installs, quarantine attributes, and wrong-arch
+    // builds all fail here, and execution is what selection depends on.
+    if (process.platform === "darwin" && appleContainerAvailable()) {
+        return new AppleContainerRuntime();
+    }
+    return new DockerRuntime();
+}
+/**
+ * Whether Apple's `container` CLI exists and executes. Reuses the same
+ * `--version` probe `AppleContainerRuntime.ensureReady()` runs, which is
+ * strictly stronger evidence than a PATH lookup. The result is memoized for
+ * the process lifetime so `selectRuntime()` and `ensureReady()` share one
+ * probe instead of running it twice; it is never persisted across runs, since
+ * the CLI's install state can change between invocations.
+ */
+let appleContainerAvailableMemo = null;
+function appleContainerAvailable() {
+    if (appleContainerAvailableMemo === null) {
         try {
             (0, node_child_process_1.execFileSync)("container", ["--version"], {
-                stdio: ["ignore", "ignore", "ignore"],
+                stdio: "ignore",
                 timeout: 5000,
             });
+            appleContainerAvailableMemo = true;
         }
         catch {
-            console.error("harness: HARNESS_CONTAINER_RUNTIME=apple requires the `container` CLI (Apple container, v1.0.0+). Install from https://github.com/apple/container/releases and run `container system start`, or unset HARNESS_CONTAINER_RUNTIME to use docker.");
-            process.exit(1);
+            appleContainerAvailableMemo = false;
         }
     }
-}
-function selectRuntime() {
-    const raw = (process.env.HARNESS_CONTAINER_RUNTIME ?? "docker").toLowerCase();
-    switch (raw) {
-        case "docker":
-            return new DockerRuntime();
-        case "apple":
-            return new AppleContainerRuntime();
-        default:
-            console.error(`harness: unknown HARNESS_CONTAINER_RUNTIME="${raw}". Valid values: apple, docker (or unset for docker).`);
-            process.exit(1);
-    }
+    return appleContainerAvailableMemo;
 }
 class PiAdapter {
-    buildCommand({ prompt, model, envFilePath }) {
+    buildCommand({ prompt, model, envFilePaths }) {
         // In local mode (no env file), pass --provider ollama so pi routes
         // the model to the local LM Studio provider. Without this, model names
         // containing slashes (e.g. HuggingFace IDs like "qwen/qwen3.5-9b") are
         // misinterpreted as provider/model format, causing pi to silently ignore
         // --model and fall back to a default that may require cloud credentials.
-        const providerArgs = !envFilePath && model ? ["--provider", "ollama"] : [];
+        const providerArgs = envFilePaths.length === 0 && model ? ["--provider", "ollama"] : [];
         const modelArgs = model ? ["--model", model] : [];
         if (prompt !== null) {
             return ["pi", "-p", prompt, ...providerArgs, ...modelArgs];
@@ -362,11 +419,12 @@ const USAGE = `Usage: harness [options]
 
 Options:
   -p, --prompt <text>    Pass a prompt directly to the coding agent
-  -e, --env-file <file>  Load environment variables from a file into the container
+  -e, --env-file <file>  Load environment variables from a file into the container; may be repeated
   -f, --file <file>      Mount a single file into the container instead of the current directory
   -m, --model <model>    Override the model used by the agent
   -a, --agent <name>     Select the coding agent adapter: pi, opencode, hermes (default: pi)
   -v, --volumes <spec>   Additional volume mount (host:container[:opts]); may be repeated
+  --port <spec>          Publish a container port to the host ([host-ip:]host-port:container-port[/protocol]); may be repeated
   --no-verify            Skip cosign image signature and provenance verification
   --no-skills            Disable mounting user skills directories (~/.agents/skills, ~/.claude/skills)
   --no-context-files     Disable mounting global context files (~/.agents/AGENTS.md, ~/.claude/CLAUDE.md); alias -nc
@@ -378,7 +436,7 @@ Options:
 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 to use: docker (default) or apple (Apple container CLI)
+  HARNESS_CONTAINER_RUNTIME   Container runtime: auto (default; prefers Apple container on macOS), docker, apple (deprecated)
   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)
 
@@ -424,6 +482,7 @@ const MINIMIST_OPTS = {
         "agent",
         "a",
         "volumes",
+        "port",
     ],
     alias: {
         e: "env-file",
@@ -468,7 +527,11 @@ const noSkills = argv.skills === false;
 const noContextFiles = argv["context-files"] === false;
 const mountEntireHome = argv["mount-entire-home"] === true;
 const localMode = argv.local;
-const envFilePath = argv["env-file"] || null;
+const envFilePaths = Array.isArray(argv["env-file"])
+    ? argv["env-file"]
+    : argv["env-file"]
+        ? [argv["env-file"]]
+        : [];
 const fileArg = argv.file || null;
 const promptArg = argv.prompt || null;
 const modelArg = argv.model || null;
@@ -481,9 +544,11 @@ const agentName = (() => {
     }
     return name;
 })();
-if (envFilePath && !node_fs_1.default.existsSync(envFilePath)) {
-    console.error(`harness: env file not found: ${envFilePath}`);
-    process.exit(1);
+for (const ep of envFilePaths) {
+    if (!node_fs_1.default.existsSync(ep)) {
+        console.error(`harness: env file not found: ${ep}`);
+        process.exit(1);
+    }
 }
 if (fileArg && !node_fs_1.default.existsSync(fileArg)) {
     console.error(`harness: file not found: ${fileArg}`);
@@ -522,6 +587,33 @@ for (const spec of volumeArgList) {
         process.exit(1);
     }
 }
+// Publish specs use the shared docker/apple-container syntax
+// [host-ip:]host-port:container-port[/protocol]. Validate up front so a
+// typo fails fast with a clear message instead of an opaque runtime error
+// after image verification/pulling.
+const PORT_SPEC_REGEXP = /^(?:(?:\d{1,3}(?:\.\d{1,3}){3}|\[[0-9a-fA-F:.]+\]):)?(\d{1,5}):(\d{1,5})(?:\/(tcp|udp|sctp))?$/;
+function isValidPortSpec(spec) {
+    const match = spec.match(PORT_SPEC_REGEXP);
+    if (!match) {
+        return false;
+    }
+    const portInRange = (p) => {
+        const n = Number.parseInt(p, 10);
+        return n >= 1 && n <= 65535;
+    };
+    return portInRange(match[1]) && portInRange(match[2]);
+}
+const portArgList = Array.isArray(argv.port)
+    ? argv.port
+    : argv.port
+        ? [argv.port]
+        : [];
+for (const spec of portArgList) {
+    if (!isValidPortSpec(spec)) {
+        console.error(`harness: invalid port spec "${spec}" (expected [host-ip:]host-port:container-port[/protocol], e.g. 8080:3000)`);
+        process.exit(1);
+    }
+}
 async function run(prompt) {
     const runtime = selectRuntime();
     runtime.ensureReady();
@@ -534,14 +626,15 @@ async function run(prompt) {
             await verifyImage(runtime, image);
         }
     }
-    const envFileArgs = envFilePath
-        ? ["--env-file", node_path_1.default.resolve(envFilePath)]
-        : [];
+    const envFileArgs = envFilePaths.flatMap((f) => [
+        "--env-file",
+        node_path_1.default.resolve(f),
+    ]);
     // Cloud mode: -e without --local signals entrypoints to skip local/defaults
     // and let agents auto-detect providers from env vars in the file.
-    const cloudModeEnv = envFilePath && !localMode ? ["-e", "HARNESS_CLOUD_MODE=1"] : [];
+    const cloudModeEnv = envFilePaths.length > 0 && !localMode ? ["-e", "HARNESS_CLOUD_MODE=1"] : [];
     const adapter = ADAPTERS[agentName];
-    const adapterOptions = { prompt, model: modelArg, envFilePath };
+    const adapterOptions = { prompt, model: modelArg, envFilePaths };
     const containerCmd = adapter.buildCommand(adapterOptions);
     const adapterDockerArgs = adapter.extraDockerArgs?.(adapterOptions) ?? [];
     const interactive = process.stdin.isTTY;
@@ -629,12 +722,19 @@ async function run(prompt) {
     for (const spec of volumeArgList) {
         userVolumeArgs.push("-v", `${node_path_1.default.resolve(spec.split(":")[0])}:${spec.split(":").slice(1).join(":")}`);
     }
+    // docker -p and apple/container --publish share the spec syntax, so the
+    // flags are runtime-agnostic (unlike caps/tty handling).
+    const portArgs = [];
+    for (const spec of portArgList) {
+        portArgs.push("-p", spec);
+    }
     const args = runtime.runArgs({
         interactive,
         envFileArgs,
         envArgs: [...cloudModeEnv, ...adapterDockerArgs],
         volumeArgs,
         userVolumeArgs,
+        portArgs,
         workdir: "/workspace",
         image,
         containerCmd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boldblackai/harness",
-  "version": "1.9.13",
+  "version": "1.10.0",
   "description": "Portable environment for running coding agents in a container",
   "bin": {
     "harness": "bin/harness.js"