The fastest way to run the full stack locally is with Kind. A single make target creates the cluster, builds the server image, and installs AgentRegistry via Helm — a PostgreSQL instance with pgvector is bundled and deployed automatically by the Helm chart for local development.
kindis installed automatically into./bin/kindbymake install-tools— no manual installation needed.
make setup-kind-clusterThis runs two steps in order:
| Step | Target | What it does |
|---|---|---|
| 1 | create-kind-cluster |
Installs kind to ./bin/, creates Kind cluster + local registry (localhost:5001) + MetalLB |
| 2 | install-agentregistry |
Builds server image, pushes to local registry, Helm installs AgentRegistry (bundled PostgreSQL with pgvector override for local dev) |
Each target can also be run independently — useful when iterating on code:
# Rebuild and redeploy after a code change (cluster and PG stay up)
make install-agentregistry
# Skip image builds if the images are already up to date
make install-agentregistry BUILD=falseinstall-agentregistry automatically runs charts-generate first (see Helm Chart Generation below), so Chart.yaml is always up to date before deploying.
On subsequent runs, install-agentregistry reuses the jwtPrivateKey already stored in the cluster secret so tokens remain valid across redeploys.
# AgentRegistry API/UI
kubectl --context kind-agentregistry port-forward -n agentregistry svc/agentregistry 12121:12121
# open http://localhost:12121
# Bundled PostgreSQL (for direct inspection)
kubectl --context kind-agentregistry port-forward -n agentregistry svc/agentregistry-postgresql 5432:5432
psql -h localhost -U agentregistry -d agentregistrymake delete-kind-clusterSee scripts/kind/README.md for more detail on configuration, troubleshooting, and overriding defaults.
charts/agentregistry/Chart.yaml is generated from charts/agentregistry/Chart-template.yaml using envsubst and is not committed to the repository. Any helm command run directly against the chart directory will fail unless Chart.yaml exists.
# Generate with version derived from the latest git tag (e.g. 0.3.0)
make charts-generate
# Generate with an explicit version
make charts-generate CHART_VERSION=0.4.0CHART_VERSION defaults to the output of git describe --tags --abbrev=0 with the leading v stripped. If there are no tags, set it explicitly.
Any Makefile target that needs Chart.yaml (e.g. charts-lint, charts-test, charts-package, install-agentregistry) declares charts-generate as a prerequisite and will generate it automatically. You only need to run make charts-generate directly if you're invoking helm commands by hand.
Because charts/agentregistry/Chart.yaml is gitignored, some editors may flag it as untracked. This is expected — treat Chart-template.yaml as the source of truth and do not commit the generated Chart.yaml.
The full release pipeline is encapsulated in a single target:
# Requires HELM_REGISTRY_PASSWORD to be set; optionally HELM_REGISTRY_USERNAME
make charts-release CHART_VERSION=0.4.0This runs in order: charts-test → charts-push (lint → package → push) → charts-checksum.
make run # starts registry server + daemon via docker-compose
make down # stops everythingThe UI is available at http://localhost:12121.
Tech stack: Go 1.25+ · PostgreSQL + pgvector (pgx) · Huma (OpenAPI) · Cobra (CLI) · Next.js 14 (App Router) · Tailwind CSS · shadcn/ui
For a detailed breakdown of layers, conventions, and contribution guidelines see AGENTS.md.
# UI only (hot reload)
make dev-ui
# Build CLI binary
make build-cli
# Build server binary
make build-server
# Build UI static assets
make build-ui