open-harness/README.md

🏗️ 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.
• Multi-agent? Add a pack. Other multi-agent setups ship as separate packs — see @ryaneggz/mifune.

---

📦 Install

Option A — Upstream (try it without any setup):

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.

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

# 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:

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

Advanced: install directly from your fork without cloning first

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 for all environment overrides.

🚀 Use it

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.

Manual setup (no installer)

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

✨ 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 for additional multi-agent setups

📚 Where to go next

• Quickstart — full step-by-step
• Crons — markdown-defined autonomous tasks

🧹 Cleanup

make destroy

🤝 Contributing & community

Issues and PRs welcome at github.com/ryaneggz/open-harness. If Open Harness is useful to you, please give us a star.

📄 License

MIT.

---

Full documentation