made portable.
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.
pip install hlock
uv add hlock # add to a project
uv tool install hlock # or install the CLI globally
uvx hlock --help
pipx install hlock
Lock the harness you already have¶ #
If you've used uv, cargo, or npm, you already know the shape of hlock:
| You know this from package managers | In hlock |
|---|---|
uv.lock /Cargo.lock |
harness.lock , thelockfile : every dependency of your harness, pinned and hashed |
pip freeze |
hlock pin : record the setup you already have, and re-pin as it grows |
--locked check |
hlock check : show what changed since the pin |
uv sync /npm ci |
hlock sync : rehydrate the locked setup on any machine |
uv run |
hlock launch and** hlock run** : start sessions and run prompts on the locked setup |
Pin everything The harness version, models, MCP servers, skills, plugins, instruction files, and config, each with a digest. Claude Code, Codex, Pi, OpenCode, autonomous agents like OpenClaw, and more . #
Secrets stay out
API keys and tokens become HLOCK_SECRET_* placeholders, so the lock is safe to
commit. You supply the values when you sync. #
Rehydrate anywhere
hlock sync restores the setup on a new machine, in an isolated directory, or in a
Docker image, and tells you exactly what it can't do for you. #
Launch from the lock
hlock launch starts your harness in an isolated environment that matches the lock,
with none of the unlocked config on your machine.
Manage your team's agents¶ #
Contributors to one repository rarely share an agent setup: one uses Claude Code with
hand-written skills, another uses Codex with a different model. Each person can commit their own
lock to .hlock/locks/harness.<handle>.lock, next to the code it was used on. Anyone with a clone
can then try a teammate's setup in isolation with hlock launch --lock, or
hlock pull it from outside the repository. Add the
hlock badge to your README to point readers at the locks. See
Team repositories for the layout and the commands.
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
Switch harnesses, or go local¶ #
hlock migrate moves a lock onto another harness, Claude Code to Codex
say: skills, MCP servers, and instructions go where the new harness reads them, and models
move to a provider it supports.
hlock localize turns any lock into an equivalent on an open-source
harness and models served by a local runtime like Ollama or LM Studio. It's like
cross-compiling: your MCP servers, skills, and instructions come along. Give it an
eval pack, and it measures the local candidates against your tasks.
Let an agent do the busywork¶ #
Some jobs need judgment, not a script. hlock meta hands them to an
agent, the meta harness, and checks every result:
install: installs what the sync plan leaves to you, then runshlock sync --yes.bootstrap-evals: fills your eval packs with real tasks from your repo.update: moves skills, MCP servers, and plugins to their latest releases.--pinrecords it in the lock.
Use the agent built into hlock, or a harness you already have (Pi, Codex, Goose, OpenCode,
Hermes), on your API key or, with --local, open-weight models. It asks before every
command, or runs --headless against an allowlist.
Then make it better¶ #
A locked harness is a baseline. Once your setup is reproducible, you can measure it: every
lock hlock resolve writes records its success rate, cost, and latency on your own tasks.
The tools will look familiar:
| You know this from | In hlock |
|---|---|
| a test suite | hlock evals init --from-traces : draft an eval pack from the requests you've made to your agent |
pyproject.toml |
harness.toml , themanifest : the models, decision models, and harnesses to try, and what "best" means |
uv lock |
hlock resolve : measure every combination on your evals, and lock the winner with its evidence |
uv lock --upgrade |
hlock upgrade : try newer models, and keep them only if they hold up |
| profile-guided optimization | hlock tune : tune prompts, hyperparameters, and small models on your evals |
Find the best stack for your tasks
Draft an eval pack from the sessions your agent already
logged, list the models and harnesses to try inharness.toml , andhlock resolve locks the winner with its evidence. #
Tune what's inside
hlock tune goes past model choice into prompts, hyperparameters,
and fine-tuned small models, on your evals. Run it offline, on this machine, on a
Flyte cluster for GPUs, or ona backend you write .
Where to next¶ #
- New here? Start withInstallation and theQuickstart .
- Want the mental model? ReadHow it works .
- Sharing a repository? SeeTeam repositories .
- Already using APM? SeeComing from APM : keep
apm.yml, and add what hlock locks and measures on top. - Comparing tools? Seehlock and related tools : APM, chezmoi, Nix, promptfoo, DSPy, and where each one fits.
- Want an agent to do the setup? SeeDelegating to the meta harness .
- Looking something up? See theCLI ,Python API , or
harness.tomlreference.