Skip to content

vox-plugin-host API Reference (generated)

Crate: vox-plugin-host · Version: 0.6.0 · Target: Library (lib.rs)

Vox host-side plugin discovery, loading, and registry.

Vox plugin host: discovery, loading, registry.

See: docs/src/architecture/plugin-system-redesign-2026.md Spec §4.2(d): a plugin whose manifest version disagrees with the running core’s own CARGO_PKG_VERSION must be refused before any attempt to resolve or dlopen its dylib.

DependencyKind
vox-plugin-apiNormal
vox-plugin-typesNormal
vox-secretsNormal
vox-telemetryNormal
vox-configDevelopment
ModuleDescription
capability—
discover—
errors—
external_skills—
host_impl—
loader—
registry—
skill_author—
skill_bundle—
skill_manifest—
skill_parser—
skill_registry—
telemetry—
user_install—
FunctionDescription
resolve_plugins_rootResolve the plugin install root, respecting $VOX_PLUGINS_DIR if set. Falls back to the platform’s local data directory under vox/plugins.
format_install_hintFormat the canonical multi-line install hint for a missing plugin. Always includes the catalog command (vox plugin install <id>). When the caller is running from a Vox workspace checkout that contains the plugin source under crates/vox-plugin-<id>/, also appends the local-path variant so contributors get a copy-pasteable command pointing at their own checkout (no GitHub fetch needed). Optionally appends a “Build with cargo:” line when the caller knows the plugin is enabled behind a cargo feature flag on a vox crate (e.g. vox-ml-cli’s gpu / mens-candle-cuda). Pass Some(cargo_hint) with the command body — cargo build -p vox-ml-cli --release --features ....
workspace_local_plugin_sourceDetect the in-tree source directory for a plugin id when running from a Vox workspace checkout. Used by load_code_plugin to make the “plugin not installed” error message actionable for contributors and by vox plugin install <id> (catalog path) to prefer the local checkout over fetching a release tarball. Walks up from CWD looking for a crates/vox-plugin-<id>/Plugin.toml. Returns Some(path-to-crate-dir) on the first hit, None otherwise. Honors VOX_WORKSPACE_ROOT as an explicit override.
current_target_triple_keyReturn the target-triple key used in [plugin.payload.artifacts] for the current build. The format is "<os>-<arch>" where os is "windows", "linux", or "macos" and arch is "x86_64" or "aarch64". This matches the keys emitted by the Plugin.toml generator and by vox plugin install.
load_code_plugin_by_idConvenience wrapper: discover the plugin install root, build the registry, and load a code plugin by id in a single call. For one-off dispatches from async contexts, wrap in tokio::task::spawn_blocking.
load_code_pluginDiscover the given plugin in registry, resolve the dylib path for the current target triple, and load it via [Loader]. This is the preferred one-shot entry point for code-payload plugins. Callers can then call .plugin.as_ml_backend() (or the relevant extension point accessor) on the returned [LoadedCodePlugin].
cached_code_pluginCached singleton: load a code plugin once and reuse the handle process-wide. First call: discover + dlopen (tens of ms). Subsequent calls: O(1) HashMap lookup. The plugin is leaked for the process lifetime (Box::leak) — code plugins are designed to never unload while the host is running. Designed for plugins called repeatedly (browser, mesh, ml backends).
Dependency Topology, diagram 116 nodes, 15 edges: vox-plugin-host → vox-config; vox-plugin-host → vox-plugin-api; vox-plugin-host → vox-plugin-types; vox-plugin-host → vox-secrets; vox-plugin-host → vox-telemetry; vox-actor-runtime → vox-plugin-host; vox-cli → vox-plugin-host; vox-cli-ci → vox-plugin-host; vox-cli-research → vo…vox-plugin-hostvox-configvox-plugin-apivox-plugin-typesvox-secretsvox-telemetryvox-actor-runtimevox-clivox-cli-civox-cli-researchvox-guivox-ml-clivox-openclaw-runtimevox-orchestrator-mcpvox-populivox-skills
Diagram source
graph {
direction: right
node vox_plugin_host: "vox-plugin-host"
node vox_config: "vox-config"
vox_plugin_host -> vox_config
node vox_plugin_api: "vox-plugin-api"
vox_plugin_host -> vox_plugin_api
node vox_plugin_types: "vox-plugin-types"
vox_plugin_host -> vox_plugin_types
node vox_secrets: "vox-secrets"
vox_plugin_host -> vox_secrets
node vox_telemetry: "vox-telemetry"
vox_plugin_host -> vox_telemetry
node vox_actor_runtime: "vox-actor-runtime"
vox_actor_runtime -> vox_plugin_host
node vox_cli: "vox-cli"
vox_cli -> vox_plugin_host
node vox_cli_ci: "vox-cli-ci"
vox_cli_ci -> vox_plugin_host
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_plugin_host
node vox_gui: "vox-gui"
vox_gui -> vox_plugin_host
node vox_ml_cli: "vox-ml-cli"
vox_ml_cli -> vox_plugin_host
node vox_openclaw_runtime: "vox-openclaw-runtime"
vox_openclaw_runtime -> vox_plugin_host
node vox_orchestrator_mcp: "vox-orchestrator-mcp"
vox_orchestrator_mcp -> vox_plugin_host
node vox_populi: "vox-populi"
vox_populi -> vox_plugin_host
node vox_skills: "vox-skills"
vox_skills -> vox_plugin_host
}
Consumer CrateRole
vox-actor-runtimeDirect workspace dependent
vox-cliDirect workspace dependent
vox-cli-ciDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-guiDirect workspace dependent
vox-ml-cliDirect workspace dependent
vox-openclaw-runtimeDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
vox-populiDirect workspace dependent
vox-skillsDirect workspace dependent
KindSymbolSignatureSourceDescription
fnresolve_plugins_rootpub fn resolve_plugins_root() -> std::path::PathBufcrates/vox-plugin-host/src/lib.rs#L44-L51Resolve the plugin install root, respecting $VOX_PLUGINS_DIR if set. Falls back to the platform’s local data directory under vox/plugins.
fnformat_install_hintpub fn format_install_hint(plugin_id: &str, cargo_feature_hint: Option<&str>) -> Stringcrates/vox-plugin-host/src/lib.rs#L66-L81Format the canonical multi-line install hint for a missing plugin. Always includes the catalog command (vox plugin install <id>). When the caller is running from a Vox workspace checkout that contains the plugin source under crates/vox-plugin-<id>/, also appends the local-path variant so contributors get a copy-pasteable command pointing at their own checkout (no GitHub fetch needed). Optionally appends a “Build with cargo:” line when the caller knows the plugin is enabled behind a cargo feature flag on a vox crate (e.g. vox-ml-cli’s gpu / mens-candle-cuda). Pass Some(cargo_hint) with the command body — cargo build -p vox-ml-cli --release --features ....
fnworkspace_local_plugin_sourcepub fn workspace_local_plugin_source(plugin_id: &str) -> Option<std::path::PathBuf>crates/vox-plugin-host/src/lib.rs#L93-L122Detect the in-tree source directory for a plugin id when running from a Vox workspace checkout. Used by load_code_plugin to make the “plugin not installed” error message actionable for contributors and by vox plugin install <id> (catalog path) to prefer the local checkout over fetching a release tarball. Walks up from CWD looking for a crates/vox-plugin-<id>/Plugin.toml. Returns Some(path-to-crate-dir) on the first hit, None otherwise. Honors VOX_WORKSPACE_ROOT as an explicit override.
fncurrent_target_triple_keypub fn current_target_triple_key() -> &'static strcrates/vox-plugin-host/src/lib.rs#L129-L132Return the target-triple key used in [plugin.payload.artifacts] for the current build. The format is "<os>-<arch>" where os is "windows", "linux", or "macos" and arch is "x86_64" or "aarch64". This matches the keys emitted by the Plugin.toml generator and by vox plugin install.
fnload_code_plugin_by_idpub fn load_code_plugin_by_id(plugin_id: &str) -> Result<LoadedCodePlugin, errors::LoadError>crates/vox-plugin-host/src/lib.rs#L138-L142Convenience wrapper: discover the plugin install root, build the registry, and load a code plugin by id in a single call. For one-off dispatches from async contexts, wrap in tokio::task::spawn_blocking.
fnload_code_pluginpub fn load_code_plugin(crates/vox-plugin-host/src/lib.rs#L150Discover the given plugin in registry, resolve the dylib path for the current target triple, and load it via [Loader]. This is the preferred one-shot entry point for code-payload plugins. Callers can then call .plugin.as_ml_backend() (or the relevant extension point accessor) on the returned [LoadedCodePlugin].
fncached_code_pluginpub fn cached_code_plugin(crates/vox-plugin-host/src/lib.rs#L274Cached singleton: load a code plugin once and reuse the handle process-wide. First call: discover + dlopen (tens of ms). Subsequent calls: O(1) HashMap lookup. The plugin is leaked for the process lifetime (Box::leak) — code plugins are designed to never unload while the host is running. Designed for plugins called repeatedly (browser, mesh, ml backends).
structcapability::CapabilitySetpub struct CapabilitySet(BTreeSet<String>)crates/vox-plugin-host/src/capability.rs#L17Host hardware/platform tags a plugin’s requires-tag is checked against. Always includes "cpu-only". Probing degrades to fewer tags on any failure — it must never panic and never require a toolchain.
fncapability::from_tagspub fn from_tags<I: IntoIterator<Item = T>, T: Into<String>>(tags: I) -> Selfcrates/vox-plugin-host/src/capability.rs#L22-L24Build a set from an explicit list of tags (mainly for tests and callers that already know the host’s capabilities).
fncapability::satisfiespub fn satisfies(&self, requires_tag: Option<&str>) -> boolcrates/vox-plugin-host/src/capability.rs#L28-L33None (no requires-tag declared) is always satisfied. Some(tag) is satisfied iff tag is in the set.
fncapability::probepub fn probe() -> CapabilitySetcrates/vox-plugin-host/src/capability.rs#L38-L66Probe this host’s capabilities. Never panics; a probe failure for one capability yields fewer tags, never a propagated error.
fndiscover::discoverpub fn discover(root: &Path) -> Result<Registry, LoadError>crates/vox-plugin-host/src/discover.rs#L16-L109—
structerrors::PluginMissingErrorpub struct PluginMissingErrorcrates/vox-plugin-host/src/errors.rs#L9-L12Plugin-missing error. Display calls into [crate::format_install_hint] so the rendered message includes the workspace-local install command when the caller is running from a Vox workspace checkout — see that helper for the exact format and detection logic.
structerrors::SkillNotInstalledErrorpub struct SkillNotInstalledErrorcrates/vox-plugin-host/src/errors.rs#L29-L31—
enumerrors::LoadErrorpub enum LoadErrorcrates/vox-plugin-host/src/errors.rs#L47-L85—
structerrors::AbiMismatchErrorpub struct AbiMismatchErrorcrates/vox-plugin-host/src/errors.rs#L89-L96—
structerrors::ChecksumMismatchErrorpub struct ChecksumMismatchErrorcrates/vox-plugin-host/src/errors.rs#L106-L110—
structexternal_skills::ExternalSkillpub struct ExternalSkillcrates/vox-plugin-host/src/external_skills.rs#L15-L20A skill found in an external (non-plugin) skill root.
fnexternal_skills::discover_external_skillspub fn discover_external_skills(roots: &[PathBuf]) -> Vec<ExternalSkill>crates/vox-plugin-host/src/external_skills.rs#L26-L70Walk each root’s immediate subdirectories for SKILL.md, highest-precedence root first; the first skill seen for a given manifest id wins (mirrors the install-first-wins ordering callers rely on for shadowing). Missing roots and unparseable SKILL.md files are skipped with a warning.
structhost_impl::DefaultVoxHostpub struct DefaultVoxHostcrates/vox-plugin-host/src/host_impl.rs#L8-L10—
fnhost_impl::newpub fn new() -> Selfcrates/vox-plugin-host/src/host_impl.rs#L13-L16—
fnhost_impl::with_data_dirpub fn with_data_dir(data_dir: impl Into<String>) -> Selfcrates/vox-plugin-host/src/host_impl.rs#L18-L22—
structloader::Loaderpub struct Loadercrates/vox-plugin-host/src/loader.rs#L25—
structloader::LoadedCodePluginpub struct LoadedCodePlugincrates/vox-plugin-host/src/loader.rs#L27-L29—
fnloader::loadpub fn load(crates/vox-plugin-host/src/loader.rs#L32—
structregistry::PluginEntrypub struct PluginEntrycrates/vox-plugin-host/src/registry.rs#L8-L13—
structregistry::Registrypub struct Registrycrates/vox-plugin-host/src/registry.rs#L15-L18—
fnregistry::newpub fn new() -> Selfcrates/vox-plugin-host/src/registry.rs#L21-L26—
fnregistry::recordpub fn record(&self, entry: PluginEntry)crates/vox-plugin-host/src/registry.rs#L27-L32—
fnregistry::list_idspub fn list_ids(&self) -> Vec<String>crates/vox-plugin-host/src/registry.rs#L33-L35—
fnregistry::haspub fn has(&self, id: &str) -> boolcrates/vox-plugin-host/src/registry.rs#L36-L38—
fnregistry::get_full_entrypub fn get_full_entry(&self, id: &str) -> Option<PluginEntry>crates/vox-plugin-host/src/registry.rs#L41-L43Return a clone of the full [PluginEntry] for id, or None if not registered.
fnskill_author::author_skill_mdpub fn author_skill_md(name: &str, description: &str, steps: &[String]) -> Stringcrates/vox-plugin-host/src/skill_author.rs#L49-L85Build a TOML-frontmatter SKILL.md. steps render as a numbered list of inline-code tokens; an empty list yields a valid file with no steps.
enumskill_bundle::SkillBundleErrorpub enum SkillBundleErrorcrates/vox-plugin-host/src/skill_bundle.rs#L17-L24Parse error for skill bundles/manifests.
structskill_bundle::VoxSkillBundlepub struct VoxSkillBundlecrates/vox-plugin-host/src/skill_bundle.rs#L28-L37A fully-loaded skill bundle ready for installation.
fnskill_bundle::newpub fn new(manifest: SkillManifest, skill_md: impl Into<String>) -> Selfcrates/vox-plugin-host/src/skill_bundle.rs#L40-L47—
fnskill_bundle::with_tools_jsonpub fn with_tools_json(mut self, json: impl Into<String>) -> Selfcrates/vox-plugin-host/src/skill_bundle.rs#L49-L52—
fnskill_bundle::with_assetpub fn with_asset(mut self, path: impl Into<String>, data: Vec<u8>) -> Selfcrates/vox-plugin-host/src/skill_bundle.rs#L54-L57—
fnskill_bundle::content_hashpub fn content_hash(&self) -> Stringcrates/vox-plugin-host/src/skill_bundle.rs#L60-L67Compute the SHA-256 content hash over the manifest JSON + SKILL.md.
fnskill_bundle::to_jsonpub fn to_json(&self) -> Result<String, SkillBundleError>crates/vox-plugin-host/src/skill_bundle.rs#L70-L72Serialize the bundle to JSON (for registry storage or download).
fnskill_bundle::from_jsonpub fn from_json(json: &str) -> Result<Self, SkillBundleError>crates/vox-plugin-host/src/skill_bundle.rs#L75-L77Deserialize a bundle from JSON.
typeskill_bundle::SkillBundlepub type SkillBundle = VoxSkillBundlecrates/vox-plugin-host/src/skill_bundle.rs#L81Re-export type alias for ergonomics.
enumskill_parser::ParseSkillErrorpub enum ParseSkillErrorcrates/vox-plugin-host/src/skill_parser.rs#L43-L50Parse error returned by [parse_skill_md].
fnskill_parser::parse_skill_mdpub fn parse_skill_md(content: &str) -> Result<VoxSkillBundle, ParseSkillError>crates/vox-plugin-host/src/skill_parser.rs#L53-L131Parse a full SKILL.md file into a VoxSkillBundle.
structskill_registry::InstallResultpub struct InstallResultcrates/vox-plugin-host/src/skill_registry.rs#L40-L49Result of a skill installation.