A vendor-neutral, agent-framework-agnostic registry for AI agents, skills, and MCP servers.
Built on open standards: A2A AgentCard for agents, MCP server.json for MCP servers, and Agent Skills for skills.
Stores metadata alongside OCI registries. Accepts evaluation signals from external tools. Enforces a promotion lifecycle. Works with any agent framework. Does not store binaries or compute trust scores.
go build -o agentctl ./cmd/agentctl
./agentctl server start
open http://localhost:8080
Full narrated walkthrough (2 min)
Slide deck covering the problem, architecture, and workflow:
The server embeds a catalog UI at the root URL. Browse artifacts by kind, filter by status, search across all kinds, and click through to see identity, OCI references, eval records, promotion history, and resolved dependencies.
You build an agent agentctl does the rest Others find it
────────────────── ──────────────────── ──────────────
docker push image ──> agentctl push agents card.json agentctl search "k8s"
--namespace acme agentctl inspect ...
--oci ghcr.io/acme/agent:1.0 agentctl deps ...
(draft — private, mutable) agentctl get ... --format a2a
or ──> agentctl init --path . # import from a running agent
(LLM generates AgentCard) agentctl import --from-a2a \
https://agent/.well-known/agent-card.json
──> agentctl eval attach ...
(external tools submit results) # export for deployment
agentctl get agents acme/x 1.0 \
──> agentctl promote --to evaluated --format a2a > agent-card.json
──> agentctl promote --to approved # serve at /.well-known/agent-card.json
──> agentctl promote --to published
Each artifact kind uses an open standard as its native identity format. The registry wraps it with governance.
| Kind | Standard | What it carries | What the registry adds |
|---|---|---|---|
| Agent | A2A AgentCard | Name, version, skills, capabilities, security, signatures | BOM, evals, promotion, provenance, trust |
| MCP Server | MCP server.json | Name, version, packages, transport | BOM, evals, promotion, provenance, trust |
| Skill | Agent Skills (SKILL.md) | Name, description, instructions | BOM, evals, promotion, provenance, trust |
Push a standard document directly. Pass an A2A AgentCard, MCP server.json, or SKILL.md with --namespace and --oci. The registry extracts identity from the standard doc.
agentctl push agents agent-card.json \
--namespace acme --oci ghcr.io/acme/my-agent:1.0.0Or generate one. Point agentctl init at your project. An LLM scans source code, Dockerfile, dependencies, and README to produce a manifest. No manual YAML writing.
agentctl config set init.provider openai
agentctl config set init.model gpt-4o-mini
agentctl init --path ./my-agent --image ghcr.io/acme/my-agent:1.0.0 -o manifest.yamlWorks with Anthropic (Messages API), OpenAI (Chat Completions, Responses API), or any compatible endpoint (Ollama, vLLM, LiteLLM) via --base-url.
Or use a full registry manifest. The legacy YAML format still works.
agentctl push agents manifest.yamlAttach eval records (optional). The registry stores results from external tools. It does not run evaluations.
agentctl eval attach agents acme/my-agent 1.0.0 \
--category safety --provider garak --benchmark toxicity --score 0.96Promote. Each step is a valid transition. Content becomes immutable after evaluated.
agentctl promote agents acme/my-agent 1.0.0 --to evaluated
agentctl promote agents acme/my-agent 1.0.0 --to approved
agentctl promote agents acme/my-agent 1.0.0 --to publishedDiscover, inspect, deploy.
agentctl search "kubernetes diagnostics"
agentctl inspect agents acme/my-agent 1.0.0
agentctl deps agents acme/my-agent 1.0.0
agentctl get agents acme/my-agent 1.0.0 # read OCI ref, then docker pullagentctl config init Interactive LLM provider setup
agentctl config set <key> <value> Set config value
agentctl config show Show config
agentctl init -p ./project -o out.yaml Generate manifest from code (LLM)
agentctl push <kind> <file> Register artifact (draft)
agentctl push <kind> <file> --namespace <ns> --oci <ref> Push standard doc (AgentCard, server.json, SKILL.md)
agentctl get <kind> <name> [version] [--format a2a|server-json|skill-md] Get artifact details
agentctl list <kind> List artifacts
agentctl delete <kind> <name> <version> Delete draft
agentctl promote <kind> <name> <ver> --to <status>
agentctl eval attach <kind> <name> <ver> --category --provider --benchmark --score
agentctl eval list <kind> <name> <ver>
agentctl inspect <kind> <name> <ver> Status + evals + promotion history
agentctl deps <kind> <name> <ver> Dependency graph from BOM
agentctl search <query> Full-text search across all kinds
agentctl import --from-a2a <url> --namespace --oci Import agent from A2A AgentCard URL
agentctl server start [--port] [--db] Start server (UI at /, API at /api/v1)
<kind> is agents, skills, or mcp-servers.
All under /api/v1. Responses wrapped in { "data": ..., "_meta": {...}, "pagination": {...} }. Errors follow RFC 7807.
| Method | Path | |
|---|---|---|
| GET | /{kind} |
List |
| POST | /{kind} |
Create (draft) |
| GET | /{kind}/{ns}/{name}/versions/{ver} |
Get |
| DELETE | /{kind}/{ns}/{name}/versions/{ver} |
Delete (draft only) |
| POST | /{kind}/{ns}/{name}/versions/{ver}/promote |
Promote |
| POST | /{kind}/{ns}/{name}/versions/{ver}/evals |
Submit eval |
| GET | /{kind}/{ns}/{name}/versions/{ver}/evals |
List evals |
| GET | /{kind}/{ns}/{name}/versions/{ver}/inspect |
Inspect |
| GET | /{kind}/{ns}/{name}/versions/{ver}/dependencies |
Deps |
| GET | /{kind}/{ns}/{name}/versions/{ver}/export |
Export standard doc |
| GET | /search?q=... |
Search |
| GET | /ping |
Health |
go build -o agentctl ./cmd/agentctl
./agentctl server start --port 8080
# API at http://localhost:8080/api/v1, UI at http://localhost:8080make image # build image (multi-stage, distroless runtime)
make image push # build and push to quay.ioThe image is quay.io/azaalouk/agent-registry. Override with IMAGE_REPO and IMAGE_TAG:
make image push IMAGE_REPO=quay.io/myorg IMAGE_TAG=v0.2.0make deploy OVERLAY=k8sThis creates a namespace agent-registry with a Deployment, Service, and health probes. Access via port-forward:
kubectl -n agent-registry port-forward svc/agent-registry 8080:8080
open http://localhost:8080make deploy # OVERLAY=openshift is the defaultThis creates the namespace, Deployment, Service, and a TLS Route. Get the URL:
oc -n agent-registry get route agent-registry -o jsonpath='{.spec.host}'The deployment runs as non-root with a read-only root filesystem, passes the restricted SCC without any grants.
make undeploy # removes all resources| Target | Description |
|---|---|
make build |
Compile binary locally |
make image |
Build container image |
make push |
Push to container registry |
make deploy |
Create namespace and apply manifests |
make undeploy |
Delete all deployed resources |
make clean |
Remove local build artifacts |
cmd/agentctl/ Entry point (thin — embeds UI, calls cli package)
cmd/server/ Standalone server entry point
internal/
cli/ Cobra commands (HTTP calls + output formatting only)
handler/ HTTP handlers (parse request, call service, write response)
service/ Business logic (promotion state machine, BOM resolution)
store/ Storage interface + SQLite (swappable to Postgres)
model/ Go types matching spec schemas
server/ Chi router, middleware, serves embedded UI
pkg/client/ HTTP client (used by CLI, usable by any Go program)
ui/index.html Catalog UI (embedded in binary, served at /)
schemas/ JSON Schemas (spec source of truth)
api/openapi.yaml OpenAPI 3.1 spec
deploy/
Dockerfile Multi-stage build (distroless runtime)
k8s/base/ Deployment, Service, Kustomization
k8s/overlays/ openshift (+ Route) and k8s overlays
Makefile build, image, push, deploy, undeploy
scripts/ Demo setup/teardown scripts
docs/ Presentation, architecture diagrams, screenshots
Standards for identity, registry for governance. Each artifact kind uses an open standard (A2A AgentCard, MCP server.json, Agent Skills) as its native identity and capability format. The registry wraps these with governance: promotion lifecycle, evaluation records, BOM, provenance, and trust signals. The standard document answers "what is this and how do I use it?" The registry answers "should I trust it, what does it depend on, and who says it's ready?"
Metadata, not payloads. The registry indexes OCI artifacts. Binary content stays in ghcr.io / quay.io / ECR.
Three artifact kinds share promotion lifecycle, eval records, and BOM. They differ in their standard identity document and BOM structure: agents declare models + tools + skills, skills declare tool requirements, MCP servers declare runtime dependencies + external services.
Evals are external signals. The registry accepts eval records from any tool (Garak, eval-hub, lm-eval-harness, custom CI). It does not run evaluations or compute trust scores. Trust scoring is a separate concern.
Promotion is a state machine. draft -> evaluated -> approved -> published -> deprecated -> archived. No hardcoded gates. Policy layers can be added externally.
Import and export. Push a standard document directly, or import from a URL (/.well-known/agent-card.json). Export the standard document for deployment with no governance wrapping.
CLI is a thin client. All logic is server-side. Any entry point (CLI, curl, UI, CI pipeline) behaves identically.
Store is swappable. SQLite for dev, Postgres for production. Implement the Store interface.
~/.config/agentctl/config.yaml
AGENTCTL_SERVER Registry URL (default http://localhost:8080)
ANTHROPIC_API_KEY For init with Anthropic
OPENAI_API_KEY For init with OpenAI