> ## Documentation Index
> Fetch the complete documentation index at: https://docs.norafleet.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent hub

# Publish and install Agent Hub templates

> Convert an existing agent into a reusable Agent Hub listing, optionally share it to the community catalog, and install listings into any workspace with one click.

Agent Hub turns a working agent into a reusable template. This guide covers the end-to-end flow: install a listing, publish your own, share to the community catalog, and roll out a new version.

## What Agent Hub does

Agent Hub is the catalog of ready-to-run agent templates inside Nora. Instead of configuring an agent from scratch — runtime, image, environment, files, and integrations — you install a **listing** that captures all of it, and Nora materializes a working agent in one click.

But the templates are only half the point. **Agent Hub is a shareable hub, not just a static template store.** Once an operator gets an agent working, they can publish it as a listing and share it — and that sharing works at three different reach levels:

* **Reuse it yourself** — publish privately so anyone in your own workspace(s) can install the same agent with one click.
* **Share with the community** — push the listing to the public upstream hub (`https://norafleet.ai`), where, once approved, it appears in every Nora instance's **Community** filter.
* **Run your own company hub** — self-hosters can point `NORA_AGENT_HUB_URL` at their **own** Agent Hub instead of the public one. Then "community" sharing stays entirely inside the company: every operator publishes to and installs from a private, org-internal catalog — the same reusable, shareable workflow, without anything leaving your infrastructure.

This is the core value: an agent that one person builds becomes a one-click install for their teammates, their company, or the whole community — their choice.

A listing bundles everything an agent needs to run:

* **Runtime configuration** — runtime family (OpenClaw or Hermes), deploy target (Docker and Kubernetes GA; Proxmox LXC experimental), sandbox profile, and the default container image.
* **Workspace files** — the markdown that defines the agent's behavior: identity, operating rules, scheduled tasks, and any bootstrap script that runs on first message.
* **Integration wiring** — which providers the agent expects, so you know what to connect after install.

Listings come from three sources, shown as filters in the catalog:

* **Built-in** — platform-seeded templates that ship with Nora (for example, the Echo personal-branding agent).
* **Internal** — listings your workspace has published for its own reuse.
* **Community** — listings synced from the upstream hub and approved for everyone.

Credentials are never part of a listing. When a template needs provider access, you connect that provider from the installed agent's **Integrations** tab (and a communication channel from its **Channels** tab) so Nora stores the secrets outside the template files.

See [Agent Hub concepts](/concepts/agent-hub) for the underlying model — listing types, share targets, and versions.

## Example: install and set up Echo

The fastest way to see the full flow is to install a built-in template and configure it end to end.

<Card title="Set up Echo, the personal-branding agent" href="/guides/echo-personal-branding" icon="feather" arrow>
  A worked example: install the Echo listing, connect X and/or LinkedIn in the Integrations tab,
  connect a channel (WhatsApp) in the Channels tab, and run the bootstrap that learns your voice.
</Card>

## Install a listing

<img src="https://mintcdn.com/sttechnologyllc/hES1KHpUWDvLb_Wr/images/operator/agent-hub-list.png?fit=max&auto=format&n=hES1KHpUWDvLb_Wr&q=85&s=e853d9b136e84c33144a4c9b96a83ec9" alt="Agent Hub catalog — internal, community, and built-in filters" width="1512" height="1080" data-path="images/operator/agent-hub-list.png" />

