Running your own registry
The conceptual pieces a registry needs — a Postgres database, S3-compatible object storage, and the API server — and how to point the CLI at it.
A registry is three moving parts: a Postgres database for metadata, an S3-compatible object store for the skill archives, and the API server that ties them together and speaks to the CLI. This page describes what each part is for and how the CLI finds your registry once it's running.
Self-hosting is developer-oriented and evolving. The pieces below run today for local development against the reference server, but there is no one-command production deployment yet. Treat this as the current shape, not a hardened production install guide.
The three parts
A Postgres database
All registry metadata — organizations, skills, versions, dist-tags, tokens, the audit log — lives in Postgres. The schema is applied by migrations rather than by hand, so a fresh database is brought up to the current shape by running them. The project develops against a recent Postgres release.
S3-compatible object storage
Skill archives are content-addressed blobs stored in an S3-compatible bucket. Anything that speaks the S3 API works — the project uses MinIO locally, and the same code paths target other S3-compatible stores. Uploads and downloads go through short-lived presigned URLs, and the store is used in path-style addressing.
The API server
The server hosts the API the CLI talks to: the RPC handler, the REST façade, the device-login pages, and the publish/scan/upload flow. A reference server lives in the repository so the CLI can be exercised end to end.
The reference server is a developer harness, not a production binary. It exists to run and test the API locally; it is explicitly throwaway-thin and isn't a supported product surface. A production deployment story is still taking shape.
The local development stack
For local work, the repository ships a Docker Compose stack that brings up Postgres and MinIO together, initializes the bucket, and gives you the two backing services the reference server needs. The example environment file documents every variable with a working local default, so the sequence is short:
Copy the example environment file. It ships with a working local default for every variable — see Configuration for what each one controls.
Bring the Compose stack up. This starts Postgres and MinIO and initializes the bucket, giving the reference server both backing services.
Run the reference server against it. With the two backing services up and the environment file in place, the server can serve the API the CLI talks to.
You need Docker (for the Compose stack) and Node (for the reference server) available locally. The example environment file's defaults assume the Compose Postgres and MinIO are the ones the server connects to.
Pointing the CLI at your registry
Once a registry is reachable, aim the CLI at it. The registry URL resolves, in order of precedence, from a command-line flag, the registry-URL environment override, then project and global config:
skillhub config set registryUrl https://registry.internal.exampleYou can also set it for a single command with --registry-url, or export the
registry-URL environment variable so every command in a shell or CI job targets
your registry without any stored config. All three routes are described on the
config page, and the environment override is listed in
Configuration.