hlock

Make your agent harness pinnable, portable, and tunable.

Tune your agent stack against your own tasks, then pin the winner in a harness.lock.

Documentation · Quickstart · CLI reference · Design spec

hlock treats an agent system the way a package manager treats dependencies. You bring your domain tasks, the models you're allowed to use, and the harness you like. hlock searches the stack, measures every candidate against your tasks, and writes a harness.lock: a pinned, version-controlled, enforceable description of the agent that actually works for your domain, along with the evidence for choosing it.

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.

Quickstart

No accounts or API keys needed. The built-in reference provider and harness are deterministic and offline, so the whole loop runs on a laptop.

hlock init --name demo --pack ./tasks   # write a starter harness.toml
hlock resolve                           # tune the search space -> harness.lock
hlock check                             # fail if harness.toml drifted from the lock
hlock run "clean ./data/orders.csv"     # run the locked agent

From there: hlock show prints the locked stack and its evidence, hlock tree prints the component graph, hlock upgrade plans model upgrades, and hlock optimize tunes prompts, hyperparameters, and small models into a harness.opt.lock.

Already have a harness set up?

Pin it. hlock pin captures your Claude Code, Codex, Pi, OpenCode, Hermes or Cursor setup into harness.lock: the harness version, the models and local runtimes it uses, MCP servers, skills, plugins, and config, with secrets replaced by placeholders.

hlock harness list      # the harnesses on this machine, and the one you're running inside
hlock pin               # lock your current setup into harness.lock
hlock check             # fail if your setup drifted from the pin
hlock sync              # on another machine: rehydrate it (also --prefix DIR, --docker)
hlock launch            # start a session that matches the lock (or: hlock launch opencode)
hlock localize          # an all-local equivalent: local harness + Ollama/LM Studio models

See Harnesses and Pinning your setup, Rehydrating with sync, and Launching a locked 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),
    tasks=json.dumps({"packs": ["./tasks"], "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 optimize --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 optimize --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

hlock is at v0.1. What works today: manifest and lockfile schema v1, a content-addressed store, task packs with graders, the reference provider and harness, grid search with Pareto selection, upgrade (plan/apply/rollback), and optimize across the local, devbox, and cluster backends. SPEC.md describes the full design, much of which is still on the roadmap.

License

Apache-2.0