# 🏗️ 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.
- **Only host dependency: Docker.** No Node, no Python, no toolchain rot on your laptop.
- **Composable infra.** Cherry-pick Postgres, Cloudflare tunnels, SSH, Caddy gateway via Compose overlays.
- **Slack-ready.** The in-tree Pi extension at `.pi/extensions/slack/` bridges Slack 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
```

Clones into `~/.openharness`, offers to share your host `gh` token, writes `.devcontainer/.env`, and builds the image (~10 min cold, ~30s warm). Only host dependency: [Docker](https://docs.docker.com/get-docker/).

**Option B — Fork and clone (recommended for self-hosting):**

```bash
# 1. Fork on GitHub, then clone YOUR fork:
git clone https://github.com/<your-org>/<your-fork>.git && cd <your-fork>
# 2. Bootstrap — installer auto-detects the local clone, no env vars needed:
bash scripts/install.sh
```

**Option C — Clone upstream, then re-point to your repo:**

```bash
git clone https://github.com/ryaneggz/open-harness.git my-harness && cd my-harness
git remote set-url origin https://github.com/<your-org>/<your-repo>.git
bash scripts/install.sh
```

<details><summary>Advanced: install directly from your fork without cloning first</summary>

```bash
OH_GITHUB_REPO=<your-org>/<your-fork> curl -fsSL \
  https://raw.githubusercontent.com/<your-org>/<your-fork>/main/scripts/install.sh | bash
```

If your fork uses a default branch other than `main`, set `OH_GITHUB_REF=<branch>` and replace `main` in the URL. See [Installation docs](https://oh.mifune.dev/docs/installation) for all environment overrides.

</details>

## 🚀 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
#   pi         # Pi Coding Agent
#   deepagents # LangChain DeepAgents (multi-provider)
make destroy     # stop and remove the sandbox
make help        # all targets
```

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)

`.devcontainer/.env` is generated with safe defaults during install. Open
it any time to change `SANDBOX_NAME`, set a different `GH_TOKEN`, change
`TZ`, or set `SLACK_*` tokens for the Pi Slack extension. Apply with
`make destroy && make sandbox`.

<details><summary>Manual setup (no installer)</summary>

```bash
git clone https://github.com/ryaneggz/open-harness.git && cd open-harness
make sandbox
make shell
```

</details>

## ✨ What you get

| | |
|---|---|
| **Core agents** | Claude Code, Codex, OpenCode, Pi |
| **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

Issues and PRs welcome at [github.com/ryaneggz/open-harness](https://github.com/ryaneggz/open-harness). If Open Harness is useful to you, please [give us a star](https://github.com/ryaneggz/open-harness/stargazers).

## 📄 License

MIT.

---

[Full documentation](https://oh.mifune.dev/docs)