---
title: Installation
description: Install CORAL and its dependencies.
---


## Quick install (recommended)

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

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

The script:

1. Installs [`uv`](https://docs.astral.sh/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):

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

Verify:

```bash
coral --version
```

Upgrade in place at any time:

```bash
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:

```bash
# 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.5.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`:

```bash
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

| Extra  | Install                  | Purpose                              |
|--------|--------------------------|--------------------------------------|
| `dev`  | `uv sync --extra dev`    | Test and lint tools (pytest, ruff, mypy) |
| `ui`   | `uv sync --extra ui`     | Web dashboard (Starlette + uvicorn)  |
| `all`  | `uv sync --extra all`    | Everything above                     |

## 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](https://github.com/corca-ai/harbor), which runs each instance inside its own Docker container.

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

```bash
# 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](/guides/benchmarks) 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](/getting-started/quickstart) to run your first task.