<Steps>
  <Step title="Open Agent Hub">
    From the dashboard, open **Agent Hub** in the workspace navigation. The catalog shows three filters: **Internal** (your workspace's listings), **Community** (synced from the upstream hub), and **Built-in** (platform-seeded templates). Every card carries a runtime-family badge (**OpenClaw** or **Hermes**), and a family filter row appears whenever the catalog contains both families.
  </Step>

  <Step title="Select a listing">
    Click any listing to open its detail page. You'll see the runtime family, deploy target, sandbox
    profile, default image, and any bootstrap files or integrations the template wires up. OpenClaw
    listings show their core markdown set; Hermes listings show the captured workspace files instead.
  </Step>

  <Step title="Click Install">
    Choose the workspace (defaults to the current one) and an agent name. The deploy target and sandbox pickers only offer targets enabled for the listing's runtime family. Nora materializes the latest version of the listing into a new agent in `queued` status. The deployment job runs the same path as a manual deploy.

    For a Hermes listing, the deploy worker writes the bundle into the new runtime after it is created: workspace files under `/opt/data/workspace`, bundled skill directories under `/opt/data/skills`, guarded by a `/opt/data/.nora/template-applied` marker so redeploys with surviving storage never overwrite files the agent has edited. The bundle's saved skills are reinstalled by the skills reconciler on boot, and its captured model selection (provider, model, base URL — never API keys) becomes the new agent's model config.

    <img src="https://mintcdn.com/sttechnologyllc/hES1KHpUWDvLb_Wr/images/guides/agent-hub/install-dialog.png?fit=max&auto=format&n=hES1KHpUWDvLb_Wr&q=85&s=5d695e151789697c42747c750918403d" alt="Install dialog — workspace + agent-name confirmation before materializing the listing" width="1512" height="1080" data-path="images/guides/agent-hub/install-dialog.png" />

    <Note>
      Any signed-in user can install a listing today; workspace-scoped install roles are on the
      roadmap. See [Permissions](#permissions).
    </Note>
  </Step>
</Steps>

## Publish a workspace listing

<Steps>
  <Step title="Pick a working agent">
    Open the agent detail page for the agent you want to template. Make sure it's healthy — the listing snapshot reflects the agent's current image, env, files, and integrations.
  </Step>

  <Step title="Click Publish to Agent Hub">
    <img src="https://mintcdn.com/sttechnologyllc/A_pk5LchBKKfnyIr/images/guides/agent-hub/publish-dialog.png?fit=max&auto=format&n=A_pk5LchBKKfnyIr&q=85&s=65e7925cbf7f13ee1e7c53aec77ea300" alt="Publish dialog — listing name, description, category, and share target" width="1512" height="1080" data-path="images/guides/agent-hub/publish-dialog.png" />

    The publish dialog asks for:

    * **Name** — display name for the listing.
    * **Description** — short description shown in the catalog.
    * **Category** — free-form label used for filtering.
    * **Share target** — `internal` (your workspace only), `community` (push to the upstream hub), or `both`.
  </Step>

  <Step title="Confirm">
    Nora captures a snapshot of the agent and creates the listing. If you chose `community` or `both`, the listing is also queued for upstream review; its status shows as **Pending review** until the upstream hub approves it.

    <Tip>
      Use `internal` first to verify the listing installs cleanly in another workspace before sharing it publicly.
    </Tip>
  </Step>
</Steps>

## Roll out a new version

When the source agent's image, env, or files change, you can capture a new version on top of the existing listing instead of publishing a fresh one.

1. Open the listing detail page.
2. Click **Capture new version**.
3. Choose `files_only` (recommended) or `image_and_files`.
4. Confirm.

Existing installs keep running their previous version. Any future install picks up the latest version automatically.

## Share to the community catalog

Workspace listings published with share target `community` or `both` sync to the upstream Agent Hub at `NORA_AGENT_HUB_URL` (default `https://norafleet.ai`). The flow:

1. Listing is created locally with `centralShareStatus = pending`.
2. Nora pushes the listing payload to the upstream hub using the workspace's source-catalog API key.
3. Upstream reviewers approve, request changes, or reject. The result is mirrored to `centralShareStatus`.
4. Approved listings appear in every workspace's **Community** filter.

If sharing fails (network error, missing key, validation rejection), the listing's `centralError` shows the cause and the listing stays in `pending`. Click **Retry sync** from the listing detail page to push again.

## Manage source-catalog keys

<img src="https://mintcdn.com/sttechnologyllc/A_pk5LchBKKfnyIr/images/admin/agent-hub.png?fit=max&auto=format&n=A_pk5LchBKKfnyIr&q=85&s=3e80c95153afdce6cae500a3c8b2983c" alt="Admin Agent Hub moderation — review queue and listing detail" width="1512" height="1080" data-path="images/admin/agent-hub.png" />

The Agent Hub source-catalog API key authenticates Nora to the upstream hub. Manage keys under **Admin Settings → Agent Hub**.

* Keys are stored hashed using `NORA_AGENT_HUB_API_KEY_HASH_SECRET`. Rotating the secret invalidates every issued key.
* Each key has a label, status (`active` / `revoked`), and a 6-character prefix shown in the UI.
* Self-hosters can either use the upstream community hub or run their own and point `NORA_AGENT_HUB_URL` at it.

## Permissions

Agent Hub authorization is platform-level today, not workspace-role-based:

| Capability                       | Who can do it                               |
| -------------------------------- | ------------------------------------------- |
| Browse listings                  | Any signed-in user                          |
| Install a listing                | Any signed-in user (subject to plan limits) |
| Publish, edit, unpublish listing | The owner of the source agent               |
| Moderation and hub settings      | Platform admin                              |

<Note>
  Workspace-scoped RBAC for Agent Hub actions is on the roadmap; until it lands the roles above are
  the actual enforcement.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Install fails immediately">
    Check the agent detail page for the new agent — the deploy job's `failedReason` shows up there. Common causes: the destination workspace lacks the runtime family, deploy target, or sandbox profile the listing requires.
  </Accordion>

  <Accordion title="Community sync stays in pending">
    Open the listing detail page and check `centralError`. If it mentions auth, regenerate the
    source-catalog API key. If it mentions validation, the upstream hub rejected the payload — usually
    for a missing description or an unsupported runtime ID.
  </Accordion>

  <Accordion title="Reports aren't visible to me">
    Reports are reviewed in the upstream hub. The publishing workspace sees the report's resolution mirrored back; reporters see their own report status under **Settings → My reports**.
  </Accordion>
</AccordionGroup>