# HLock: Harness Portability for Agent Configs > Source: > Published: 2026-10-29 02:01:20+00:00 # 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..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.