HLock: Harness Portability for Agent Configs

A tool called hlock was released to package and portably restore AI agent harnesses — the harness version, models, MCP servers, skills, plugins, instruction files and config — into a single hashed harness.lock file that can be committed to git and rehydrated on any machine. Installed via pip, uv or pipx, hlock offers pin, check, sync, launch and run commands modeled on uv and npm, keeps API keys and tokens out of the lock as HLOCK_SECRET_* placeholders, and supports per-contributor locks at .hlock/locks/harness.<handle>.lock for team repositories. The tool also provides hlock migrate to move a lock between harnesses such as Claude Code and Codex, hlock localize to convert a lock to an open-source harness with models served by Ollama or LM Studio, and hlock meta, which hands install, bootstrap-evals and update jobs to an agent and checks every result.

Your agent harness 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 ¶ 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 , the lockfile reference/lockfile/ : every dependency of your harness, pinned and hashed | | pip freeze | hlock pin guides/pin/ : record the setup you already have, and re-pin as it grows | | --locked check | hlock check guides/pin/ keep-it-honest-with-check : show what changed since the pin | | uv sync / npm ci | hlock sync guides/sync/ : rehydrate the locked setup on any machine | | uv run | hlock launch guides/launch/ and hlock run reference/cli/ 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 reference/harnesses/ . - 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 ¶ manage-your-teams-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 guides/pull/ it from outside the repository. Add the hlock badge project/badge/ to your README to point readers at the locks. See Team repositories guides/teams/ 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 ¶ switch-harnesses-or-go-local hlock migrate guides/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 guides/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 guides/eval-packs/ , and it measures the local candidates against your tasks. Let an agent do the busywork ¶ let-an-agent-do-the-busywork Some jobs need judgment, not a script. hlock meta guides/meta/ hands them to an agent, the meta harness , and checks every result: - install : installs what the sync plan leaves to you, then runs hlock 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. --pin records 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 ¶ 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 guides/eval-packs/ draft-a-pack-from-your-traces : draft an eval pack from the requests you've made to your agent | | pyproject.toml | harness.toml , the manifest reference/manifest/ : the models, decision models, and harnesses to try, and what "best" means | | uv lock | hlock resolve guides/resolve/ : measure every combination on your evals, and lock the winner with its evidence | | uv lock --upgrade | hlock upgrade guides/upgrade/ : try newer models, and keep them only if they hold up | | profile-guided optimization | hlock tune guides/tune/ : tune prompts, hyperparameters, and small models on your evals | - Find the best stack for your tasks Draft an eval pack guides/eval-packs/ from the sessions your agent already logged, list the models and harnesses to try in harness.toml , and hlock resolve guides/resolve/ locks the winner with its evidence. - Tune what's inside hlock tune guides/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 guides/backends/ . Where to next ¶ where-to-next - New here? Start with Installation getting-started/installation/ and the Quickstart getting-started/quickstart/ . - Want the mental model? Read How it works concepts/ . - Sharing a repository? See Team repositories guides/teams/ . - Already using APM? See Coming from APM getting-started/apm/ : keep apm.yml , and add what hlock locks and measures on top. - Comparing tools? See hlock and related tools concepts/related/ : APM, chezmoi, Nix, promptfoo, DSPy, and where each one fits. - Want an agent to do the setup? See Delegating to the meta harness guides/meta/ . - Looking something up? See the CLI reference/cli/ , Python API reference/python-api/ , or harness.toml reference/manifest/ reference.