Marketplace architecture
A hosted Marketplace is a web service that a team runs so its members can search for and install agent resources from one place. It reads approved Git registries, checks and stores their content, and answers the search and install requests that agent-marketplace sends. You never need to run one to use a Marketplace; this page explains what sits behind the URL you install from.
The pieces
A deployment has a few parts, each with one job:
- The worker clones each approved registry, reads the resources in it, runs the security analyzers and license and size policy, and stores the results. In
databasemanagement mode it also runs discovery previews that the admin panel requests. - The API answers HTTP requests: the well-known identity document, search, resource and revision metadata, assessments, inspection content, artifacts, health, and the optional admin routes.
- The Nuxt UI serves the Marketplace at the deployment root, including the admin panel.
- An optional documentation-only VitePress image serves these docs below
/docs/. - A reverse proxy terminates TLS and routes API paths, enabled local documentation, and the remaining UI paths to their owning services.
The public project website is a separate deployment profile. It does not run a Marketplace API, worker, or UI.
| Profile | Root route | Documentation |
|---|---|---|
| Public project website | https://agent-marketplace.io/ serves the landing page | https://agent-marketplace.io/docs/ |
| Self-hosted Marketplace (default) | The deployment origin serves the Nuxt UI, for example https://marketplace.example.com/ | Links to https://agent-marketplace.io/docs |
| Self-hosted Marketplace with local docs | The same Nuxt UI | The same origin below /docs/ |
Local documentation is disabled by default. Enable Helm docs.enabled: true or append the supplied compose.docs.yaml override to either Compose deployment to host documentation without public-site access. These options also set the web runtime boolean NUXT_PUBLIC_DOCS_ENABLED, keeping all documentation links consistent. Local docs stay at origin-root /docs/ even when the UI has a non-root base path. The setting does not disable other product networking; required images must already be available.
The worker and the API are the same agent-marketplace serve program. The --role flag runs one of them or both in one process.
From registry to your harness
- The operator lists the approved registries. With
management.mode: filethey are in the operator configuration file; withdatabasemode an administrator manages them in the admin panel. - The worker clones each registry at its configured ref, on a schedule (every 30 minutes by default) or when an operator runs
serve reindex. - The worker reads the resources, runs the analyzers and policy checks, computes a content digest for each resource, and records the result as an assessment. In
mirrormode it also stores an artifact, a compressed archive of the resource, under its digest. - The API publishes the catalog. Each revision is identified by its content digest, and its content stays unchanged after publication. A repaired archive can update the served archive digest without changing that identity; the previous artifact remains downloadable.
- You run
agent-marketplace searchandinstall. The CLI verifies the revision, records its exact digest so later syncs install the same content, and writes the files into your harness folders.
Storage
The server keeps two kinds of data:
- Metadata, such as registries, revisions, assessments, and revocations, lives in SQLite or PostgreSQL.
- Blobs, meaning artifacts, manifests, and inspection files, live on a filesystem or in S3. Each blob is stored under its SHA-256 digest.
Back up metadata and blobs together. If you restore one without the other, the metadata can point to blobs that do not exist, or history can be incomplete.
Operations listener
The server opens a second, private listener for /readyz (is the server ready to serve?) and /metrics (Prometheus data). Do not publish it through the reverse proxy. The public listener answers 404 for both paths.
Authentication
The public catalog routes are anonymous: the server does not identify or authorize whoever calls them. If only certain people may browse or install, the reverse proxy must enforce that.
The admin routes are different. When the operator turns them on, they authenticate every request, either through native OIDC sign-in with a signed session cookie or through identity headers set by a trusted reverse proxy. Access requires a configured admin group or user.