Automation and apps

Guide

Host a pack registry

Package a library pack as a zip with pack.json, serve it from an HTTPS registry with an index.json, and connect the registry in another workspace.

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.

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.
sha256sum release-pack.zip
stat -c %s release-pack.zip

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. 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.

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

SymptomFix
A pack is missing from the catalogIts 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 downloadThe zip's SHA-256 does not match the index. Recompute it and publish the index again
The bundle does not match the indexThe 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 offlineThe Library keeps showing the last index it fetched; installs of bundles already cached still work, others fail until you Refresh
The registry cannot be deletedPacks from it are still installed. Remove those installations first, or disable the registry to hide its packs
The pack stays Pending setupA required secret was skipped. Choose Continue setup and pick the secret

Next steps