docs

Using the registry

The registry holds agent setups — any of harness.toml, harness.lock, apm.yml, apm.lock.yaml — and APM packages.

hlock CLI

Needs an hlock release with registry support. Log in once; the token goes to your OS keychain.

$hlock login https://app.hlock.ai

$hlock push # → you/<project>@sha-<digest>

$hlock push you/review-bot --version 1.2.0 --dry-run

$hlock search "code review" --kind apm

$hlock pull you/review-bot@1.2.0 # into ~/.hlock/pulls/review-bot/

$hlock pull you/review-bot --into . # write the files into a project

$hlock pull github:owner/repo # remote packages come straight from git

In CI, set HLOCK_REGISTRY=https://app.hlock.ai and HLOCK_REGISTRY_TOKEN to a token from Settings → API tokens.

APM

hlock vault implements APM's Registry HTTP API v1. Add the registry to apm.yml:

registries:
  hlock:
    url: https://app.hlock.ai/api/apm
dependencies:
  apm:
    - registry: hlock
      id: acme/security-baseline
      version: ~1.4.0

$export APM_REGISTRY_TOKEN_HLOCK=hlk_… # a token with the publish scope

$apm publish --package you/my-skill --registry hlock

A project's own apm.yml and apm.lock.yaml aren't an APM package (they have no .apm/); publish those with hlock push, which bundles them with your harness files.

Remote packages

Public GitHub and GitLab repositories that contain any of the four files are indexed without publishing: add one, or let discovery find it. We check the default branch hourly; each change to those files becomes a version named by the commit, recorded in Union Artifacts as a pointer to that commit. Pull them with hlock pull github:owner/repo. Repository owners (signed in with GitHub or GitLab) can remove theirs from the registry.

HTTP API

JSON, RFC 7807 errors, Bearer tokens

POST /api/v1/auth/device	Start a device login (RFC 8628) → device_code, user_code, verification_uri
POST /api/v1/auth/device/token	Poll with {device_code} → access_token, or authorization_pending / slow_down / expired_token / access_denied
GET /api/v1/whoami	Your handle, publishable namespaces and token scopes
GET /api/v1/search?q=&type=&kind=&source=&file=&harness=&mcp=&sort=&page=&per_page=	Search; each result's `pull` is the argument for hlock pull
GET /api/v1/packages/{ns}/{name}	A package and its versions
GET /api/v1/packages/{ns}/{name}/versions/{version\|latest}	One version: digest, files, pull
GET /api/v1/packages/{ns}/{name}/versions/{version}/download	The archive (application/gzip), with Digest and X-Hlock-Digest
PUT /api/v1/packages/{ns}/{name}/versions/{version}	Publish a setup tar.gz (≤ 4 MiB) → 201; 409 if it exists; 422 with extensions.errors

APM endpoints live under /api/apm/v1/packages/{owner}/{repo}/versions[/{version}[/download]].