Publishing Packages

What you'll accomplish: Create, build, lint, and publish packages to a registry with automatic provenance.

Package workflow

Every package published to a Hoziron registry receives a cryptographic provenance signature automatically. The registry signs on behalf of the authenticated publisher — no local signing keys needed.

1. Scaffold

hoziron package init --type competency --name my-package

Package types: tool, skill, competency, agent-template, workflow-template, integration

2. Write the MANIFEST.toml

[package]
type = "competency"
name = "my-package"
version = "1.0.0"
description = "What this package does"
license = "MIT"
min_platform_version = "0.5.0"

[package.author]
name = "Your Company"
email = "platform@company.com"

[package.metadata]
keywords = ["insurance", "claims"]
categories = ["insurance"]

[dependencies]
postgresql-connector = "^2.0"

3. Build

hoziron package build ./my-package/

Produces a deterministic .hpkg archive (tar.gz, reproducible builds). Computes a SHA-256 content hash of the payload directory for integrity verification.

4. Lint

hoziron package lint ./my-package/

Validates name, version, description, license, dependencies, and taxonomy categories.

5. Publish

hoziron package publish ./my-package/

The publish command runs the full pipeline: lint → build → upload. On upload, the registry:

1. Authenticates the publisher via their API key
2. Validates the manifest (semantics, taxonomy, license compatibility)
3. Computes the archive hash (SHA-256 of the .hpkg tarball)
4. Signs the provenance payload: name:version:publisher_id:archive_hash:timestamp
5. Stores the archive and provenance metadata

Publish target resolution:

1. Explicit --registry <name> flag
2. Scope-based routing (@scope/name prefix)
3. default_publish_registry config field

Provenance

Every published package includes:

This guarantees: every package in the catalog has a verifiable chain of custody back to an authenticated publisher.

Verification

Verify package integrity locally (content hash):

hoziron package verify ./my-package/

Verify provenance (publisher identity + registry signature):

hoziron package verify ./my-package/ --provenance

The --provenance flag contacts the registry to fetch the signature metadata and the registry's public key, then verifies the Ed25519 signature locally.

Authentication

Publishing always requires authentication. Bootstrap your first API key:

# On a fresh registry with no keys (bootstrap bypass)
curl -X POST http://registry:4210/keys \
  -H 'Content-Type: application/json' \
  -d '{"name": "ci-publisher", "role": "developer"}'

Configure the key in your environment (the CLI uses it when publishing):

export HOZIRON_REGISTRY_TOKEN="hzk_..."

Size limit

Maximum package size: 50 MB (enforced by the registry on upload).

Registry signing key

The registry's public key is available at:

curl http://registry:4210/signing-key
# → {"key_id": "registry-abcd1234", "public_key": "ed25519:...", "algorithm": "ed25519"}

Clients use this to verify provenance signatures offline after downloading a package.

Next steps

• Private registries
• Collections
• Competency authoring

Related:

• Browsing and installing
• Private registries