hlock

Your agent harness
made portable.

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, MCP servers, skills, and config, hand-tuned on one machine. hlock is the missing harness packaging layer, written in Rust 🦀: 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.

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
hlock add skill github:anthropics/skills/skills/pdf   # declare a dependency, pin it, install it
hlock audit                     # integrity, hidden characters, what it runs, policy, secrets

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

Switch harnesses, or go local. hlock migrate --to codex moves a lock onto another harness, with your MCP servers, skills, and instructions rewritten to where it reads them. hlock localize does the same onto an open-source harness and models served by Ollama or LM Studio.

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 Switching harnesses, 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="offline")   # 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 on a backend: hlock's Python worker on this machine, Flyte tasks on a cluster, or a backend you write in Rust or Python.

Backends

hlock tune --backend local --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 flyte --depth ft --data user:./runs   # LoRA on a GPU worker

Backends are pluggable: a Python class registered in the hlock.backends entry point group, or any executable named hlock-backend-<name> (Rust has a serve helper). See Backends for setup, the HL_* environment variables, and how to write your own.

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?". Already using APM? See Coming from 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.

License

Apache-2.0