HLock: Harness Portability for Agent Configs

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

~/projects/my-app

Lock the harness you already have¶

If you've used uv, cargo, or npm, you already know the shape of hlock:

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.

API keys and tokens become HLOCK_SECRET_* placeholders, so the lock is safe to commit. You supply the values when you sync.

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.

hlock launch starts your harness in an isolated environment that matches the lock, with none of the unlocked config on your machine.

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.

Some jobs need judgment, not a script. hlock meta hands them to an agent, the meta harness, and checks every result:

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.

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:

Draft an eval pack from the sessions your agent already logged, list the models and harnesses to try in harness.toml, and hlock resolve locks the winner with its evidence.

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 on a backend you write.