Supported harnesses¶

hlock supports agent CLIs, autonomous agents, agent frameworks, and local inference runtimes. Each one is described by a profile, a TOML file that tells hlock where the harness keeps its config, model, MCP servers, skills and plugins, and how it was installed. These tables are generated from the built-in profiles, so they match the version of hlock these docs are for. hlock harness list shows the same harnesses, and which of them are installed on your machine.

Agent CLIs¶

Name in hlock is what you pass to --harness or put in [target] harness. Any alias in parentheses works too. Installs from lists the install methods hlock recognizes, most preferred first. A lock records which one the installed copy came from, and hlock sync --install uses it.

Support says how complete and well-tested the profile is:

• full: everything pin, sync and launch read is described and maintained.
• basic: detection, version, MCP servers and skills are covered. The rest of the profile may be partial or less tested, so reports and fixes are welcome.

What hlock captures¶

Deciders are the decision-model uses hlock can wire into the harness: through hooks in its config, a plugin hlock writes, or, when recorded, a setting of the harness's own that pin reads.

• Model: the configured model, which pin records and launch passes to the harness.
• Providers: custom model providers and their base URLs, from the harness's config.
• MCP servers and Skills: pinned, synced, and written into the harness's config by launch.
• Plugins: plugins or packages installed into the harness, pinned with their versions.
• Instructions: the project instruction files the harness reads. Its config root usually holds a global one as well.
• localize: whether hlock localize can move a lock onto this harness with local models. ✓ means it's open source and can use a local endpoint. with --harness means it can use a local model but isn't open source, so localize uses it only when you ask for it. by hand means localize can move a lock onto it, but doesn't know the harness's settings for a local endpoint, so it tells you what to set.

Every agent CLI also runs one prompt non-interactively with hlock run.

Autonomous agents¶

Autonomous agents run on their own instead of in a session you drive. Each one is a long-running gateway that you message from chat apps (Telegram, Slack, WhatsApp, …). It wakes itself on heartbeats and schedules, and keeps a workspace of persona files, skills, and memory it writes as it goes. To hlock they're agent CLIs, so pin, check, sync, launch, run and localize work the same way. hlock harness list lists them in their own group.

Instructions here are the persona and operating files in the agent's workspace, under its config root. hlock pins the files you write: who the agent is (SOUL.md, IDENTITY.md), how it works (AGENTS.md, TOOLS.md) and who it works for (USER.md). It leaves out what the agent writes as it runs, such as MEMORY.md, memory/, HEARTBEAT.md, sessions and cron state. A conversation therefore isn't drift, but a changed persona is, and hlock sync restores the pinned one.

What hlock doesn't do for these agents:

• Run the gateway. hlock launch and hlock run start the agent's CLI. run sends one message and waits for the reply, for example openclaw agent exec, nanobot agent -m, or picoclaw agent -m. Keeping a gateway running, and the channel accounts it logs into, stay with the agent's own service commands.
• Pin channel credentials. Bot tokens in the agent's config are secrets. hlock handles them like any other secret and never writes them into a lock.
• Evaluate them in trials. As with the other agent CLIs, hlock resolve runs trials on the reference adapter.

Notes on each agent:

• OpenClaw keeps its config in JSON5. hlock reads JSON5 and writes plain JSON, which OpenClaw also reads, so comments in the file don't survive a sync. hlock pins the default workspace, ~/.openclaw/workspace. If agents.defaults.workspace points somewhere else, copy the profile and change the paths. --model is a flag of OpenClaw's subcommands, so when you hlock launch openclaw with another harness's lock, OpenClaw keeps its own model and launch says so. On Ollama, localize uses OpenClaw's native ollama API, because OpenClaw calls tools unreliably through Ollama's /v1 endpoint.
• nanobot moves its home with nanobot --home, not with an environment variable, so an isolated launch relocates HOME instead. A modelPreset in its config takes precedence over agents.defaults.model, which is the model pin records. localize therefore sets a preset.
• PicoClaw's model is a model_name that refers to an entry in model_list, and pin records that name. hlock doesn't read API keys kept in .security.yml. MCP servers need tools.mcp.enabled set to true.
• ZeroClaw chooses a model per agent, so pin records the whole config.toml instead of a model. hlock reads instruction files and skills from the workspace of the assistant agent, the name used in ZeroClaw's quickstart examples. hlock run messages that agent too. ZeroClaw has no localize settings yet, so localize tells you what to set by hand.
• IronClaw manages MCP servers as extensions and keeps its identity files in its memory store, so hlock pins neither. It pins the model, the provider and config.toml.

Hermes Agent is listed here because it also runs as a gateway. It's as fully supported as the agent CLIs above. NanoClaw isn't supported: it's a git checkout that you customize by editing its code, and its settings live in a SQLite database rather than in a config file a profile can describe.

Agent frameworks¶

Framework profiles are building blocks for your own agent. Declare a project harness with framework = "<name>" and an entrypoint or command, and hlock pins the framework's packages along with your agent.

An agent written from scratch, with no framework, works too: give the project harness a command or an entrypoint and list its packages.

Local inference runtimes¶

hlock localize serves local models with these runtimes, and hlock pin recognizes a model provider whose base URL points at one of their ports. hlock runtime list shows which are installed. Ollaya serves only decision models; Ollama serves those (Kev) as well as LLMs.

Add a harness¶

If your harness isn't listed, you can add it without changing hlock's code:

1. Write a profile. Copy the built-in profile closest to your harness from crates/harness-lock-core/profiles/harnesses and edit it. Harness profiles describes every field.

2. Try it locally. Put the file in .hlock/profiles/harnesses/ in your project, or in ~/.config/hlock/profiles/harnesses/ to use it everywhere. Then check that hlock reads it the way you expect:

   $ hlock harness show my-agent
   ╭─ My Agent ───────────────────────────────────────────────────────────────────────╮
   │                                                                                  │
   │  id               my-agent                                                       │
   │  kind             cli                                                            │
   │  support          basic                                                          │
   │  installed        no                                                             │
   │  config root      /Users/you/.my-agent  ($MY_AGENT_HOME)                         │
   │  file · settings  /Users/you/.my-agent/settings.json  (missing)                  │
   │  skills           /Users/you/.my-agent/skills  (missing)                         │
   │  profile          /Users/you/my-project/.hlock/profiles/harnesses/my-agent.toml  │
   │                                                                                  │
   ╰──────────────────────────────────────────────────────────────────────────────────╯
   

   hlock harness show prints the paths the profile resolves to on your machine, and whether each one exists. Then pin a setup with hlock pin --harness my-agent and look at what lands in harness.lock.

3. Contribute it. Open a pull request that adds the profile to crates/harness-lock-core/profiles/harnesses/ with support = "basic", and regenerate this page with uv run python scripts/harness_table.py. To mark it full, show in the pull request that pin, sync and launch work with it, and add tests. See Contributing.

The same steps fix a built-in profile that has a path wrong for your setup: a profile with the same id replaces the built-in one.