Installation#

The core framework needs Python 3.12+ and Git. It does not require a GPU. External tasks, model endpoints, learner CLIs, and sandbox support depend on the workflow you choose.

Install the checkout#

Recommended for examples, benchmark recipes, and development.

If you do not have a checkout:

git clone https://github.com/Infini-AI-Lab/hermit.git
cd hermit

From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
hermit --help

Help should list check, train, eval, deploy, convert, and serve. Activate the environment again in each new terminal. Editable installation uses this checkout’s Python code.

Install from PyPI#

Install the core framework in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install hermit-harness
hermit --help

The package includes the CLI, adapter templates, and built-in Evolvers. GEPA, SkillOpt, and Harness² also need their method-specific dependencies. The example data, benchmark recipes, and method dependency groups live in the repository; use a checkout for those workflows.

Install method dependency groups#

Method dependencies are declared once in pyproject.toml, separately from the core package dependencies. Run these commands from the checkout root in the environment that runs Hermit. Group installation requires pip 25.1+ and Git:

python -m pip install --upgrade "pip>=25.1"
python -m pip install -e . --group gepa
# Other methods:
python -m pip install -e . --group skillopt
python -m pip install -e . --group harness2
python -m pip install -e . --group ace
python -m pip install -e . --group rrsi
# Or all method dependencies:
python -m pip install -e . --group all

To combine methods, repeat the option, for example --group skillopt --group gepa for OfficeQA. uv reads the same groups: uv pip install -e . --group gepa. Each group but ace (sentence-transformers alone) retains its tested upstream Git commit. all includes the five method groups; it does not install host CLIs, datasets, or system tools. Groups are not published as package extras, so pip install hermit-harness still installs only the core; hermit-harness[gepa] is not supported. Without a checkout, install a method’s pinned requirements from its group in pyproject.toml directly; the Evolver’s missing-dependency error prints them. Documentation build dependencies are in docs/requirements.txt.

The upstream Harness² package supports Python 3.12 and 3.13 only, so --group harness2 and --group all fail on Python 3.14; install gepa and skillopt separately there.

Install the sandbox’s packages#

The bubblewrap sandboxes (the acting agent’s, the learner’s, the adapter’s) show the environment Hermit runs in: what is installed there is what their code can import. The sandbox extra installs a base, numpy, pandas, scipy and torch:

python -m pip install -e ".[sandbox]"      # a checkout
python -m pip install "hermit-harness[sandbox]"

PyPI’s torch for Linux is the CUDA build; for the CPU one, install torch first from https://download.pytorch.org/whl/cpu. Install Hermit in an environment of its own: a package installed beside it is shown to the sandboxes too (sandbox.hide covers a benchmark’s scoring module; an editable install’s checkout is never shown).

Install mini-swe-agent#

The mini-swe-agent acting agent and hermit deploy --host mini-swe-agent need mini-swe-agent (2.4.6, which brings litellm), published as an extra:

python -m pip install -e ".[mini-swe-agent]"      # a checkout
python -m pip install "hermit-harness[mini-swe-agent]"

Choose the additional requirements#

Workflow

Additional requirements

Offline first training

None beyond the core install

First real-model training

python -m pip install -e . --group gepa, a compatible chat-completions endpoint, model id, and credential; data is included

Generate a Codex / Claude Code / Pi / OpenCode / DeepSeek Harness / Hermes Agent workspace

No host CLI is needed until you start the host

Act with, or deploy to, mini-swe-agent

The mini-swe-agent extra and a chat-completions model (tutorial)

Run an acting host

Installed and authenticated host, plus adapter tool dependencies

Prompt-only learner

The Codex CLI, Linux with bubblewrap, and a learner backend that serves the Responses API

GEPA

python -m pip install -e . --group gepa, learner endpoint, validation split

SkillOpt

python -m pip install -e . --group skillopt, learner endpoint, validation split

Harness²

Python 3.12 or 3.13, python -m pip install -e . --group harness2, Claude Code (or Codex or Pi), and the execution environment described in Harness²

RRSI Adapter

python -m pip install -e . --group rrsi, a CLI for the proposer and its analyst, digesters and critic (Codex, Claude Code or Pi), a training split evaluated k times per task

Codex / Claude learner

Selected authenticated CLI and supported program-execution environment

MWM

Linux learner environment, Codex, Claude Code or Pi, evidence store, task deployment contract, model access

Acting and learning on a Claude subscription

Claude Code 2.1.248 or later, claude setup-token, Linux with bubblewrap for its sandboxes; see Claude subscription

Pi acting agent or learner

The pi release binary on PATH (GitHub release pi-linux-x64.tar.gz, checked against its SHA256SUMS) and a model reference. For a Pi acting agent put the release’s directory on PATH, or link pi from outside /usr: its task sandbox shows a program’s own directory and follows no link from /usr

OpenCode acting agent or learner

The opencode 2.2 release binary on PATH (GitHub release opencode-linux-x64.tar.gz of anomalyco/opencode, checked against the release’s sha256 digest) and a model reference

DeepSeek Harness acting agent or learner

The dsh command on PATH (Node.js 24.9 or later, npm install -g @deepseek-ai/dsh@0.2.2-rc.1) and a model reference

Hermes Agent acting agent or learner

The hermes command on PATH (Python 3.11 to 3.13, uv tool install 'hermes-agent[mcp,anthropic]==0.19.0': the mcp extra is required for Hermit’s tools, and the anthropic extra for a backend Hermes reaches over the Messages API, which it cannot install inside the run’s sandbox) and a model reference

Benchmark recipe

Its dataset, scorer, model settings, and environment; see catalog

Core installation and the deterministic tutorial work on macOS. The sandboxes (the acting agent’s, the judge’s, the learner’s) use a Linux-specific bubblewrap backend; macOS has no evolver sandbox. For Ubuntu/Debian:

sudo apt-get install bubblewrap
bwrap --version

The environment must permit the required namespaces. Installing the binary alone may not satisfy a container or cluster’s namespace policy (on Ubuntu 24.04, unprivileged user namespaces need an AppArmor profile for bwrap or the kernel.apparmor_restrict_unprivileged_userns=0 setting). The sandbox does not isolate arbitrary in-process Python. See sandbox boundaries.

A recipe or method can support fewer Python versions than the core. Check external dependencies separately. For exact experiment reproduction, record the framework commit and dependency revisions.

Verify the local installation#

From the source checkout:

hermit check --config docs/_examples/first_training/run.yaml

The probe should score the first toy task zero without execution errors, its agent in the task sandbox. The best_effort warning is expected: the example runs where bubblewrap is missing too, unconfined and recorded. Continue to Quick Start to train and evaluate it.

Optional: build documentation#

python -m pip install -r docs/requirements.txt
bash docs/build.sh
bash docs/serve.sh 8000

Open http://127.0.0.1:8000. The preview rebuilds on source changes. The strict build treats warnings as errors. The local preview includes design drafts under _static/drafts/; the default publication build excludes them. For earlier evolve / run interfaces and current limitations, see Compatibility.