How to Use hlock: The Beginner's Guide
CodexFuse Team · 2026-11-04T17:39:10.624Z · 12 min read min read
An hlock tutorial for beginners: install the CLI, pin your agent stack with hlock pin, commit the harness.lock file, sync it anywhere, and use evals to find a better setup — with commands verified against the current docs.
If you have ever spent weeks tuning Claude Code on your laptop — the skills, the MCP servers, the config — and then sat down at a second machine to find none of it there, this hlock tutorial is for you. Learning how to use hlock means learning the lockfile layer for your AI agent stack: one command pins the harness, models, MCP servers, skills, plugins, and config you actually run into a hashed harness.lock file that you commit to git and restore on any machine.
One clarification before we start: this is hlock the Rust-powered agent-setup tool from the unionai-oss GitHub organization — not the step-security Go package for process locking, not the H.LOCK button on a Haier TV remote, not the classic Macintosh HLock memory routine, and not the HLOCK trading indicator for MetaTrader. The search page mixes all four, so pin the name to the product: an AI-agent setup lockfile. If you have not set up an agent harness yet, read the Claude Code beginner guide first — hlock pins the setup you already have; it does not install the harness for you.
What Is hlock, Exactly?
hlock is a packaging layer for your AI agent setup, written in Rust: it pins your harness, models, MCP servers, skills, plugins, and config into a hashed harness.lock file, so you can commit it to git and restore the exact setup anywhere.
The idea is older than agents. Every package manager learned that "works on my machine" is a dependency problem, and lockfiles were the fix. hlock applies the same fix one level up: your agent's whole working environment becomes a pinned, hashed, version-controlled artifact. The project's own description is honest about its age: "hlock is in early development. Expect rough edges and breaking changes between releases." (PyPI, fetched November 4, 2026.)
As of this writing, hlock 0.9.0 shipped November 1, 2026 on PyPI — four days ago — from a repository created October 16, 2026, with 14 stars, 1 fork, and 239 commits at the time of checking (November 4, 2026; the number moves). The core is Apache 2.0 open source, the Rust core ships precompiled inside the Python wheel, and the my2cents.ai launch writeup describes it as a Union.ai project. Treat every version number below as current as of November 2026 and re-check the docs before relying on a flag.
What Does hlock Actually Lock?
The full stack your agent runs on: the harness version, the models and local runtimes it uses, MCP servers, skills, plugins, instruction files, and config — each recorded with a digest so you can see when anything drifted.
That digest part matters. A lockfile is not a backup of your dotfiles; it is a fingerprint of the working setup. When hlock pins Claude Code, Codex, Pi, OpenCode, Cursor, or Gemini CLI — or autonomous agents like OpenClaw — it records what each piece is, with hashes, so a later check can tell you exactly what changed instead of just "something broke."
Secrets never land in the lock as values. API keys and tokens become HLOCK_SECRET_* placeholders in the file, the lock stays safe to commit, and you supply the real values when you sync. (docs.hlock.ai, fetched November 4, 2026.)
How Do I Install hlock?
With pip: pip install hlock. No Rust toolchain, no accounts, no API keys — the Rust core ships precompiled inside the wheel.
pip install hlock # or: uv add hlock · uvx hlock --help
hlock --helpPrebuilt wheels cover Linux (x86_64 and aarch64), macOS (arm64 and x86_64), and Windows (x64) for CPython 3.9 and newer — the wheels are cp39-abi3, so any Python 3.9+ works. The docs homepage also lists uv tool install hlock and pipx install hlock as options, and Rust developers can use cargo add hlock. A Rust toolchain is only needed if you want to develop hlock itself; the separate harness-lock-core crate is published on crates.io for that side of the world.
How Do I Pin My Current Setup?
Run hlock pin inside your project. It records your harness, models, MCP servers, skills, plugins, and config into harness.lock — then you commit it. The five-step arc:
- Run hlock pin — records the project's own skills, MCP servers, and config. Your personal setup stays out of the repository.
- Run hlock pin --user if you also want your personal setup (for example ~/.claude) in the lock.
- Commit it: git add harness.lock .hlock/ — secrets are placeholders, never values. If you are new to version control, the Git beginner guide walks through your first repository.
- Run hlock audit — it checks integrity, hidden characters, what the setup runs, policy, and secrets before you share the lock.
- Run hlock check later — it shows what changed since the pin; re-pin to lock the new state.
If OpenCode is the harness you run, the OpenCode beginner guide is the companion read here — hlock pins whichever harness you already use, from Claude Code and Codex to Pi, OpenCode, Cursor, and Gemini CLI.
What Is harness.toml vs harness.lock?
harness.toml is the manifest — the models, harnesses, and decision models you want to try, and what "best" means. harness.lock is the pinned, hashed result — what actually worked, with the evidence attached.
The docs draw the package-manager parallel explicitly, and it is the fastest way to learn the vocabulary:
| You know this from | In hlock |
|---|---|
| uv.lock / Cargo.lock | harness.lock: 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 |
| 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, the manifest |
| uv lock | hlock resolve: measure every combination, lock the winner with its evidence |
| uv lock --upgrade | hlock upgrade: try newer models, keep them only if they hold up |
| profile-guided optimization | hlock tune: tune prompts, hyperparameters, small models on your evals |
hlock init --name demo writes a starter harness.toml. hlock resolve is the uv lock analog: it measures every combination on your evals and locks the winner — success rate, cost, latency, plus the evidence — into harness.lock.
How Do I Sync a Pinned Setup to a New Machine?
On the new machine, run hlock sync. It rehydrates the locked setup into .hlock/env — or in place, or into a container, with the --in-place and --docker flags.
Teams pin per person: each developer writes their own lock to .hlock/locks/harness.<handle>.lock, and anyone can try a teammate's stack with hlock launch --lock .hlock/locks/harness.bob.lock. You can also pull a published setup straight from GitHub — hlock pull github:alice/agents, then hlock launch --lock alice — or declare a new dependency with hlock add skill github:anthropics/skills/skills/pdf, which pins and installs it in one step.
The secrets flow stays honest the whole way: the lock holds HLOCK_SECRET_* placeholders, and you supply the real values at sync time. If you take the container route, the Docker beginner guide covers the engine that hlock sync --docker runs on.
How Do I Run Something on the Locked Setup?
hlock launch starts a session on the locked setup, isolated from your own config; hlock run executes a single prompt through it.
hlock launch # start a session on the locked setup
hlock run "summarize README.md" # run one prompt through itUnder the hood, hlock run routes through the harness you pinned — claude -p, codex exec, and their equivalents — so the locked stack is the one doing the work, not whatever happens to be installed on the machine.
How Do I Find a Better Stack Instead of Just Pinning This One?
Write an eval pack, then let hlock resolve measure candidate stacks against it and lock the winner — with the evidence — instead of guessing.
hlock evals init -t coding (or data, research, or support) writes an eval-pack template plus an Agent Skill, so the agent you already use can fill it with real tasks from your project. Even faster: hlock evals init --from-traces drafts the eval pack from the requests you have already made to your agent, reading the sessions Claude Code, Codex, and Pi logged for the project.
From there, hlock tune does profile-guided optimization — prompts, hyperparameters, and small fine-tuned models — on your evals, and hlock upgrade tries newer models and keeps them only if they hold up. The built-in reference provider is offline and deterministic, so the whole loop runs on a laptop with no API keys. The available backends are offline (the default, an in-process Rust reference harness that is CI-friendly), local (a Python worker), flyte (Flyte 2 tasks with GPUs), or a custom backend of your own.
Two more tools round out the picture: hlock migrate --to codex moves a lock onto another harness, and hlock localize moves it onto an open-source harness with models served by Ollama or LM Studio. And hlock meta delegates judgment work to a pinned "meta harness" agent — install, bootstrap-evals, and update are the subcommands, the default agent is built into hlock, and you can also point it at Pi, Codex, Goose, OpenCode, or Hermes with your own API key. There is also a Python API: import hlock, describe a SearchSpace, and hlock.resolve writes ./harness.lock for you.
Should I Use hlock, or Just Commit My Config Files?
If your agent setup lives on one machine and rarely changes, commit the config files. If the setup moves between machines, teammates, or CI, pin it with hlock.
| If you… | Use this | Why |
|---|---|---|
| Run one agent on one machine | Commit the config files | hlock adds a layer you don't need |
| Set up the same stack on a second machine | hlock sync | One command rehydrates the locked stack |
| Onboard a teammate to your agent setup | hlock pull + launch --lock | They get your pinned stack, not a setup doc |
| Run agents in automated pipelines | harness.lock + hlock check | The --locked analogy: drift between runs becomes visible |
| Want to compare model/harness choices | hlock resolve + evals | The winner is measured, with evidence — not argued |
Five Beginner Mistakes to Avoid
Almost every hlock beginner trips on one of these, and most trace back to the project's age:
| Mistake | What happens | Do this instead |
|---|---|---|
| Pinning before you have a working harness | The lock records a setup that never ran | Install and run your harness first, then pin what works |
| Using plain hlock pin and missing your personal config | Plain pin records only the project's own setup | Add --user when you want ~/.claude and friends in the lock — but not in shared repos |
| Committing the lock without auditing it | Integrity issues and secrets ride along | Run hlock audit first — integrity, hidden characters, policy, secrets |
| Treating 0.9.x commands as a stable API | Breaking changes between releases | Pin the hlock version in your requirements; the project says so itself |
| Following 0.1.2-era guides | Old commands (lock, show, tree) no longer exist | Re-pin with the current CLI; harness-lock 0.1.2 is superseded |
What's New in hlock Right Now?
hlock 0.9.0 shipped November 1, 2026 — four days ago — on a project whose repository is seventeen days old. The v0.5.0 release on October 21, 2026 was the one the my2cents.ai launch writeup covered on October 22, and the pace since — 9 releases, 12 tags, 239 commits — is exactly what the project's own "early development" warning predicts.
On the packaging side, the PyPI release carries a source distribution plus five wheels with provenance attestations (33.4 MB total), the harness-lock-core Rust crate is live on crates.io, and there is a harness-lock package on PyPI that pins the matching hlock release as an alias. Do not confuse it with the older standalone harness-lock 0.1.2 from October 17, 2026 — that early CLI (init, lock, show, check, tree, run, backend) is superseded, and the pure-Python reference implementation now lives under python-legacy/ in the repo.
Sources
The PyPI hlock page (pypi.org/project/hlock/, fetched November 4, 2026) documents version 0.9.0 (November 1, 2026), the install commands, the pin/check/sync/launch/run quickstart, the full current command list, the package-manager analogy table, the built-in offline reference provider, the Python API, and the four backends; the docs.hlock.ai homepage (fetched November 4, 2026) documents harness.toml vs harness.lock, the HLOCK_SECRET_* placeholders, team locks under .hlock/locks/, the meta harness and its subcommands, evals/tune/upgrade, migrate/localize, and the supported-harness list including OpenClaw; the unionai-oss/hlock GitHub repository (fetched November 4, 2026) documents the tagline "Make your agent setup portable", the October 16, 2026 creation date, the 14-star / 1-fork / 0-watcher snapshot, 239 commits, the Apache 2.0 license, and the python-legacy note; the my2cents.ai launch writeup (October 22, 2026, fetched November 4, 2026) documents v0.5.0 released October 21, 2026, the Union.ai attribution, the pin/sync/launch/audit description, and the early-development framing; crates.io/crates/harness-lock-core (fetched November 4, 2026) documents the Rust core crate listing; pkg.go.dev/github.com/step-security/agent/lockfile (fetched November 4, 2026) documents the Go process-locking package used for disambiguation; Haier TV manuals (via web search, fetched November 4, 2026) document the H.LOCK remote button used for disambiguation; Inside Macintosh / Classic Mac OS memory management (via web search, fetched November 4, 2026) documents the HLock memory routine used for disambiguation; winoption.net/hlock (fetched November 4, 2026) documents the HLOCK trading indicator used for disambiguation.
Frequently Asked Questions
Is hlock free to use?
Yes — hlock is open source under Apache 2.0 and installs with pip; it charges nothing itself. The model usage underneath still bills through whichever provider your harness uses.
Does hlock replace my harness's own config files?
No. hlock is a lockfile layer, not a new config format: it pins the configs, skills, MCP servers, and models you already have, and your harness keeps reading its own files. Think uv.lock next to pyproject.toml, not instead of it.
Is the 0.x instability a problem for beginners?
Only if you ignore the project's own warning. Pin the hlock version in your requirements, re-pin the lock after you upgrade, and treat any guide older than a few weeks as suspect — including this one, eventually.
What is the difference between hlock pin and hlock pin --user?
Plain hlock pin records only the project's own skills, MCP servers, and config, so your personal setup stays out of the repository. The --user flag adds your personal setup (like ~/.claude). Use --user for your own machines, never for a shared repo.
Can I try the eval and resolve loop without paying for API calls?
Yes. The built-in reference provider is offline and deterministic, and the default offline backend runs the whole measure-and-lock loop on your laptop with no API keys.
