hlock

Make your agent harness pinnable, portable, and tunable.

Pin your harness, models, MCP servers, skills, and config in a harness.lock, version it, and rehydrate it anywhere.

Documentation · Quickstart · CLI reference · Design specs

Your agent is more than a model: it's a harness version, MCP servers, skills, plugins, instruction files, and config, set up by hand on one machine. hlock pins all of it in a harness.lock you commit to git, catches drift, and brings the same setup back on another laptop, in CI, or in a container. When you're ready, it measures your stack against your own tasks and finds a better one.

Install

pip install hlock        # or: uv add hlock  ·  uvx hlock --help

Prebuilt wheels cover Linux (x86_64, aarch64), macOS (arm64, x86_64), and Windows (x64) for CPython 3.9+. For Rust, use cargo add hlock.

[!NOTE] harness-lock is an alias for hlock. Both names install the same package at the same version, so import hlock and import harness_lock are the same API.

Quickstart

Pin the harness you already use (Claude Code, Codex, Pi, OpenCode, Cursor, Gemini CLI, and more), then bring it back anywhere:

hlock pin                       # lock your current setup into harness.lock
git add harness.lock .hlock/    # version it (secrets are placeholders, never values)
hlock check                     # see what changed since the pin; re-pin to lock it
hlock sync                      # on another machine: rehydrate it (also --prefix DIR, --docker)
hlock launch                    # start a session on the locked setup, isolated from your config
hlock run "summarize README.md"  # or run one prompt through it (claude -p, codex exec, …)

For your own work, hlock evals init -t coding (or data, research, support) writes an eval pack template plus an Agent Skill, so the agent you already use can fill it in with real tasks from your project. See Eval packs.

See the Quickstart, Pinning your setup, Rehydrating with sync, and Launching a locked harness.

Then make it better

Optimize your harness. Draft an eval pack from the requests you've already made to your agent with hlock evals init --from-traces (it reads the sessions Claude Code, Codex, and Pi logged for the project), and review it with your agent using the Agent Skill it writes. List the models, decision models and harnesses to try in a harness.toml, and let hlock resolve lock the best combination with its success rate, cost, and latency. hlock tune goes further, into prompts, hyperparameters, and fine-tuned small models. The built-in reference provider is offline, so you can try the loop with no API keys:

hlock evals init                          # write a hello-world eval pack to ./evals
hlock init --name demo                    # write a starter harness.toml
hlock resolve                             # measure every combination -> harness.lock
hlock run "count the words in words.txt"  # run the locked agent

Go local. hlock localize turns a lock into an equivalent on an open-source harness and models served by Ollama or LM Studio, keeping your MCP servers, skills, and instructions.

Let an agent do the busywork. hlock meta hands work that needs judgment (installing what a lock needs on a new machine, filling in an eval pack, updating skills and MCP servers) to a pinned agent and checks the result itself. The default is an agent built into hlock, so there's nothing to install: give it an API key or a local model.

hlock meta init                 # pick a model for the built-in agent, and pin it
hlock meta run install          # install what harness.lock still needs, then verify

See Finding the best stack, Eval packs, Tuning, and Going local, and The meta harness.

import json
import hlock
from hlock import SearchSpace, Objective, Budget

space = SearchSpace(
    llm={"planner": ["reference:qwen-7b", "reference:qwen-32b"]},
    decision=["none", "rules:default"],
    harness=["reference"],
    objective=Objective(select="min-cost", constraints={"success-rate": ">=0.5"}),
    budget=Budget(max_trials=50),
    evals=json.dumps({"packs": ["./evals"], "seeds": 2}),
)
lock = hlock.resolve(space, backend="local")   # writes ./harness.lock
print(lock.summary())

agent = hlock.load("harness.lock")
print(agent.run("clean ./data/orders.csv"))   # {"success": true, "model": "qwen-7b", ...}

How it works

Architecture

A Rust core does all the deterministic work. Anything that needs the Python ML ecosystem or a GPU runs in a Python worker, which can lift each piece of work to a Flyte task on a cluster.

Backends

hlock tune --backend devbox --depth probe --max-trials 10
# real LLM calls: export HL_LLM_BASE_URL=http://… HL_LLM_MODEL=qwen-32b [HL_LLM_API_KEY=…]
hlock tune --backend cluster --depth ft --data user:./runs   # LoRA on a GPU worker

See Backends for setup and the HL_* environment variables.

Development

Development uses uv and a Rust toolchain.

uv sync                            # create .venv, build the Rust extension, install dev tools
uv run pytest                      # Python bindings, CLI, worker
uv run ruff check harness_lock hlock tests
cargo test -p harness-lock-core    # Rust core + integration tests

uv run --group docs zensical serve # docs at http://localhost:8000

uv run rebuilds the extension automatically when Rust sources change.

Want to help? See the contributing guide. Releases are cut from tags. See RELEASING.md.

Status

What works today: pin, check, sync, and launch for the supported harnesses, localize, manifest and lockfile schema v1, a content-addressed store, eval packs (hlock evals) with graders, the reference provider and harness, grid search with Pareto selection, upgrade (plan/apply/rollback), tune across the local, devbox, and cluster backends, and the meta harness. The design specs describe the full design, much of which is still on the roadmap.

License

Apache-2.0