Installing from Community Registry — Discover and Install Published Plugins
Install plugins published by other community members or your organization’s Gitea-hosted registry using sb plugin from-registry. The command queries the backend discovery API, validates version compatibility, downloads the TTL file, and installs it into your local plugins directory.
| Topic | Summary |
|---|---|
| What it does | Downloads a published plugin from a Gitea-hosted registry and installs it locally |
| How it works | Queries backend discovery API → checks runtime compatibility → downloads TTL → writes to ~/.schemabound/plugins/ |
| Where it installs | ~/.schemabound/plugins/<plugin-name>.ttl (user directory, no root required) |
Install Command
# Install the latest version from registry
sb plugin from-registry quantum-benchmarking
# Install a specific version
sb plugin from-registry quantum-benchmarking --version 0.1.0
Flags
| Flag | Required | Description |
|---|---|---|
name | Yes (positional) | Plugin slug as published to the registry |
--version | No | Specific version tag; defaults to latest |
--registry-url | No | Backend API URL for discovery queries; default: http://localhost:8080 (or set SCHEMABOUND_BACKEND_URL) |
Version Compatibility Check
Before downloading, the CLI checks whether the plugin’s declared compatible runtime version matches your current SCHEMABOUND installation. This prevents installing schema extensions that target incompatible API versions.
The compatibility constraint is defined by the plugin author at publish time (e.g., >=0.3.0). If it doesn’t match your runtime, you’ll see a warning but installation still proceeds — use this flag to override:
sb plugin from-registry --name quantum-benchmarking \
--compatible-runtime-version ">=0.5.0"
Full Lifecycle Example
1. Discover available plugins
Check the registry for what’s published (requires a running backend with catalog data):
# Query via curl against the backend discovery API
curl http://localhost:8080/api/plugins | jq '.plugins[].name'
# → quantum-circuit-cutting
# → quantum-state-simulation
# → ...
The backend serves this catalog from its internal triplestore, populated by webhook events when authors publish new releases.
2. Install a quantum circuit-cutting plugin (#094)
Install the distributed QPU coordination schema:
sb plugin from-registry quantum-circuit-cutting
# → Plugin 'quantum-circuit-cutting' (v0.1.0) installed from registry. Location: ~/.schemabound/plugins/quantum-circuit-cutting.ttl
The CLI queries the backend discovery API for the download URL, checks version compatibility against your runtime, downloads the TTL asset from Gitea, and writes it to ~/.schemabound/plugins/. The plugin loads automatically on next backend restart.
3. Verify installation
sb plugin list
# → quantum-circuit-cutting (2.4 KB)
The installed .ttl file is now in ~/.schemabound/plugins/quantum-circuit-cutting.ttl. When OAM starts, it discovers this file and merges the wire cut indices + subcircuit count schema into the runtime registry.
4. Uninstall a plugin
When you no longer need a quantum plugin:
sb plugin uninstall --name quantum-circuit-cutting
# → Plugin 'quantum-circuit-cutting' uninstalled.
If the plugins directory is empty after removal, it will be cleaned up automatically.
5. Install state vector simulation schema (#095) — alternative workflow
Install a different quantum plugin from a specific version:
sb plugin from-registry quantum-state-simulation --version 0.2.0
# → Plugin 'quantum-state-simulation' (v0.2.0) installed from registry. Location: ~/.schemabound/plugins/quantum-state-simulation.ttl
This installs a specific version for reproducibility — useful when testing against known-good schema extensions before upgrading to the latest release.
Using Installed Plugins
Once installed and loaded by OAM, agents can interact with the new schema as if it were part of the base ontology:
- New RDF classes appear in schema introspection results
- New properties are queryable through standard tools
- Mutable properties (marked
qg:mutable true) allow writes; static ones remain read-only per OAM’s mutability model
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Plugin not found in registry | Name typo or unpublished | Verify name with catalog query; ask author to publish |
| Compatibility warning on install | Runtime version outside plugin’s constraint range | Override with --compatible-runtime-version; rebuild runtime if needed |
| Backend reports validation error after install | TTL file violates schema boundaries (overrides base class) | Edit the .ttl file; do not override existing classes |