The Open Framework for Building Agents
docs: explain self-hosted integration registries (#1324)
Casey Gowrie406d4773f3ba
diff --git a/docs/install-integrations.mdx b/docs/install-integrations.mdxindex dfb9467bb..496da529a 100644--- a/docs/install-integrations.mdx+++ b/docs/install-integrations.mdx@@ -44,7 +44,7 @@ eve registry view extension/agent-browser## Add a third-party source-Give a registry a namespace and an integration URL template:+Use the integration URL template provided by the registry publisher and give the source a namespace:```basheve registry add @acme=https://registry.acme.com/r/{name}.json@@ -71,6 +71,75 @@ Install a known integration URL directly when you do not need a namespace:eve add https://registry.acme.com/r/analytics.json```+## Host your own registry++Hosting your own registry is the publishing side of the [third-party source workflow](#add-a-third-party-source). Once it is deployed, other eve projects can give it a namespace and pull integrations from it.++An eve registry is a standard [shadcn registry](https://ui.shadcn.com/docs/registry), so it can be hosted by any service that serves JSON over HTTP. It needs two kinds of endpoint:++- A catalog such as `https://registry.acme.com/r/registry.json` for `eve registry list` and `eve registry search`+- One JSON document per integration, such as `https://registry.acme.com/r/analytics.json`, for `eve registry view` and `eve add`++Start with a source file for the integration and a `registry.json` that describes where to install it:++```text+registry.json+registry/+└── analytics.ts+```++```json title="registry.json"+{+ "$schema": "https://ui.shadcn.com/schema/registry.json",+ "name": "acme",+ "homepage": "https://registry.acme.com",+ "items": [+ {+ "name": "analytics",+ "type": "registry:item",+ "title": "Acme Analytics",+ "description": "Add Acme analytics tools to an eve agent.",+ "dependencies": ["@acme/eve-analytics"],+ "envVars": {+ "ACME_API_KEY": ""+ },+ "files": [+ {+ "path": "registry/analytics.ts",+ "type": "registry:file",+ "target": "agent/extensions/analytics.ts"+ }+ ]+ }+ ]+}+```++`files[].path` is relative to `registry.json`. `files[].target` is relative to the root of the eve project that installs the item. Use `registry:item` with explicit `registry:file` targets for eve integrations so installation does not depend on a UI framework or shadcn project aliases.++Validate the source registry, then build its static JSON:++```bash+pnpm dlx shadcn@latest registry validate+pnpm dlx shadcn@latest build+```++By default, the build writes the catalog to `public/r/registry.json` and each item to `public/r/<name>.json`. Deploy the `public` directory to a static host, or use the shadcn registry APIs to serve the same payloads from dynamic routes.++Before sharing the registry, test its deployed catalog and item endpoints from an eve project:++```bash+eve registry list --registry https://registry.acme.com/r/registry.json+eve registry view https://registry.acme.com/r/analytics.json+```++Share the item URL template with consumers. From another eve project, they can add the hosted registry as a third-party source and pull the integration through its namespace:++```bash+eve registry add @acme=https://registry.acme.com/r/{name}.json+eve add @acme/analytics+```+## Configure generated filesIntegrations add project files. Read the generated mount before you run the agent, then add the configuration the extension requires.