# Host a pack registry

At the end of this guide your own library packs (agents, skills, commands and connections) are listed in the **Library** of any workspace that connects your registry, and its admins install them like the packs that ship with Volobox. The registry is a set of static files on an HTTPS origin you control. Connecting it, and installing from it, needs the organization settings permission for AI (`Volobox.GlobalSettings.Ai`) together with **Admin console (menu link)**, like every **Organization Settings** tab.

## Before you begin

- The organization settings permission for AI and **Admin console (menu link)** in the workspace that will connect the registry.
- An HTTPS origin where you can publish static files.
- The skills, agents and commands the pack holds. To publish them from a workspace, the skills and commands must be workspace-wide and the agents shared; personal and system items are refused.

## Package the pack

The quickest way to get a valid zip is to publish the pack in a workspace and download it.

1. In **Organization Settings** > **AI** > **Library**, choose **Publish a pack**.
2. Give it a name, a short name (used in the pack's address, and never changed afterwards) and a version.
3. Tick the skills, agents, commands and connections to include, and choose **Check what's included** to see the item list, what an installing admin will have to supply, and any warnings.
4. Choose **Publish a pack**.
5. On the pack under **Packs from this workspace**, choose **Download**. You get a `.zip` holding `pack.json` and every included skill's files.
6. Give the pack a key in your own namespace. A pack published from a workspace has the key `workspace/<short name>`, and a registry may not serve `workspace/` or `volobox/` keys. Open `pack.json`, change `key` to your own, such as `acme/release-pack`, and zip the files again with `pack.json` at the top.

> **Note:** Change the key before you compute the zip's SHA-256 and size, and recompute both whenever you change the zip. The zip's `pack.json` `key` and `version` must match the pack's entry in `index.json`.

You can also write the zip by hand: `pack.json` at the top, and each skill's folder at the path its item names.

```text
release-pack.zip
  pack.json
  skills/
    release-checklist/
      SKILL.md
      references/
        checklist.md
```

```json
{
  "key": "acme/release-pack",
  "version": "1.0.0",
  "name": { "en": "Release pack" },
  "description": { "en": "A release agent with a checklist skill." },
  "category": "roles",
  "items": [
    { "id": "skill-release-checklist", "type": "skill", "path": "skills/release-checklist" },
    {
      "id": "agent-release",
      "type": "agent",
      "spec": {
        "handle": "release",
        "displayName": "Release",
        "autoIncludeSystemSkills": true,
        "charterInstructions": "You prepare releases with the release checklist. Never merge pull requests.",
        "skillRefs": ["skill-release-checklist"]
      }
    }
  ]
}
```

Every field and item type is in [Skills and packs](/docs/skill-and-pack-formats#packjson).

> **Warning: Never put a token in a pack**
>
> A connection item carries its address, transport and auth mode only. Declare the token under `requires.inputs` with `kind: "secret"`; the installing admin picks it from their own secret scope.

## Publish the registry

1. Choose a base URL, such as `https://packs.example.com/`.
2. Put each pack's zip under that origin, at a path relative to the base URL, such as `packs/acme/release-pack/1.0.0.zip`.
3. Compute each zip's SHA-256 and its size in bytes (the commands are below this list).
4. Publish `index.json` at the base URL. For each pack it lists the pack's key, its version, the zip's relative path, SHA-256 and size, and the full `pack.json` manifest inlined, so the Library can list the pack without downloading the zip.
5. Serve everything over HTTPS. If the registry needs a key, accept it as `X-Api-Key` or `Authorization: Bearer`: Volobox sends both.

**bash**

```bash
sha256sum release-pack.zip
stat -c %s release-pack.zip
```

**PowerShell**

```powershell
(Get-FileHash release-pack.zip -Algorithm SHA256).Hash.ToLower()
(Get-Item release-pack.zip).Length
```

An `index.json` with one pack. `manifest` is the zip's `pack.json`, shortened here:

```json
{
  "schemaVersion": 1,
  "generatedAt": "2026-11-14T09:00:00Z",
  "packs": [
    {
      "key": "acme/release-pack",
      "version": "1.0.0",
      "bundle": {
        "path": "packs/acme/release-pack/1.0.0.zip",
        "sha256": "<64 lowercase hex characters>",
        "sizeBytes": 18432
      },
      "manifest": {
        "key": "acme/release-pack",
        "version": "1.0.0",
        "name": { "en": "Release pack" },
        "description": { "en": "A release agent with a checklist skill." },
        "category": "roles",
        "items": []
      }
    }
  ]
}
```

The fields are in [Skills and packs](/docs/skill-and-pack-formats#remote-pack-registry). `schemaVersion` must be `1`, or the whole index is refused. An entry is dropped, and the rest of the index still loads, when:

- its key starts with `volobox/` or `workspace/`;
- its bundle `path` is an absolute URL or contains `..`;
- its `sha256` is not 64 hexadecimal characters;
- its `sizeBytes` is missing, `0` or less, or over the per-pack limit;
- its `manifest.key` differs from its `key`.

After download, the zip's SHA-256 must match the index, and the zip's `pack.json` `key` and `version` must match the entry.

## Connect the registry

1. In the workspace that will use it, open **Organization Settings** > **AI** > **Library**.
2. Under **Remote pack registries**, choose **Add a registry**.
3. Give it a short name (it becomes `registry:{name}` in the catalog), a display name, and the HTTPS base URL.
4. Optionally paste the API key.
5. Choose a **trust level**:
   - **Untrusted** or **Trusted**: packs install as ordinary workspace content, and bundled scripts still ask for approval.
   - **Verified**: skills install as verified, the same privilege first-party packs have. Use it only for a registry you fully control.
6. Save. Volobox fetches `index.json` and lists the packs below.

**Test** checks the connection without replacing the cached list; **Refresh** fetches the index again.

![Organization Settings on the AI tab, Library: the Meridian Works packs registry with its index address, and pack cards such as Software Delivery Team, Release Manager (installed, one edited item) and Delivery Coach, each with its version, a Verified badge, its description, what it produces and example prompts.](https://volobox.io/docs/images/library-packs.light.webp)

*The Library in Organization Settings, AI: a connected remote pack registry with Test, Refresh and Edit, and the packs it lists, each with its version, badges and Install.*

## Install a pack from it

1. On the pack card, review the description, what it produces, the example prompts, and whether secrets are required. Choose **Install**.
2. Resolve conflicts with items you already have: **Use existing**, **Rename new** (adds a `-pack` suffix) or **Skip**.
3. Pick a **secret scope** and variable for each secret the pack requires.
4. Confirm. The pack becomes **Active**, or **Pending setup** when a required secret was skipped.

Installed items become ordinary, editable organization resources.

## Check that it works

- The registry's packs appear in the Library with a **Community registry** badge, and a **Verified** badge when the registry's trust level is **Verified**.
- After install, the pack card shows **Remove**, and its agents, skills and commands appear in the workspace's lists. Agents from packs start with **Autonomous** off.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| A pack is missing from the catalog | Its key starts with `volobox/` or `workspace/`, its bundle path leaves the origin, it has no `sizeBytes`, or the entry is otherwise malformed. Fix the index and choose **Refresh** |
| Install fails after download | The zip's SHA-256 does not match the index. Recompute it and publish the index again |
| The bundle does not match the index | The zip's `pack.json` has a different `key` or `version` than its index entry, often a `workspace/` key left from a downloaded pack. Fix `pack.json`, zip it again, recompute the SHA-256 and size, and publish the index again |
| The registry is offline | The Library keeps showing the last index it fetched; installs of bundles already cached still work, others fail until you **Refresh** |
| The registry cannot be deleted | Packs from it are still installed. Remove those installations first, or disable the registry to hide its packs |
| The pack stays **Pending setup** | A required secret was skipped. Choose **Continue setup** and pick the secret |

## Next steps

- [Skills and packs](/docs/skill-and-pack-formats)
- [Create a skill](/docs/create-a-skill)
- [Agents](/docs/agents)
- [Integrations](/docs/integrations)
