agentry

module
v0.7.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: MIT

README

Agentry

The Agentry registry server: a registry and git host for single-purpose AI agents, with a mandatory pre-publication security pipeline and signed provenance.

This repository is the open core. It holds agentryd (the server, in api, git and worker roles), the ten-stage security pipeline, the account and authorization system, the git host, the server's own pages at /ui/, and a headless deployment (Docker Compose and a Helm chart). It runs on its own. The Go module path, the agentryd and agentry binaries and the AGENTRY_ environment prefix keep the agentry name.

Every published version is scanned on the exact bytes that will ship, and nothing becomes installable until the gate decides. A scanner that errors or times out, or content it could not read, fails toward review — never through. Static analysis cannot prove an agent safe, and the product never claims it does. See the trust model for what the pipeline checks, what a signature proves and what none of it guarantees.

Prerequisites

  • Go at the version on the go line of go.mod (an older go fetches that toolchain itself). There is no JavaScript build: the server's pages are Go templates.
  • Docker with Compose, or PostgreSQL 18 locally (scripts/dev/pg.sh runs a private cluster).
  • sqlc for query code generation (make generate).
  • golangci-lint for make lint (the target skips it when it is absent).

Build, test and lint

make build      # compile ./... and write bin/agentryd
make test       # all Go tests; database tests read AGENTRY_TEST_DATABASE_URL
make lint       # gofmt, go vet, golangci-lint
make generate   # regenerate the OpenAPI server, the Go client and sqlc output
make check      # the CI gate: generated-code drift, ruleset sync, compose image pins, third-party notices, lint, tests, build
make workflows-check  # no fork-reachable workflow job on a self-hosted runner (python3 with PyYAML)

./scripts/dev/pg.sh test-url prints a database URL for the tests. The acceptance scripts in scripts/acceptance/ drive a booted server end to end (make e2e runs smoke.sh). The API is spec-first: edit schemas/openapi.yaml, run make generate, then implement the new method on internal/api.Server. Developing Agentry has the details.

Run it locally

make db-up      # local Postgres 18 on :5477
make dev        # migrations, then agentryd (all roles) on :8080
curl localhost:8080/api/v1/meta

People sign in through an OpenID provider you configure (auth.oidc); the server keeps no passwords. http://localhost:8080/ui/ hands sign-in to that provider, and /ui/authorize is the page the CLI and the desktop app open. Configuration is agentry.yaml (copy agentry.yaml.example) with AGENTRY_* environment overrides; the environment wins. deploy/compose runs the whole registry with no site in front: Postgres, object storage, mail, agentryd and an nginx edge. For a real deployment, see self-hosting.

Layout

Path What
cmd/agentryd the server: agentryd api|git|worker|all
internal/scan the security pipeline: orchestrator, stages S1–S10, gate, judge, signing
internal/registry agents, versions, the publication state machine, deterministic archives
internal/gitsrv git smart-HTTP, repository storage, policy hooks
internal/api internal/auth internal/store HTTP layer, identity and authorization, Postgres
internal/render the only path by which author markdown reaches a browser
internal/ui the server's own pages at /ui/ (Go templates): device authorize, the sign-in hand-off, sign-out, address confirmation
pkg/extension the seam an outside Go module extends the server through: routes, migrations, entitlements, hooks, jobs
pkg/judge pkg/websearch the AI Review client and its question sets, and the web search clients
pkg/ the public surface the CLI and third parties build on: manifest spec and refs, rules engine, embedded ruleset, deterministic archives and extractor, attestation verification, the generated API client
rules/ the versioned S3/S4 rule bundle
testdata/attack-corpus/ the golden corpus: attack fixtures and their benign twins
examples/ small example QuickAgent packages that publish through the pipeline
deploy/ the headless Compose stack and the Helm chart
schemas/ the OpenAPI spec and the code generator configuration
tools/oapi-codegen the OpenAPI generator's own Go module, so its dependencies stay out of the server's go.mod
docs/ the pages published at docs.secureagentry.net

The CLI is agentry-cli; it depends on this module's pkg/.

Documentation

Contributing

Contributions are welcome under the Developer Certificate of Origin (every commit is signed off) and no CLA. See CONTRIBUTING.md.

Security

Report vulnerabilities as described in SECURITY.md, never in a public issue.

