https://github.com/mifunedev/openharness
🏗️ We provide the Sandbox. You choose the Harness.
https://github.com/mifunedev/openharness
claude claude-code codex deepagents docker gemini-cli langchain nvidia openai openclaw opencode openshell pi-mono sandbox
Last synced: about 10 hours ago
JSON representation
🏗️ We provide the Sandbox. You choose the Harness.
- Host: GitHub
- URL: https://github.com/mifunedev/openharness
- Owner: mifunedev
- License: mit
- Created: 2026-03-27T04:26:44.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-25T06:04:35.000Z (1 day ago)
- Last Synced: 2026-06-25T08:06:27.281Z (1 day ago)
- Topics: claude, claude-code, codex, deepagents, docker, gemini-cli, langchain, nvidia, openai, openclaw, opencode, openshell, pi-mono, sandbox
- Language: TypeScript
- Homepage: https://oh.mifune.dev
- Size: 8.71 MB
- Stars: 20
- Watchers: 0
- Forks: 3
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 🏗️ Open Harness
**Open Harness** is a Docker-based agent harness for **one project**, agent-tended over time. One `docker compose up` gives you a long-lived sandbox where Claude (or another agent of your choice) runs against a single repo, branch, and identity — not a multi-tenant comparison rig.
- **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.
- **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.** No Node, no Python, no toolchain rot on your laptop.
- **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](docs/integrations/slack.md).
- **Multi-agent? Add a pack.** Other multi-agent setups ship as separate packs — see [`@ryaneggz/mifune`](https://github.com/ryaneggz/mifune).
---
## 📦 Install
**Option A — Upstream (try it without any setup):**
```bash
curl -fsSL https://oh.mifune.dev/install.sh | bash
```
Review-first alternative (no extra dependency):
```bash
curl -fsSL -o openharness-install.sh https://oh.mifune.dev/install.sh
# Review openharness-install.sh in your editor or pager before running it.
bash openharness-install.sh
```
If you already use [`vet`](https://github.com/vet-run/vet), you can review and approve the same installer with `vet https://oh.mifune.dev/install.sh`. `vet` is optional; Open Harness requires Docker with the Compose plugin and Git on the host.
Clones into `~/.openharness`, offers to share your host `gh` token, writes `.devcontainer/.env`, and builds the image (~10 min cold, ~30s warm). Required host dependencies: [Docker](https://docs.docker.com/get-docker/) with the Compose plugin and [Git](https://git-scm.com/).
**Option B — Fork and clone (recommended for self-hosting):**
```bash
# 1. Fork on GitHub, then clone YOUR fork:
git clone https://github.com//.git && cd
# 2. Bootstrap — installer auto-detects the local clone, no env vars needed:
bash .oh/scripts/install.sh
```
**Option C — Clone upstream, then re-point to your repo:**
```bash
git clone https://github.com/mifunedev/openharness.git my-harness && cd my-harness
git remote set-url origin https://github.com//.git
bash .oh/scripts/install.sh
```
Advanced: install directly from your fork without cloning first
```bash
OH_GITHUB_REPO=/ curl -fsSL \
https://raw.githubusercontent.com///main/scripts/install.sh | bash
```
Review-first fork install:
```bash
curl -fsSL -o openharness-install.sh \
https://raw.githubusercontent.com///main/scripts/install.sh
# Review openharness-install.sh, then run it against your fork.
OH_GITHUB_REPO=/ bash openharness-install.sh
```
If your fork uses a default branch other than `main`, set `OH_GITHUB_REF=` and replace `main` in the URL. See [Installation docs](https://oh.mifune.dev/docs/installation) for all environment overrides.
## 🚀 Use it
```bash
cd ~/.openharness
make shell # enter the isolated sandbox
# inside the sandbox, launch any core agent:
# claude # Claude Code (default)
# codex # OpenAI Codex CLI
# opencode # OpenCode (optional: set install.opencode: true in harness.yaml and rebuild)
# pi # Pi Coding Agent
# deepagents # LangChain DeepAgents (optional: set install.deepagents: true in harness.yaml and rebuild)
# hermes # Nous Research Hermes (optional: set install.hermes: true in harness.yaml and rebuild)
# grok # xAI Grok Build (optional: set install.grok_build: true in harness.yaml and rebuild)
make destroy # stop and remove the sandbox
make help # all targets
```
## 🧪 Testing
- Property-based testing convention: [docs/property-testing.md](docs/property-testing.md)
Prefer VS Code or remote SSH? Use the Dev Containers extension's "Attach to Running Container" against `openharness`, or SSH into your host first and then attach.
## ⚙️ Configure (optional)
`harness.yaml` is the tracked config for shared non-secret settings (optional
installs, Slack allowlists, compose overlays, and any sandbox defaults you
intentionally want in git). `.devcontainer/.env` is gitignored and holds
host-local defaults generated by the installer (`SANDBOX_NAME`, `TZ`, git
identity) plus secrets (`GH_TOKEN`, `PI_SLACK_APP_TOKEN`, `PI_SLACK_BOT_TOKEN`).
Active keys in `harness.yaml` override `.devcontainer/.env`. Apply changes
with `make destroy && make sandbox`.
Manual setup (no installer)
```bash
git clone https://github.com/mifunedev/openharness.git && cd openharness
make sandbox
make shell
```
## ✨ What you get
| | |
|---|---|
| **Core agents** | Defaults: Claude Code, Codex, Pi. Optional: OpenCode, DeepAgents, Hermes, Grok Build |
| **Runtimes** | Node 22, pnpm, Bun, uv (Python) |
| **DevOps** | Docker CLI + Compose, GitHub CLI, cloudflared, tmux, croner |
| **Browser** | agent-browser + Chromium (headless) |
| **One project, one sandbox** | A single container scoped to a single repo and branch |
| **Crons** | Markdown-defined schedules in `crons/*.md` driven by the in-container croner runtime |
| **Multi-agent** | Install a harness pack such as [`@ryaneggz/mifune`](https://github.com/ryaneggz/mifune) for additional multi-agent setups |
## 📚 Where to go next
- [Quickstart](https://oh.mifune.dev/docs/quickstart) — full step-by-step
- [Crons](https://oh.mifune.dev/docs/crons/overview) — markdown-defined autonomous tasks
## 🧹 Cleanup
```bash
make destroy
```
## 🤝 Contributing & community
Open Harness is maintained under the [`mifunedev`](https://github.com/mifunedev) org — the canonical repo is [github.com/mifunedev/openharness](https://github.com/mifunedev/openharness). To run your own, fork it (see **Option B** above) and open PRs back upstream. Issues and PRs welcome; if Open Harness is useful to you, please [give us a star](https://github.com/mifunedev/openharness/stargazers).
## 📄 License
MIT.
---
[Full documentation](https://oh.mifune.dev/docs)