🏗️ Open Harness

Open Harness provides the sandbox; you choose the harness. It's a Docker-based workspace, agent-tended over time: one agro sandbox install docker boots a long-lived container where the coding agent of your choice — Claude Code, Codex, Pi, Hermes, Grok, and more, each installed with one agro harness install command — works on its own branch and identity. Because it's just Docker, it runs identically on your laptop or a remote VM — and remote is the default: deployed on a VM, Open Harness becomes a lights-out software factory, where the agent works unattended, on a schedule and reachable over Slack, fanning out across isolated git worktrees — parallel branches, delegated sub-agents, even other cloned repos — while you're away and your laptop stays clean.

• One project, one sandbox. A single container scoped to a single repo. The agent owns its branch and its workspace; you keep your laptop clean.
• Parallel by design. The worktrees skill fans one sandbox into isolated git worktrees — parallel branches, delegated sub-agents, even other cloned repos.
• Remote-first, lights-out. Runs the same on your laptop or a cloud VM; on a VM it's an unattended software factory — agents build on a schedule, reachable over Slack.
• Agents that work while you sleep. A tiny croner runtime reads crons/*.md markdown and wakes the agent on a schedule.
• Host dependencies: Docker, Git, and Node.js ≥ 20. No Python, no pnpm, no agent CLIs, no toolchain rot on your laptop — Node runs the agro CLI and nothing else. (get-agro.sh installs Node for you if you don't have it — see Prerequisites.) The same agro verbs work on the host and inside the sandbox — see lifecycle commands.
• Composable infra. Cherry-pick Cloudflare tunnels, SSH, Caddy gateway, or pack-supplied services via Compose overlays.
• Slack-ready. The pi-messenger-bridge package bridges Slack (and other messengers) to a Pi agent — see docs/integrations/slack.md.
• Herdr-first interactive work. Nothing installs at boot: every harness and tool arrives through agro harness install <id> or agro tool install <id>. After entering the sandbox, install and run Herdr first; keep setup, agents, tests, and servers organized in its persistent panes. Headless Slack and cron infrastructure remain independent.

📖 Read the docs → https://oh.mifune.dev
Rendered, searchable docs, guides, and blog. New here? Start with the Start Here hub.

📦 Install

Open Harness runs one project in one Docker sandbox, and agro is the only
front door. Host prerequisites: Docker (with the Compose plugin), Git, and
Node.js ≥ 20.

1. Get agro

npm — you already have Node ≥ 20:

npm install -g @mifune/agro   # puts `agro` on your PATH

curl — no Node yet; the bootstrap downloads the prebuilt agro artifact from
the latest GitHub release (nothing is cloned or built on your host) and offers to
install nvm + Node 22 for you:

curl -fsSL https://github.com/mifunedev/openharness/releases/latest/download/get-agro.sh | bash

Review-first (download, read, then run — no extra dependency):

curl -fsSL -o get-agro.sh https://github.com/mifunedev/openharness/releases/latest/download/get-agro.sh
# Review get-agro.sh in your editor or pager before running it.
bash get-agro.sh

It installs to ~/.local/bin/agro; AGRO_BIN_DIR overrides the location, and
export PATH="$HOME/.local/bin:$PATH" puts it on an already-open shell's PATH.
agro update upgrades it later. oh remains the compatibility alias for the
same executable — npm install -g @mifune/openharness or the get-oh.sh
bootstrap — and every agro verb below also works as oh <verb>; see
AGRO compatibility and
Installation.

2. Create the sandbox

agro sandbox install docker runs from any directory — it needs no project
checkout:

agro sandbox install docker   # wizard: name, timezone, git identity, SSH, Docker socket
agro shell <name>             # attach as the sandbox user

The wizard's answers land in a registry entry at
~/.oh/sandboxes/<name>/oh.json, beside the compose files and the wrapper
script the CLI regenerates on every lifecycle call. The default name is
oh-sbx-<n>; --yes keeps every default and asks nothing. Without --repo the
sandbox runs the published image and seeds its workspace from it.

Mount a project instead. Point the sandbox at a checkout and it is
bind-mounted at /home/sandbox/harness:

agro sandbox install docker --repo ~/my-project --name my-project

Equip that checkout with the control plane first — cd ~/my-project && oh update writes .oh/ and crons/ and nothing else: no AGENTS.md, no
provider configuration, no .gitignore line beyond the .env line
agro secret set adds. Those files stay yours.

Then, inside the sandbox, install and open the persistent interactive workspace
first — a fresh sandbox has no herdr, because nothing installs at boot:

agro tool install herdr
herdr

Run the remaining setup, authentication, agents, tests, and servers from its
panes. That is already a working sandbox. To make it yours (private origin

• upstream) and authenticate the agents, continue with the optional full
  setup.

One-line install of this harness. curl -fsSL https://oh.mifune.dev/install.sh | bash
does steps 1 and 2 in one shot for a clone of this repo at ~/.openharness
(review-first: download it, read it, then bash openharness-install.sh). Set
OH_GITHUB_REPO=<your-org>/<your-fork> to install a fork instead. All
environment overrides: Installation.

3. Full setup (optional) — private repo, remotes, agent auth

Run these inside the initial Herdr pane (agro shell <name>, then agro tool install herdr, then herdr). Per-step depth + troubleshooting:
quickstart → End-to-end setup walkthrough.

# GitHub auth over SSH — pick SSH, generate a key, paste a token
# (SSH remotes use the key directly, so `gh auth setup-git` isn't needed):
gh auth login

# Create your own PRIVATE repo and point origin at it. `agro config repo` runs the
# four commands below for you (it asks first, and defaults to no):
agro config repo

# The manual equivalent, if `gh` is not installed — `agro config repo` keeps the
# upstream you cloned from as the `openharness` remote instead of `upstream`:
gh repo create <your-user>/openharness --private
git remote set-url origin [email protected]:<your-user>/openharness.git
git remote add upstream [email protected]:mifunedev/openharness.git
git push -u origin HEAD

# Authenticate the agents you'll use. Simplest cross-provider path: launch the agent,
# run /login, and pick DEVICE MODE (a code + URL that works headless/remote). The
# one-liners below are equivalents where a provider exposes them:
# Each CLI arrives only through `agro harness install <id>` — nothing installs at boot.
agro harness install claude-code && claude auth login   # Claude Code (or /login in-session)
agro harness install codex && codex login --device-auth # Codex (device mode; or /login in-session)
agro harness install pi && pi                           # Pi (first run walks provider auth)
agro harness install hermes && hermes setup             # Hermes

# Configure Slack, then run + verify the gateways (sandbox-only):
#   config: docs/integrations/slack.md  ·  docs/harnesses/hermes.md
gateway pi && gateway hermes
gateway status
tmux attach -r -t client-slack-pi   # read-only view; detach with Ctrl-b d

VS Code (secondary path)

Provision with agro sandbox install docker, then attach with Dev Containers:
Attach to Running Container against your sandbox. That is the supported editor
path.

Do not provision with "Reopen in Container". That path reads
.devcontainer/devcontainer.json, which lists docker-compose.yml alone, so it
bypasses .oh/scripts/docker-compose.sh and no overlay applies — no SSH
(access.ssh), no host Docker socket (access.dockerSocket), no Hermes
dashboard (hermesDashboard.enabled), and nothing from composeOverrides[].
Secrets still load, because compose auto-loads the .devcontainer/.env symlink
beside the compose file; non-secret oh.json settings fall back to the compose
defaults. Details: lifecycle commands.

Optional — DebugMCP. Once attached from VS Code, you can install the
microsoft/DebugMCP extension to expose a debugging MCP server that any
MCP-capable harness (Claude Code, Codex, …) can drive. It's optional and not
tied to any single agent — see the
DebugMCP runbook.

🧩 How the primitive pack ships

Open Harness vendors the shared skills/hooks primitive pack directly into the .oh/ control plane: .oh/skills/, .oh/hooks/, and .oh/skills.lock are tracked as ordinary files in this repo. Skills are the reusable-behavior primitive; the harness ships no repository-authored agent definitions, and provider-native sub-agents remain available as a bounded execution primitive through /delegate. oh update lays them down, so a fresh checkout has the skills immediately — no submodule, no recursive clone, no network step.

Provider surfaces are symlinks into .oh/: .pi/skills, .claude/skills, and .codex/skills point at .oh/skills; .claude/hooks → .oh/hooks. .pi/ itself remains the Pi provider surface in v1.

🚀 Use it

agro sandbox list       # every sandbox: name, runtime, status, repo
agro shell <name>       # enter the isolated sandbox
agro tool install herdr # nothing installs at boot; install the workspace first
herdr                 # open the primary interactive workspace
# install an agent CLI the same way, then launch it from a Herdr pane:
#   agro harness install claude-code  → claude    # Claude Code
#   agro harness install codex        → codex     # OpenAI Codex CLI
#   agro harness install pi           → pi        # Pi Coding Agent
#   agro harness install opencode     → opencode  # OpenCode
#   agro harness install hermes       → hermes    # Nous Research Hermes
#   agro harness install grok-build   → grok      # xAI Grok Build
agro stop <name>    # stop the sandbox, keeping volumes
agro destroy <name> # stop the sandbox, wipe its volumes, drop the registry entry
agro --help         # every verb

🧪 Testing

• Property-based testing convention: docs/property-testing.md

Prefer VS Code or remote SSH? Use the Dev Containers extension's "Attach to Running Container" against openharness — not "Reopen in Container", which applies no overlays (see VS Code (secondary path)) — or SSH into your host first and then attach.

⚙️ Configure (optional)

Configuration is split by kind across two files. oh.json holds every
non-secret setting — sandbox identity, git identity, the SSH and Docker-socket
toggles. It holds no install field: agro harness install <id> and agro tool install <id> are the only door. A gitignored, mode-0600 .env holds nothing
but secrets (GH_TOKEN, SANDBOX_PASSWORD, PI_SLACK_APP_TOKEN,
PI_SLACK_BOT_TOKEN, …); the tracked .example.env documents every
allow-listed key. A sandbox keeps its pair inside its registry entry —
agro config set --sandbox <name> <field> <value> and agro secret set --sandbox <name> <KEY> write there; without the flag both write the project root. Apply a
change with agro stop <name> && agro sandbox install docker --name <name>.
Full field reference: Configuration.

Secrets are read on every path, including VS Code "Reopen in Container" —
that path loads .devcontainer/docker-compose.yml directly and compose
auto-loads the dotenv beside it, which is a symlink to the root one. Compose
overlays are the exception: that path applies none, which is why
agro sandbox install docker provisions and VS Code only attaches. A
harness.yaml layer used to sit in front of these files and was invisible on
exactly that path; it was removed in 0.4.0, and a leftover one is migrated
automatically on the next lifecycle command. Compose overlay paths live in
composeOverrides[] in oh.json. See
the agro sandbox install docker guide for
the image-mode recipe.

✨ What you get

📚 Where to go next

• Read the docs → oh.mifune.dev — the rendered, searchable documentation site (start here)
• Docs index — GitHub-readable docs kept with the core repo
• Quickstart — full step-by-step
• DeepWiki — generated codebase map
• Docs site source — Docusaurus source repo that builds oh.mifune.dev (contribute doc edits here)

🧹 Cleanup

agro destroy <name>

🤝 Contributing & community

Open Harness is maintained under the mifunedev org — the canonical repo is github.com/mifunedev/openharness. To run your own, use the clone-and-own setup above (or fork it — see Other install methods) and open PRs back upstream. Issues and PRs welcome; if Open Harness is useful to you, please give us a star.

📄 License

Apache License 2.0 — copyright Ryan Eggleston, d/b/a Mifune Dev (mifune.dev). Prior MIT releases remain available under MIT; this change governs new code and future releases and does not revoke past grants.

Apache-2.0 covers the runtime, the oh CLI, container definitions, and the harness spec. The Mifune Console, the provisioning and fleet-management control plane, and billing / enterprise policy / RBAC / hosted operations are proprietary — see the open-core boundary.

Trademarks

Apache-2.0 §6 grants no permission to use the Mifune or Open Harness names, logos, or trade dress (reasonable, customary use in describing the origin of the work is fine). Fork it, modify it, sell it — just don't present your fork as Mifune.

Read the docs · Docs index · Docs site source