License

MIT (see LICENSE).

Directories

Path Synopsis
cmd
agentryd command
agentryd is the Agentry server binary: a modular monolith whose role is chosen on the command line (api | git | worker | all).
agentryd is the Agentry server binary: a modular monolith whose role is chosen on the command line (api | git | worker | all).
Package agentrydeps pins dependencies that code about to land imports, so go.mod does not change concurrently.
Package agentrydeps pins dependencies that code about to land imports, so go.mod does not change concurrently.
api
Package api provides primitives to interact with the openapi HTTP API.
Package api provides primitives to interact with the openapi HTTP API.
audit
Package audit provides the append-only audit log: a code-registered action catalog (so docs and events cannot drift) and a writer that lands every event in the partitioned audit_events table.
Package audit provides the append-only audit log: a code-registered action catalog (so docs and events cannot drift) and a writer that lands every event in the partitioned audit_events table.
auth
Package auth implements authentication and authorization primitives: PAT and session token handling, PAT scopes, sealing of small secrets, and the single authorization chokepoint.
Package auth implements authentication and authorization primitives: PAT and session token handling, PAT scopes, sealing of small secrets, and the single authorization chokepoint.
auth/oidc
Package oidc implements the OpenID Connect Relying Party side of sign-in through an OpenID provider: authorization-code flow with PKCE, issuer pinning (the discovery document's issuer must match the configured issuer), and email_verified respected.
Package oidc implements the OpenID Connect Relying Party side of sign-in through an OpenID provider: authorization-code flow with PKCE, issuer pinning (the discovery document's issuer must match the configured issuer), and email_verified respected.
auth/social
Package social implements sign-in for individual accounts through the deployment's OpenID provider (linked via identities; no password), on the relying party in internal/auth/oidc.
Package social implements sign-in for individual accounts through the deployment's OpenID provider (linked via identities; no password), on the relying party in internal/auth/oidc.
config
Package config loads agentryd configuration from agentry.yaml plus AGENTRY_* environment overrides.
Package config loads agentryd configuration from agentry.yaml plus AGENTRY_* environment overrides.
dnsx
Package dnsx abstracts DNS TXT lookups behind an interface so domain verification is testable with an injected fake resolver.
Package dnsx abstracts DNS TXT lookups behind an interface so domain verification is testable with an injected fake resolver.
entitlements
Package entitlements is the product seam: the one place that answers "how much of this may this subject have?" and "is this feature on?".
Package entitlements is the product seam: the one place that answers "how much of this may this subject have?" and "is this feature on?".
gitsrv
Package gitsrv implements git hosting: bare-repo storage keyed by repo UUID, smart HTTP v2 by shelling out to git, and the pre-receive policy hook.
Package gitsrv implements git hosting: bare-repo storage keyed by repo UUID, smart HTTP v2 by shelling out to git, and the pre-receive policy hook.
httpmux
Package httpmux names the one thing a package that registers HTTP routes and a package that serves them must agree on: what a mux is.
Package httpmux names the one thing a package that registers HTTP routes and a package that serves them must agree on: what a mux is.
knowledge
Package knowledge is the registry's store of knowledge packs: the packs a signed-in person, or an organization, keeps in Agentry, each held as its tree sealed under a data key of its own (pkg/packseal) with that key wrapped for its owner by a KeyWrapper, scanned when it arrives, and destroyed with its owner.
Package knowledge is the registry's store of knowledge packs: the packs a signed-in person, or an organization, keeps in Agentry, each held as its tree sealed under a data key of its own (pkg/packseal) with that key wrapped for its owner by a KeyWrapper, scanned when it arrives, and destroyed with its owner.
logevent
Package logevent is the vocabulary of the log contract (docs/logging.md): the `event` names a line carries when it is a signal rather than narration.
Package logevent is the vocabulary of the log contract (docs/logging.md): the `event` names a line carries when it is a signal rather than narration.
logx
Package logx is the mechanism behind the log contract (docs/logging.md): the request id carried in a context, the handler that stamps it on every line written under that context, and the sanitiser that keeps tokens and secrets out of a line and keeps a line below the size at which Docker splits it.
Package logx is the mechanism behind the log contract (docs/logging.md): the request id carried in a context, the handler that stamps it on every line written under that context, and the sanitiser that keeps tokens and secrets out of a line and keeps a line below the size at which Docker splits it.
maildomains
Package maildomains answers one question: is this mail domain one that no single organization owns? An organization is keyed on the domain of its creator's verified address, and a person at gmail.com must not be able to claim gmail.com for their organization — nor be told that "gmail.com is registered to Acme" — so an address at a shared domain records no domain at all.
Package maildomains answers one question: is this mail domain one that no single organization owns? An organization is keyed on the domain of its creator's verified address, and a person at gmail.com must not be able to claim gmail.com for their organization — nor be told that "gmail.com is registered to Acme" — so an address at a shared domain records no domain at all.
manifestcaps
Package manifestcaps decodes the capabilities block of a canonical manifest's JSON the one way every reader of it in the registry does: the scanner's stages, the gate's inputs, and the derivations pkg/gatecases publishes for clients that restate the gate.
Package manifestcaps decodes the capabilities block of a canonical manifest's JSON the one way every reader of it in the registry does: the scanner's stages, the gate's inputs, and the derivations pkg/gatecases publishes for clients that restate the gate.
metrics
Package metrics is the telemetry seam: one instrument set, two ways out of the process.
Package metrics is the telemetry seam: one instrument set, two ways out of the process.
notify
Package notify sends user-facing notifications (email in v1).
Package notify sends user-facing notifications (email in v1).
queue
Package queue is the async job abstraction.
Package queue is the async job abstraction.
ratelimit
Package ratelimit is the shared in-memory token-bucket store behind the quotas: the API rate classes, the per-org webhook delivery rate, and the per-repo git push budget.
Package ratelimit is the shared in-memory token-bucket store behind the quotas: the API rate classes, the per-org webhook delivery rate, and the per-repo git push budget.
redteam
Package redteam attacks the registry's own S3/S4 gate: it takes the golden attack corpus, rewrites each attack fixture with the paraphrase and obfuscation tricks red-team harnesses use (garak/PyRIT- style, without a model in the loop so a run is reproducible), scans the rewrites with the same rule bundle `agentry validate` and the pipeline use, and reports which rewrites the expected rule no longer catches.
Package redteam attacks the registry's own S3/S4 gate: it takes the golden attack corpus, rewrites each attack fixture with the paraphrase and obfuscation tricks red-team harnesses use (garak/PyRIT- style, without a model in the loop so a run is reproducible), scans the rewrites with the same rule bundle `agentry validate` and the pipeline use, and reports which rewrites the expected rule no longer catches.
registry
Package registry owns the agent/version domain: agent creation, resolution, effective-permission computation, and the publication state machine.
Package registry owns the agent/version domain: agent creation, resolution, effective-permission computation, and the publication state machine.
render
Package render turns untrusted author markdown into safe HTML.
Package render turns untrusted author markdown into safe HTML.
scan
Package scan is the security pipeline: orchestrator, scanner stages S1–S10, the LLM judge interface, the gate, and provenance signing.
Package scan is the security pipeline: orchestrator, scanner stages S1–S10, the LLM judge interface, the gate, and provenance signing.
store
Package store owns PostgreSQL access: the pgx pool, goose migrations, and sqlc-generated typed queries.
Package store owns PostgreSQL access: the pgx pool, goose migrations, and sqlc-generated typed queries.
testdb
Package testdb gives integration-test binaries fresh Postgres databases.
Package testdb gives integration-test binaries fresh Postgres databases.
testidp
Package testidp is a stand-in OpenID provider for tests: discovery, a signing key, an authorization endpoint and a token endpoint that hold a relying party to the parts of the protocol the registry depends on (the registered client, PKCE, single-use codes, the nonce), and sign real ID tokens for whoever a test says is signing in.
Package testidp is a stand-in OpenID provider for tests: discovery, a signing key, an authorization endpoint and a token endpoint that hold a relying party to the parts of the protocol the registry depends on (the registered client, PKCE, single-use codes, the nonce), and sign real ID tokens for whoever a test says is signing in.
ui
Package ui is the server's own browser surface, served by agentryd at /ui/: the device-authorize page the CLI and the desktop app open, and, without a site in front, the hand-off to the deployment's OpenID provider, sign-out and the page an activation link opens.
Package ui is the server's own browser surface, served by agentryd at /ui/: the device-authorize page the CLI and the desktop app open, and, without a site in front, the hand-off to the deployment's OpenID provider, sign-out and the page an activation link opens.
version
Package version carries build-time version identity for agentryd and the CLI.
Package version carries build-time version identity for agentryd and the CLI.
voice
Package voice is the registry's store of Writing Voices: the one VOICE.md a person keeps in Agentry, the instructions a run follows for how it writes and nothing else.
Package voice is the registry's store of Writing Voices: the one VOICE.md a person keeps in Agentry, the instructions a run follows for how it writes and nothing else.
webhook
Package webhook implements org-configurable webhooks: HMAC-SHA256 signed delivery through the async queue with 5× exponential backoff, and the SSRF egress guard (https-only, re-resolve to public unicast per attempt, block private/link-local/metadata ranges, no redirect following, 10s timeout).
Package webhook implements org-configurable webhooks: HMAC-SHA256 signed delivery through the async queue with 5× exponential backoff, and the SSRF egress guard (https-only, re-resolve to public unicast per attempt, block private/link-local/metadata ranges, no redirect following, 10s timeout).
pkg
apiclient
Package apiclient provides primitives to interact with the openapi HTTP API.
Package apiclient provides primitives to interact with the openapi HTTP API.
archive
Package archive is the public release-archive toolkit: the deterministic tar.zst builder that gives every release its content-addressed identity, the hardened extractor for untrusted archives, the trusted unpacker clients use on registry-built archives, and the content sniffers behind the S1 inventory and `agentry validate` parity.
Package archive is the public release-archive toolkit: the deterministic tar.zst builder that gives every release its content-addressed identity, the hardened extractor for untrusted archives, the trusted unpacker clients use on registry-built archives, and the content sniffers behind the S1 inventory and `agentry validate` parity.
attest
Package attest is the public attestation format for published versions: the in-toto v1 statement, the publish predicate, the DSSE envelope, and offline verification.
Package attest is the public attestation format for published versions: the in-toto v1 statement, the publish predicate, the DSSE envelope, and offline verification.
connector
Package connector is Agentry's catalogue of connectors: the vendors' MCP servers Agentry has vetted, each bound to the app Agentry registered with that vendor.
Package connector is Agentry's catalogue of connectors: the vendors' MCP servers Agentry has vetted, each bound to the app Agentry registered with that vendor.
draftcheck
Package draftcheck is AI Review's check of a finished draft: before a draft is handed back, AI Review reads its rendered package with the release rubric that stage S5 of the pipeline will ask at publish, so the person knows before Submit what AI Review will flag, and asks the draft question set (pkg/judge DraftQuestions) about whether the draft does the task it was drafted for.
Package draftcheck is AI Review's check of a finished draft: before a draft is handed back, AI Review reads its rendered package with the release rubric that stage S5 of the pipeline will ask at publish, so the person knows before Submit what AI Review will flag, and asks the draft question set (pkg/judge DraftQuestions) about whether the draft does the task it was drafted for.
draftproof
Package draftproof is the proof that a published version is the one a hosted draft wrote.
Package draftproof is the proof that a published version is the one a hosted draft wrote.
egressguard
Package egressguard is the core's SSRF egress guard: every fetch the registry makes to an address someone else chose (a webhook endpoint, an OIDC issuer, a README image, an MCP server's vendor) goes through it.
Package egressguard is the core's SSRF egress guard: every fetch the registry makes to an address someone else chose (a webhook endpoint, an OIDC issuer, a README image, an MCP server's vendor) goes through it.
extension
agentryd is the Agentry server binary: a modular monolith whose role is selected at start: `agentryd api|git|worker|all`.
agentryd is the Agentry server binary: a modular monolith whose role is selected at start: `agentryd api|git|worker|all`.
gatecases
Package gatecases publishes the registry gate's behaviour as data: a table of cases, each a set of findings, the flags the gate reads, a policy, and the outcome the gate reaches (published, needs_review, rejected).
Package gatecases publishes the registry gate's behaviour as data: a table of cases, each a set of findings, the flags the gate reads, a policy, and the outcome the gate reaches (published, needs_review, rejected).
handle
Package handle is the grammar of an Agentry handle, the name of a person or an organization: the first segment of every /<namespace>/<name> path, and the namespace of every QuickAgent.
Package handle is the grammar of an Agentry handle, the name of a person or an organization: the first segment of every /<namespace>/<name> path, and the namespace of every QuickAgent.
judge
Package judge is the one client for TypeSafe AI's Jev and the question sets it is asked.
Package judge is the one client for TypeSafe AI's Jev and the question sets it is asked.
manifest
Package manifest implements the agent.yaml package manifest: strict parsing (closed schema, rule V1), the validation rules V1–V18, the closed capability vocabulary, and the canonical JSON form stored as agent_versions.manifest.
Package manifest implements the agent.yaml package manifest: strict parsing (closed schema, rule V1), the validation rules V1–V18, the closed capability vocabulary, and the canonical JSON form stored as agent_versions.manifest.
packseal
Package packseal is the sealed form of a knowledge pack: the pack's tree, as one tar, encrypted under a random data key of its own, so that neither a laptop's store nor Agentry's holds a pack's pages in the clear.
Package packseal is the sealed form of a knowledge pack: the pack's tree, as one tar, encrypted under a random data key of its own, so that neither a laptop's store nor Agentry's holds a pack's pages in the clear.
reportdesign
Package reportdesign is the one definition of a report design: the theme document version 3 that sets the look of a person's PDF reports, a whole brand.
Package reportdesign is the one definition of a report design: the theme document version 3 that sets the look of a person's PDF reports, a whole brand.
rules
Package rules is the embedded scanner engine that powers both the server-side publication pipeline stages S3 and S4 and the offline `agentry validate` command.
Package rules is the embedded scanner engine that powers both the server-side publication pipeline stages S3 and S4 and the offline `agentry validate` command.
ruleset
Package ruleset embeds the versioned S3/S4 rule bundle (rules/) into the server binary so the pipeline ships a self-contained ruleset.
Package ruleset embeds the versioned S3/S4 rule bundle (rules/) into the server binary so the pipeline ships a self-contained ruleset.
toolgrant
Package toolgrant compares the runner tools a QuickAgent's instruction names with what its manifest grants.
Package toolgrant compares the runner tools a QuickAgent's instruction names with what its manifest grants.
websearch
Package websearch is web search behind one small interface.
Package websearch is web search behind one small interface.
scripts
dev/attest-fixture command
attest-fixture writes what a third-party verifier needs to check one of this registry's attestations: a blob, the DSSE envelope this code produces over the blob's digest — the exact bytes the server would store and serve — and the signing public key.
attest-fixture writes what a third-party verifier needs to check one of this registry's attestations: a blob, the DSSE envelope this code produces over the blob's digest — the exact bytes the server would store and serve — and the signing public key.
dev/dbexec command
Command dbexec runs SQL statements against the acceptance database, one per argument, for the acceptance scripts that need a fact the API never exposes — an address marked verified, since the verification token never leaves the server (docs/logging.md).
Command dbexec runs SQL statements against the acceptance database, one per argument, for the acceptance scripts that need a fact the API never exposes — an address marked verified, since the verification token never leaves the server (docs/logging.md).
dev/ruleset-digest command
Command ruleset-digest prints the semantic version and the digest of a rule bundle directory, computed by the loader the server records it with, so a ruleset_releases row can be checked against the bundle a ruleset/v<semver> tag holds (pkg/ruleset/README.md).
Command ruleset-digest prints the semantic version and the digest of a rule bundle directory, computed by the loader the server records it with, so a ruleset_releases row can be checked against the bundle a ruleset/v<semver> tag holds (pkg/ruleset/README.md).
notices command
Command notices writes THIRD_PARTY_NOTICES, the licence and notice texts of the Go modules compiled into agentryd, in a form that is the same on every machine: modules sorted by path, no timestamps, the linux/amd64 build the container image uses.
Command notices writes THIRD_PARTY_NOTICES, the licence and notice texts of the Go modules compiled into agentryd, in a form that is the same on every machine: modules sorted by path, no timestamps, the linux/amd64 build the container image uses.
seed command
Command seedgen writes the performance seed dataset: N published agents with realistic names, summaries, manifests, capabilities and install counts, straight into the database through the store.
Command seedgen writes the performance seed dataset: N published agents with realistic names, summaries, manifests, capabilities and install counts, straight into the database through the store.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL