@boldblackai/harness 1.8.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julio Capote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+<p align="center" style="margin-bottom: 0">
+  <img alt="harness" src="logo-light.png#gh-light-mode-only" width="250">
+  <img alt="harness" src="logo-dark.png#gh-dark-mode-only" width="250">
+</p>
+
+<p align="center">
+  <strong>Run agents in a sandboxed container — ready to drop into any project.</strong>
+</p>
+
+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/)
+
+## Features
+
+- **Sandboxed by default** — capability-dropped container with `no-new-privileges`; the agent only sees the directory (or file) you mount.
+- **Three agents, one CLI** — switch between `pi`, `opencode`, and `hermes` with `-a`. Same flags, same flow.
+- **Supply-chain hardened** — the image is signed and verified with cosign and SLSA provenance on every run; dependencies installed inside the container are always pinned and verified where possible and a 7-day "cooldown" is used to mitigate supply-chain attacks.
+- **Local-first** — defaults to LM Studio with `gemma-4-e4b`. Drop in an `--env-file` to use Anthropic, OpenRouter, OpenAI, Gemini, and others.
+- **Stateful or one-shot** — interactive runs persist agent state under `$XDG_DATA_HOME/harness/<project>/<agent>/` (defaults to `~/.local/share/harness/`); one-shot prompts (`-p` or piped stdin) stay ephemeral.
+- **User skills** — automatically mounts `~/.agents/skills` and `~/.claude/skills` into the container so agents can discover and use custom skills. Disable with `--no-skills`.
+- **Context files** — automatically mounts `~/.agents/AGENTS.md` and `~/.claude/CLAUDE.md` into the agent's context directory so cross-agent rules apply inside the container. Disable with `--no-context-files` (`-nc`).
+- **Zero install** — `npx @boldblackai/harness` just works.
+
+## Quickstart
+
+[Docker](https://www.docker.com) is required. By default, harness uses LM Studio locally:
+
+```bash
+lms daemon up
+lms get google/gemma-4-e4b
+```
+
+The container is preconfigured to use `gemma-4-e4b` via LM Studio's local API.
+
+You can also specify a different local model with `-m`. HuggingFace-style names with slashes (e.g. `qwen/qwen3.5-9b`) work correctly in local mode:
+
+```bash
+npx @boldblackai/harness -m "qwen/qwen3.5-9b" -p "write a fizzbuzz in Go"
+```
+
+### Using a cloud provider instead
+
+#### pi (default agent)
+
+If you pass an API key for a supported provider via `--env-file`, [`pi`](https://pi.dev/) will use that provider instead of the local LM Studio setup. Supported keys:
+
+| Provider | Environment Variable |
+|----------|----------------------|
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| Mistral | `MISTRAL_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| Cerebras | `CEREBRAS_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| Hugging Face | `HF_TOKEN` |
+
+See the [full list of supported providers](https://github.com/badlogic/pi-mono/blob/c779c14e91bc2ea65143e59b0dc1baf3646ba8c9/packages/coding-agent/docs/providers.md#api-keys) for more options. When using LM Studio locally, 16k context is sufficient.
+
+#### opencode agent
+
+[`opencode`](https://opencode.ai) uses LM Studio by default. Pass `--env-file` to switch to cloud mode — the agent auto-detects the provider from whichever API key is in the file:
+
+```bash
+echo 'OPENROUTER_API_KEY=sk-...' > .env
+npx @boldblackai/harness -e .env -p "write me a fizzbuzz in Go"
+```
+
+That's it. Your current directory is mounted at `/workspace` inside the container and the agent works against it.
+
+## Contents
+
+- [Examples](#examples)
+- [Agents](#agents)
+  - [pi (default)](#pi-default)
+  - [opencode](#opencode)
+  - [hermes](#hermes)
+- [Security model](#security-model)
+  - [Sandbox](#sandbox)
+  - [Image verification](#image-verification)
+  - [Dependency cooldown](#dependency-cooldown)
+- [Persistence](#persistence)
+- [Reference](#reference)
+  - [CLI flags](#cli-flags)
+  - [Environment variables](#environment-variables)
+  - [Agent-specific behavior](#agent-specific-behavior)
+- [Deploying hermes as a claw](#deploying-hermes-as-a-claw)
+- [Developing](#developing)
+
+## Examples
+
+```bash
+# One-shot prompt
+npx @boldblackai/harness -p "write me a fizzbuzz in Go"
+
+# Pipe via stdin
+echo "write me a fizzbuzz in Go" | npx @boldblackai/harness
+
+# Interactive session (no -p, no piped stdin) — state persists under XDG data dir
+npx @boldblackai/harness
+
+# Use a cloud provider via env file
+npx @boldblackai/harness -e .env -p "add a login endpoint"
+
+# Override the model
+npx @boldblackai/harness -m anthropic/claude-sonnet-4-5 -p "refactor the auth module"
+
+# Mount a single file instead of the whole directory
+npx @boldblackai/harness -f ./script.py -p "add type hints"
+
+# Switch agents
+npx @boldblackai/harness -a opencode -p "write me a fizzbuzz in Go"
+npx @boldblackai/harness -a hermes -e .env -p "add tests"
+```
+
+`npx`, `bunx`, and `pnpm dlx` are interchangeable. Or install globally:
+
+```bash
+npm install -g @boldblackai/harness
+# or
+pnpm add -g @boldblackai/harness
+# or
+bun add -g @boldblackai/harness
+```
+
+## Agents
+
+Pick an agent with `-a`. Default is `pi`.
+
+### pi (default)
+
+[`pi`](https://pi.dev/) defaults to LM Studio with `google/gemma-4-e4b` (16k context is enough). Pass an `--env-file` containing any of the keys below and `pi` switches to that provider:
+
+| Provider      | Environment Variable |
+|---------------|----------------------|
+| Anthropic     | `ANTHROPIC_API_KEY`  |
+| OpenRouter    | `OPENROUTER_API_KEY` |
+| OpenAI        | `OPENAI_API_KEY`     |
+| Google Gemini | `GEMINI_API_KEY`     |
+| Mistral       | `MISTRAL_API_KEY`    |
+| Groq          | `GROQ_API_KEY`       |
+| Cerebras      | `CEREBRAS_API_KEY`   |
+| xAI           | `XAI_API_KEY`        |
+| Hugging Face  | `HF_TOKEN`           |
+
+See the [full provider list](https://github.com/badlogic/pi-mono/blob/c779c14e91bc2ea65143e59b0dc1baf3646ba8c9/packages/coding-agent/docs/providers.md#api-keys). The `-m` flag is forwarded directly.
+
+### opencode
+
+[`opencode`](https://opencode.ai) defaults to LM Studio in local mode. Pass `--env-file` to enter cloud mode — the agent auto-detects the provider from whichever API key is in the file (`ZAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, etc.). The `-m` flag takes a bare model name; the provider prefix is added for you.
+
+```bash
+npx @boldblackai/harness -a opencode -e .env -p "refactor the auth module"
+npx @boldblackai/harness -a opencode -e .env -m anthropic/claude-sonnet-4-5 -p "add tests"
+```
+
+To pass env vars but stay in local mode, use `--local`:
+
+```bash
+npx @boldblackai/harness -a opencode -e .env --local -p "refactor the auth module"
+```
+
+When using LM Studio locally, set the model's context length to at least 32k tokens.
+
+### hermes
+
+[`hermes`](https://github.com/NousResearch/hermes-agent) by NousResearch supports many providers. Pass `--env-file` to enter cloud mode — the agent auto-detects the provider from whichever API key is in the file. Use a `provider/model` for `-m`:
+
+```bash
+npx @boldblackai/harness -a hermes -e .env -m anthropic/claude-sonnet-4-5 -p "add tests"
+npx @boldblackai/harness -a hermes -e .env -m openrouter/auto -p "add tests"
+```
+
+Common keys: `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, [and others](https://github.com/NousResearch/hermes-agent/blob/main/.env.example). LM Studio context length should be at least 64k tokens.
+
+## Security model
+
+Harness layers protections at runtime, image, and dependency level.
+
+### Sandbox
+
+Each run starts the container with:
+
+- `--cap-drop=ALL --cap-add=NET_RAW` — minimal capability set
+- `--security-opt no-new-privileges:true` — block privilege escalation
+- `--security-opt seccomp=...` — inline seccomp profile blocks `socket(AF_ALG)` to prevent kernel crypto API access (a known container escape vector)
+- Only your mounted directory (or single file with `-f`) is visible to the agent
+
+### Image verification
+
+By default, harness verifies that the container image was signed by the official CI workflow and carries a valid SLSA provenance attestation. This requires [cosign](https://github.com/sigstore/cosign):
+
+```bash
+brew install cosign
+```
+
+Verified digests are cached at `~/.cache/harness/cosign-verified.json` so verification only runs once per image. Skip with `--no-verify` (or by setting `HARNESS_IMAGE_TAG`, which implies skip):
+
+```bash
+npx @boldblackai/harness --no-verify -p "write me a fizzbuzz in Go"
+```
+
+### Dependency cooldown
+
+The image build enforces a 7-day cooldown on dependency resolution — a guard against supply-chain compromises that are typically discovered and yanked within hours.
+
+- **pnpm**: `PNPM_MINIMUM_RELEASE_AGE=10080` (minutes) via environment variable
+- **uv**: `--exclude-newer` set to 7 days ago at image build time
+
+The cooldown applies to transitive dependencies too. Older packages install normally.
+
+## Persistence
+
+Interactive runs (no `-p` and no piped stdin) store persistence data at `$XDG_DATA_HOME/harness/<project>/<agent>/` (defaults to `~/.local/share/harness/`). The `<project>` segment is the working directory path with `/` replaced by `_` and the home prefix stripped. This lets agents resume sessions, skip database migrations on repeat runs, and retain memories across invocations. The container's `~/.config` is persisted at `<persist-root>/../xdg_config` (one level above the per-agent root, i.e. `$XDG_DATA_HOME/harness/<project>/xdg_config`), so tool configs (e.g. jj) survive across runs and are shared by every agent working in the same project. For the opencode adapter the existing per-agent `.config/opencode` mount nests inside this project-level one. Per-agent `mise` tool data and trust settings are persisted at `<persist-root>/mise/` and `<persist-root>/mise-state/` respectively. For the pi adapter, extensions/skills installed via `npm install -g` are persisted at `<persist-root>/npm/`, avoiding re-downloads on every boot.
+
+One-shot runs (`-p` or piped stdin) are implicitly ephemeral — no persistence data is created. Use `--ephemeral` to force-disable persistence on interactive runs.
+
+If an old `.harness/` directory exists in your working directory, harness will emit a deprecation warning with migration instructions.
+
+## Reference
+
+### CLI flags
+
+| Flag          | Alias | Description |
+|---------------|-------|-------------|
+| `--prompt`    | `-p`  | Pass a prompt directly to the agent |
+| `--env-file`  | `-e`  | Load environment variables into the container |
+| `--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 |
+| `--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`) |
+| `--ephemeral` |       | Disable session persistence (implied by `-p` and piped stdin) |
+| `--local`     |       | Force local mode even with `-e` (use LM Studio / local defaults) |
+| `--help`      | `-h`  | Show help |
+
+### Environment variables
+
+| Variable             | Description |
+|----------------------|-------------|
+| `HARNESS_IMAGE_TAG`  | Override the Docker image tag (defaults to the package version). Setting this implies `--no-verify`. |
+
+### Agent-specific behavior
+
+- **pi** — `-m` is passed straight to the binary as `--model`.
+- **opencode** — `-m` is passed via the `OPENCODE_MODEL` env var. Without `-e`, uses LM Studio locally. With `-e`, enters cloud mode and auto-detects the provider from whichever API key is in the env file. Use `--local` to force local mode even with `-e`.
+- **hermes** — `-m` is passed as `--model` in `provider/model` form. Without `-e`, uses local config. With `-e`, enters cloud mode and auto-detects from env vars. Use `--local` to force local mode even with `-e`.
+
+## Deploying hermes as a claw
+
+You can run `hermes` as a long-running "claw" — a persistent agent process reachable over a messaging gateway (e.g. Telegram). Three deployment targets are documented:
+
+- [fly.io](docs/deploying-to-fly.md)
+- [Kubernetes](docs/deploying-to-k8s.md)
+- [AWS (ECS Fargate or EC2 + SSM)](docs/deploying-to-aws.md)
+
+## Developing
+
+Link your local checkout globally:
+
+```bash
+pnpm link --global
+# unlink with:
+pnpm unlink --global @boldblackai/harness
+```
+
+### Building the image
+
+```bash
+make image
+```
+
+Builds `ghcr.io/boldblackai/harness` with Debian stable-slim, Node.js v24, `git`, [`@earendil-works/pi-coding-agent`](https://pi.dev/), [`opencode-ai`](https://opencode.ai), [`hermes-agent`](https://github.com/NousResearch/hermes-agent), `fd`, `ripgrep`, `jq`, and `curl`. The hermes variant also includes the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) for connecting to MCP servers, and [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) for local speech-to-text.
+
+The base image is pinned by manifest-list digest (the OCI image index, not a per-platform manifest) for reproducible multi-arch builds. To bump it:
+
+```bash
+docker buildx imagetools inspect debian:stable-slim --format '{{.Manifest.Digest}}'
+```
+
+### Linting
+
+```bash
+pnpm lint           # all
+pnpm lint:ts        # Biome
+pnpm lint:md        # markdownlint
+pnpm lint:sh        # shellcheck
+pnpm lint:docker    # hadolint
+pnpm lint:actions   # actionlint
+pnpm format         # auto-format with Biome
+```
+
+`shellcheck`, `hadolint`, and `actionlint` are system binaries. Install with [mise](https://mise.jdx.dev/) (recommended):
+
+```bash
+mise install
+```
+
+Or install manually:
+
+```bash
+brew install shellcheck hadolint actionlint
+```

package/bin/harness.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/harness.js

@@ -0,0 +1,516 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const minimist_1 = __importDefault(require("minimist"));
+const SECCOMP_PROFILE = node_path_1.default.join(__dirname, "seccomp-profiles", "block-af-alg.json");
+class PiAdapter {
+    buildCommand({ prompt, model, envFilePath }) {
+        // 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 modelArgs = model ? ["--model", model] : [];
+        if (prompt !== null) {
+            return ["pi", "-p", prompt, ...providerArgs, ...modelArgs];
+        }
+        return ["pi", ...providerArgs, ...modelArgs];
+    }
+    persistMounts() {
+        return [
+            { hostSubpath: "", containerPath: "/home/harness/.pi/agent" },
+            { hostSubpath: "npm", containerPath: "/home/harness/.local/share/npm" },
+        ];
+    }
+    contextDir() {
+        return "/home/harness/.pi/agent";
+    }
+}
+class OpenCodeAdapter {
+    buildCommand({ prompt }) {
+        if (prompt !== null) {
+            return ["opencode", "run", prompt];
+        }
+        return ["opencode"];
+    }
+    extraDockerArgs({ model }) {
+        return model ? ["-e", `OPENCODE_MODEL=${model}`] : [];
+    }
+    persistMounts() {
+        return [
+            {
+                hostSubpath: "config",
+                containerPath: "/home/harness/.config/opencode",
+            },
+            {
+                hostSubpath: "share",
+                containerPath: "/home/harness/.local/share/opencode",
+            },
+            {
+                hostSubpath: "state",
+                containerPath: "/home/harness/.local/state/opencode",
+            },
+        ];
+    }
+    contextDir() {
+        return "/home/harness/.config/opencode";
+    }
+}
+class HermesAdapter {
+    buildCommand({ prompt, model }) {
+        const args = ["hermes", "chat"];
+        if (model)
+            args.push("-m", model);
+        if (prompt !== null)
+            args.push("-q", prompt);
+        return args;
+    }
+    persistMounts() {
+        return [{ hostSubpath: "", containerPath: "/home/harness/.hermes" }];
+    }
+    contextDir() {
+        return "/home/harness/.hermes";
+    }
+}
+const IDENTITY_REGEXP = "https://github.com/boldblackai/harness/.github/workflows/docker.yml@refs/tags/";
+const OIDC_ISSUER = "https://token.actions.githubusercontent.com";
+const CACHE_VERSION = 1;
+function cachePath() {
+    const base = process.env.XDG_CACHE_HOME || node_path_1.default.join(node_os_1.default.homedir(), ".cache");
+    return node_path_1.default.join(base, "harness", "cosign-verified.json");
+}
+function inspectLocalImage(image) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)("docker", [
+            "image",
+            "inspect",
+            "--format",
+            "{{if .RepoDigests}}{{index .RepoDigests 0}}{{end}}",
+            image,
+        ], { stdio: ["ignore", "pipe", "ignore"], timeout: 5000 })
+            .toString()
+            .trim();
+        return {
+            exists: true,
+            digest: /@sha256:[0-9a-f]{64}$/.test(out) ? out : null,
+        };
+    }
+    catch {
+        return { exists: false, digest: null };
+    }
+}
+function readCache() {
+    try {
+        const raw = node_fs_1.default.readFileSync(cachePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            parsed.version === CACHE_VERSION &&
+            parsed.verified &&
+            typeof parsed.verified === "object") {
+            return parsed;
+        }
+    }
+    catch { }
+    return { version: CACHE_VERSION, verified: {} };
+}
+function writeCacheAtomic(cache) {
+    try {
+        const file = cachePath();
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true, mode: 0o700 });
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        node_fs_1.default.writeFileSync(tmp, JSON.stringify(cache, null, 2), { mode: 0o600 });
+        node_fs_1.default.renameSync(tmp, file);
+    }
+    catch {
+        // best-effort; never break verify path
+    }
+}
+function cosign(args) {
+    return new Promise((resolve, reject) => {
+        (0, node_child_process_1.execFile)("cosign", args, { timeout: 30000 }, (err, _stdout, stderr) => {
+            if (err) {
+                const e = err;
+                e.stderr = stderr;
+                reject(e);
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}
+async function verifyImage(image) {
+    let { exists, digest: digestRef } = inspectLocalImage(image);
+    const cache = readCache();
+    if (digestRef && cache.verified[digestRef]) {
+        return;
+    }
+    if (exists && !digestRef) {
+        console.error(`harness: refusing to verify ${image}: image exists locally but has no registry digest (locally-built?).`);
+        console.error("harness: verifying the tag would check registry bytes, not the local image docker would run.");
+        console.error("harness: use --no-verify, or set HARNESS_IMAGE_TAG for an implicit skip.");
+        process.exit(1);
+    }
+    if (!digestRef) {
+        console.error(`harness: pulling ${image} for verification...`);
+        try {
+            (0, node_child_process_1.execFileSync)("docker", ["pull", image], {
+                stdio: ["ignore", "inherit", "inherit"],
+                timeout: 600000,
+            });
+        }
+        catch {
+            console.error(`harness: docker pull failed for ${image}`);
+            process.exit(1);
+        }
+        digestRef = inspectLocalImage(image).digest;
+        if (!digestRef) {
+            console.error(`harness: failed to resolve digest for ${image} after pull`);
+            process.exit(1);
+        }
+        if (cache.verified[digestRef]) {
+            return;
+        }
+    }
+    const identityArgs = [
+        "--certificate-identity-regexp",
+        IDENTITY_REGEXP,
+        "--certificate-oidc-issuer",
+        OIDC_ISSUER,
+    ];
+    const verifyP = cosign(["verify", ...identityArgs, digestRef]);
+    const attestP = cosign([
+        "verify-attestation",
+        "--type",
+        "slsaprovenance",
+        ...identityArgs,
+        digestRef,
+    ]);
+    const [verifyResult, attestResult] = await Promise.allSettled([
+        verifyP,
+        attestP,
+    ]);
+    if (verifyResult.status === "rejected") {
+        const e = verifyResult.reason;
+        if (e.code === "ENOENT") {
+            console.error("harness: cosign not found — cannot verify image without it.");
+            console.error("harness: install cosign (brew install cosign) or pass --no-verify to skip verification.");
+            process.exit(1);
+        }
+        console.error(`harness: image signature verification failed for ${digestRef}`);
+        console.error(e.stderr?.trim() || e.message);
+        process.exit(1);
+    }
+    if (attestResult.status === "rejected") {
+        console.error(`harness: WARNING: no provenance attestation found for ${digestRef}`);
+    }
+    cache.verified[digestRef] = {
+        tag: image,
+        verifiedAt: new Date().toISOString(),
+    };
+    writeCacheAtomic(cache);
+}
+const AGENT_NAMES = ["pi", "opencode", "hermes"];
+const ADAPTERS = {
+    pi: new PiAdapter(),
+    opencode: new OpenCodeAdapter(),
+    hermes: new HermesAdapter(),
+};
+function isAgentName(name) {
+    return AGENT_NAMES.includes(name);
+}
+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
+  -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
+  --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
+  --ephemeral            Disable session persistence (implied by -p and piped stdin)
+  --local                Force local mode even with -e (use LM Studio / local defaults)
+  -h, --help             Show this help message
+
+Environment variables:
+  HARNESS_IMAGE_TAG      Override the Docker image tag (defaults to package version)
+  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)
+
+Persistence data is stored at $XDG_DATA_HOME/harness/<project>/<agent>/.
+
+You can also pipe text to harness as an implied -p:
+  echo "write me a fizzbuzz in Go" | harness
+`;
+const workspace = process.cwd();
+const REGISTRY = "ghcr.io/boldblackai/harness";
+const VERSION = require("../package.json").version;
+const IMAGE_TAG = process.env.HARNESS_IMAGE_TAG ?? VERSION;
+function normalizeCwd(cwd) {
+    const home = node_os_1.default.homedir();
+    let normalized = cwd;
+    if (normalized.startsWith(home)) {
+        normalized = normalized.slice(home.length);
+    }
+    normalized = normalized.replace(/\//g, "_");
+    if (normalized === "") {
+        normalized = "_home";
+    }
+    return normalized;
+}
+function xdgDataDir() {
+    return (process.env.XDG_DATA_HOME || node_path_1.default.join(node_os_1.default.homedir(), ".local", "share"));
+}
+function getImage(agent) {
+    const tag = agent === "pi" ? IMAGE_TAG : `${agent}-${IMAGE_TAG}`;
+    return `${REGISTRY}:${tag}`;
+}
+const MINIMIST_OPTS = {
+    boolean: ["help", "h", "ephemeral", "local"],
+    string: [
+        "env-file",
+        "e",
+        "file",
+        "f",
+        "prompt",
+        "p",
+        "model",
+        "m",
+        "agent",
+        "a",
+        "volumes",
+    ],
+    alias: {
+        e: "env-file",
+        f: "file",
+        p: "prompt",
+        m: "model",
+        h: "help",
+        a: "agent",
+        v: "volumes",
+    },
+};
+// Translate pi's short context-files flag (-nc) to its long form before
+// minimist, which would otherwise split -nc into clustered -n -c flags.
+const rawArgs = process.argv
+    .slice(2)
+    .map((a) => (a === "-nc" ? "--no-context-files" : a));
+const argv = (0, minimist_1.default)(rawArgs, MINIMIST_OPTS);
+// Warn on unrecognized flags
+{
+    const knownKeys = new Set([
+        "_", // minimist internal positional args
+        ...MINIMIST_OPTS.boolean,
+        ...MINIMIST_OPTS.string,
+        ...Object.keys(MINIMIST_OPTS.alias),
+        ...Object.values(MINIMIST_OPTS.alias),
+        "verify", // --no-verify sets verify=false
+        "skills", // --no-skills sets skills=false
+        "context-files", // --no-context-files / -nc sets context-files=false
+        "local",
+    ]);
+    const unknown = Object.keys(argv).filter((k) => !knownKeys.has(k));
+    if (unknown.length > 0) {
+        process.stderr.write(`warning: unrecognized flag(s): ${unknown.map((k) => `--${k}`).join(", ")}\n`);
+    }
+}
+if (argv.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+}
+const noVerify = argv.verify === false;
+const noSkills = argv.skills === false;
+const noContextFiles = argv["context-files"] === false;
+const localMode = argv.local;
+const envFilePath = argv["env-file"] || null;
+const fileArg = argv.file || null;
+const promptArg = argv.prompt || null;
+const modelArg = argv.model || null;
+const effectiveEphemeral = argv.ephemeral || promptArg !== null || !process.stdin.isTTY;
+const agentName = (() => {
+    const name = argv.agent ?? "pi";
+    if (!isAgentName(name)) {
+        console.error(`harness: unknown agent: "${name}". Available: ${Object.keys(ADAPTERS).join(", ")}`);
+        process.exit(1);
+    }
+    return name;
+})();
+if (envFilePath && !node_fs_1.default.existsSync(envFilePath)) {
+    console.error(`harness: env file not found: ${envFilePath}`);
+    process.exit(1);
+}
+if (fileArg && !node_fs_1.default.existsSync(fileArg)) {
+    console.error(`harness: file not found: ${fileArg}`);
+    process.exit(1);
+}
+if (fileArg && node_fs_1.default.statSync(fileArg).isDirectory()) {
+    console.error(`harness: --file requires a file, not a directory: ${fileArg}`);
+    process.exit(1);
+}
+const volumeArgList = Array.isArray(argv.volumes)
+    ? argv.volumes
+    : argv.volumes
+        ? [argv.volumes]
+        : [];
+for (const spec of volumeArgList) {
+    const parts = spec.split(":");
+    if (parts.length < 2) {
+        console.error(`harness: invalid volume spec "${spec}" (expected host:container[:opts])`);
+        process.exit(1);
+    }
+    if (parts[0] && !node_fs_1.default.existsSync(parts[0])) {
+        console.error(`harness: volume source path does not exist: ${parts[0]}`);
+        process.exit(1);
+    }
+}
+async function run(prompt) {
+    const image = getImage(agentName);
+    if (!noVerify) {
+        if (process.env.HARNESS_IMAGE_TAG) {
+            console.error(`harness: HARNESS_IMAGE_TAG is set; skipping cosign verification for ${image}`);
+        }
+        else {
+            await verifyImage(image);
+        }
+    }
+    const envFileArgs = envFilePath
+        ? ["--env-file", node_path_1.default.resolve(envFilePath)]
+        : [];
+    // 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 adapter = ADAPTERS[agentName];
+    const adapterOptions = { prompt, model: modelArg, envFilePath };
+    const containerCmd = adapter.buildCommand(adapterOptions);
+    const adapterDockerArgs = adapter.extraDockerArgs?.(adapterOptions) ?? [];
+    const interactive = process.stdin.isTTY;
+    const ttyFlags = interactive ? ["-it"] : ["-i"];
+    let volumeArgs;
+    if (fileArg) {
+        const absFile = node_path_1.default.resolve(fileArg);
+        const fileName = node_path_1.default.basename(absFile);
+        volumeArgs = ["-v", `${absFile}:/workspace/${fileName}`];
+    }
+    else {
+        volumeArgs = ["-v", `${workspace}:/workspace`];
+        if (!effectiveEphemeral) {
+            const persistRoot = node_path_1.default.join(xdgDataDir(), "harness", normalizeCwd(workspace), agentName);
+            // Deprecation warning for old .harness/ directory
+            const oldHarnessDir = node_path_1.default.join(workspace, ".harness");
+            if (node_fs_1.default.existsSync(oldHarnessDir)) {
+                console.error(`harness: WARNING: found ${oldHarnessDir}/ — persistence data now lives at ${persistRoot}. To migrate session data, copy the contents of .harness/${agentName}/ to the new location. Otherwise this directory can be safely deleted.`);
+            }
+            const mounts = adapter.persistMounts?.() ?? [];
+            for (const mount of mounts) {
+                const hostFullPath = node_path_1.default.join(persistRoot, mount.hostSubpath);
+                node_fs_1.default.mkdirSync(hostFullPath, { recursive: true });
+                volumeArgs.push("-v", `${hostFullPath}:${mount.containerPath}`);
+            }
+            // Project-level (agent-independent) XDG config persistence. Tools like
+            // jj write to ~/.config; persisting it one level above the per-agent
+            // persistRoot lets that config survive across runs and be shared by every
+            // agent working in this project. For opencode the more-specific
+            // .config/opencode mount above nests inside this one (Docker mounts
+            // parents before children), so opencode keeps its own per-agent bucket.
+            const xdgConfigPath = node_path_1.default.join(node_path_1.default.dirname(persistRoot), "xdg_config");
+            node_fs_1.default.mkdirSync(xdgConfigPath, { recursive: true });
+            volumeArgs.push("-v", `${xdgConfigPath}:/home/harness/.config`);
+            // Per-agent mise persistence (data: tools/plugins, state: trust settings)
+            const miseDataPath = node_path_1.default.join(persistRoot, "mise");
+            node_fs_1.default.mkdirSync(miseDataPath, { recursive: true });
+            volumeArgs.push("-v", `${miseDataPath}:/home/harness/.local/share/mise`);
+            const miseStatePath = node_path_1.default.join(persistRoot, "mise-state");
+            node_fs_1.default.mkdirSync(miseStatePath, { recursive: true });
+            volumeArgs.push("-v", `${miseStatePath}:/home/harness/.local/state/mise`);
+        }
+    }
+    if (!noSkills) {
+        const skillDirs = [
+            {
+                host: node_path_1.default.resolve(node_os_1.default.homedir(), ".agents", "skills"),
+                container: "/home/harness/.agents/skills",
+            },
+            {
+                host: node_path_1.default.resolve(node_os_1.default.homedir(), ".claude", "skills"),
+                container: "/home/harness/.claude/skills",
+            },
+        ];
+        for (const sd of skillDirs) {
+            if (node_fs_1.default.existsSync(sd.host) && node_fs_1.default.statSync(sd.host).isDirectory()) {
+                volumeArgs.push("-v", `${sd.host}:${sd.container}`);
+            }
+        }
+    }
+    // Mount the user's global context files into the adapter's context directory
+    // so cross-agent rules apply inside the container. Mirrors pi's context-files
+    // model (AGENTS.md + CLAUDE.md). Each file is skipped when absent (like skills
+    // dirs); --no-context-files / -nc disables all of them.
+    if (!noContextFiles) {
+        const contextDir = adapter.contextDir?.();
+        if (contextDir) {
+            const contextFiles = [
+                {
+                    host: node_path_1.default.resolve(node_os_1.default.homedir(), ".agents", "AGENTS.md"),
+                    name: "AGENTS.md",
+                },
+                {
+                    host: node_path_1.default.resolve(node_os_1.default.homedir(), ".claude", "CLAUDE.md"),
+                    name: "CLAUDE.md",
+                },
+            ];
+            for (const cf of contextFiles) {
+                if (node_fs_1.default.existsSync(cf.host) && node_fs_1.default.statSync(cf.host).isFile()) {
+                    volumeArgs.push("-v", `${cf.host}:${contextDir}/${cf.name}`);
+                }
+            }
+        }
+    }
+    const userVolumeArgs = [];
+    for (const spec of volumeArgList) {
+        userVolumeArgs.push("-v", `${node_path_1.default.resolve(spec.split(":")[0])}:${spec.split(":").slice(1).join(":")}`);
+    }
+    const args = [
+        "run",
+        "--rm",
+        ...ttyFlags,
+        "--cap-drop=ALL",
+        "--cap-add=NET_RAW",
+        "--security-opt",
+        "no-new-privileges:true",
+        "--security-opt",
+        `seccomp=${SECCOMP_PROFILE}`,
+        ...envFileArgs,
+        ...cloudModeEnv,
+        ...adapterDockerArgs,
+        ...volumeArgs,
+        ...userVolumeArgs,
+        "-w",
+        "/workspace",
+        image,
+        ...containerCmd,
+    ];
+    const docker = (0, node_child_process_1.spawn)("docker", args, { stdio: "inherit" });
+    docker.on("exit", (code) => process.exit(code ?? 1));
+}
+if (!process.stdin.isTTY && promptArg === null) {
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+        input += chunk;
+    });
+    process.stdin.on("end", () => run(input.trim() ? input : null).catch(() => process.exit(1)));
+}
+else {
+    run(promptArg).catch(() => process.exit(1));
+}

package/bin/seccomp-profiles/block-af-alg.json

@@ -0,0 +1,10 @@
+{
+  "defaultAction": "SCMP_ACT_ALLOW",
+  "syscalls": [
+    {
+      "names": ["socket"],
+      "action": "SCMP_ACT_ERRNO",
+      "args": [{ "index": 0, "op": "SCMP_CMP_EQ", "value": 38 }]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@boldblackai/harness",
+  "version": "1.8.5",
+  "description": "Portable environment for running coding agents in a container",
+  "bin": {
+    "harness": "bin/harness.js"
+  },
+  "files": ["bin/"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boldblackai/harness.git"
+  },
+  "packageManager": "pnpm@10.33.2",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && cp -r src/seccomp-profiles bin/seccomp-profiles",
+    "prepare": "tsc",
+    "lint": "pnpm lint:ts && pnpm lint:md && pnpm lint:sh && pnpm lint:docker && pnpm lint:actions",
+    "lint:ts": "biome check .",
+    "lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\"",
+    "lint:sh": "shellcheck entrypoint.sh entrypoint-opencode.sh entrypoint-hermes.sh",
+    "lint:docker": "hadolint Dockerfile Dockerfile.opencode Dockerfile.hermes",
+    "lint:actions": "actionlint",
+    "format": "biome format --write .",
+    "test:e2e:cli": "node --test tests/e2e/cli.test.mjs",
+    "test:e2e": "node --test tests/e2e/cli.test.mjs",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**\" --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 tests/e2e/cli.test.mjs"
+  },
+  "dependencies": {
+    "minimist": "^1.2.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^25.6.0",
+    "markdownlint-cli2": "0.17.2",
+    "typescript": "^6.0.2"
+  }
+}