Installation

Quick install (recommended)

One line — installs the coral CLI globally so you can run it from any directory:

curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | sh

The script:

1. Installs uv if missing.
2. Runs uv tool install git+https://github.com/Human-Agent-Society/CORAL.git — drops the coral binary into ~/.local/bin inside an isolated venv.
3. Ensures ~/.local/bin is on PATH for future shells.

Pin a version (any git tag, branch, or commit):

curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | CORAL_VERSION=v0.7.0 sh

Verify:

coral --version

Upgrade in place at any time:

uv tool upgrade coral

Prerequisites

The installer handles uv for you. You still need:

• Python 3.11+ (uv will fetch one if you don't have it)
• git — CORAL uses git worktrees for agent isolation
• curl — used by the installer to bootstrap uv

Recommended:

• tmux — CORAL auto-wraps runs in a tmux session (use run.session=local to skip)

At least one supported agent runtime:

• Claude Code (default) — requires an Anthropic API key
• Codex — OpenAI's coding agent
• OpenCode — open-source alternative

For Harbor-based benchmarks (SWE-bench, terminal-bench):

• Docker — installed and running on the host
• Harbor CLI — invoked via uvx harbor (no separate install if you have uv)

Manual install (no curl pipe)

If you'd rather not pipe a remote script into a shell:

# Install uv first (skip if already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install coral as a uv tool (isolated venv, on PATH):
uv tool install git+https://github.com/Human-Agent-Society/CORAL.git

# Pin a version:
uv tool install git+https://github.com/Human-Agent-Society/CORAL.git@v0.7.0

Develop CORAL itself

If you're modifying CORAL's source rather than just using it, clone the repo and use an editable install. In this mode, prefix commands with uv run:

git clone https://github.com/Human-Agent-Society/CORAL.git
cd CORAL
uv sync                       # basic
uv sync --extra dev           # with pytest, ruff, mypy
uv sync --extra ui            # with web dashboard
uv sync --all-extras          # everything

uv run coral --version

Optional extras

Benchmark evaluators

Standardized coding benchmarks like SWE-bench Verified and terminal-bench are shipped as example tasks under examples/, not as Python extras. Their graders delegate evaluation to Harbor, which runs each instance inside its own Docker container.

Run them directly with coral start — no extra uv sync step is required:

# SWE-bench Verified (meta-solver optimization over 500 GitHub issues)
coral start -c examples/swebench-verified/task.yaml

# terminal-bench (meta-solver optimization over terminal/shell tasks)
coral start -c examples/terminal-bench/task.yaml

Each task's seed includes a solve.py baseline (a Terminus2-based Harbor agent) and a grader that invokes uvx harbor run -d <dataset> with tiered evaluation (5 → 30 → all instances). See the Benchmarks guide for details.

Docker-in-Docker is not supported. Because Harbor spawns Docker containers, CORAL itself must run on the host machine (not inside a container) for these benchmarks. Other examples that don't use Harbor are unaffected.

Next steps

Once installed, head to the Quick Start to run your first task.