hlock

Your agent harnessmade portable.

Pin your harness, models, MCP servers, skills, and config ina 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, MCP servers, skills, and config, hand-tuned on one machine. hlock is the missing harness packaging layer: harness.lock tracks all of its dependencies, so you can commit it to git and restore it anywhere. 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 --user                # lock your setup (yours in ~/.claude etc., and the project's) 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 into .hlock/env (or --in-place, --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, …)
hlock pull github:alice/agents  # get someone else's pinned setup; then hlock launch --lock alice

Plain hlock pin records only the project's own skills, MCP servers and config, so your personal setup stays out of the repository; --user adds it.

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.

Manage your team's agents

Contributors to one repository rarely share an agent setup. Each person can commit their own lock to .hlock/locks/harness.<handle>.lock, next to the code it was used on, and anyone with a clone can try a teammate's setup in isolation:

hlock pin -o .hlock/locks/harness.alice.lock         # your harness and model, with the repo's setup
hlock launch --lock .hlock/locks/harness.bob.lock    # try a teammate's, isolated from yours

Add the hlock badge to your README to point readers at the locks. See Team repositories for the layout, the conventions, and pulling a teammate's lock from outside the repository.

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.

Related projects

hlock builds on, and borrows from, a lot of good work. Package managers install agent config, dotfile managers and Nix reproduce it, eval frameworks measure it, and optimizers generate it. hlock isn't trying to replace any of them; it has different devex goals:

• speed: one command pins the setup you already have
• quick portability: the whole stack, from harness version and models to MCP servers, skills and config, in one lock you can rehydrate anywhere
• tunability: eval packs, the resolver and the tuner measure your stack against your own tasks
• let agents do the busy work: some packaging and syncing work that users need to do around hlock can be further automated with a meta agent.

The comparison page goes through each one, including "why not just dotfiles / chezmoi / Nix / APM?".

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