Distribution

Plugins travel over npm, install without a rebuild, and reconcile declaratively at boot. This page covers how a plugin reaches an instance: the npm resolver and pacote fetch, the boot-time reconcile, the bundled set that ships built-ins, the adoption seam that migrates data when a core feature becomes a plugin, and the version-pinned workflow bundle build. For the manifest and the install review, see authoring; for exact-state fleet control, see GitOps.

npm as transport

plugins.install accepts a local directory or an npm spec: name[@range] or a file:tarball.tgz. An npm spec is fetched with pacote straight into ~/Subspace/plugins/<name>@<version>/, integrity-checked. Crucially, npm never touches the server’s node_modules: a plugin is copied into its own immutable version directory and imported from there, so installing a plugin cannot perturb the host’s own dependencies and there is no rebuild. An npm install also resolves the manifest’s dependencies first, recursively and topologically, and the install response returns the resolved dependency tree with each already-satisfied node marked satisfied: true.

Boot-time reconcile

Instances converge on a desired plugin set declaratively at boot rather than through imperative install commands.

1. SUBSPACE_PLUGINS

   The SUBSPACE_PLUGINS environment variable (comma- or space-separated npm specs or local paths) reconciles first: missing plugins install into the volume, satisfied ones are left untouched, and a failing spec logs and never bricks boot.

2. Bundled set

   The bundled plugin sweep runs next, installing and enabling the in-repo set.

3. GitOps

   The GitOps plugins.json sync runs last, as the outer authority.

The bundled set

plugins/bundled.json ({"plugins": [<in-repo plugin directory names>]}) lists the plugins that install and enable idempotently on every trusted-plane boot, after the SUBSPACE_PLUGINS reconcile and before the GitOps sync. This is how domain features ship as plugins with zero UX regression: MLOps, CRM, meetings, spaced repetition, and outreach are bundled plugins that a fresh home and an upgraded home both converge on.

Note

A bundled plugin you (or GitOps) disable stays disabled: a same-version sync short-circuits before install, so the boot sweep never re-enables it. A version bump re-installs and re-enables. A missing or invalid bundled.json yields an empty set, never a boot failure.

The first-enable adoption seam

When a feature that used to live in core becomes a plugin, the plugin needs to adopt the data core already wrote. A plugin registers a one-time, core-implemented migration step by name (for example, copying existing SRS card rows into a collection). installPlugin runs the step inside the install transaction, claim-guarded by an ops.plugin_state (plugin, 'adopted') row.

Tip

The claim and the step commit atomically. A throwing step fails the whole install so nothing is left half-adopted, and it retries on the next install; a completed step never re-runs, across re-installs and upgrades alike. Steps are written to be idempotent regardless, and the step’s returned note is stored in the claim row’s value.

Workflow bundles

A plugin’s workflows: [{ dir, names }] ships compiled WDK standalone bundles that run on the durable agent engine. Every installed version directory imports at boot (superseded and disabled included, so in-flight runs resume against their pinned id), while the unversioned alias <plugin>/<fn> resolves to the newest enabled version’s workflow//<plugin>@<version>//<fn> only at run start, so a mid-flight upgrade never mutates a running body. syncPluginWorkflows reconciles aliases on boot and on every plugins event: it hot-imports on install, repoints only once the import completes, drops aliases on disable (the bundles stay for draining), and refuses non-package-mode ids (relative ./ specifiers). Shipping workflows requires pinning sdk: 1. An agent definition binds a workflow through its workflow: <alias> field.

Package-mode builds

The @subspace/plugin-sdk build command compiles a plugin’s use workflow sources into the version-pinned bundle the host requires:

subspace-plugin build [pluginDir] [--dir workflows] [--shared-external]

The stock builder emits relative ids (workflow//./…) that the host refuses. The SDK forces package mode: it runs the standalone builder with the module root pointed at a throwaway package whose package.json lists the plugin as a dependency, so the sources resolve as a workspace package and produce ids like workflow//<name>@<version>//<fn> (name and version read from the plugin’s package.json). It writes the {"type":"commonjs"} marker the host’s import() needs, and an assertion fails the build if any id came out relative.

Tip

--shared-external (or sharedExternal: true) stops each bundle from inlining @workflow/core (observed to shrink step.js from about 9.3 MB to about 18 KB). The CJS marker gains "externals": ["@workflow/core"], and the host symlinks its own copy next to the bundle at import time. Such bundles run only inside a Subspace host, and undeclared externals are refused at import. The flow.js half always stays self-contained.

GitOps and fleet control

For declarative fleet management, GitOps runs a plugins.json in exact-state mode as the outer authority: it runs after the bundled sweep and can disable bundled entries to enforce a precise plugin set across an instance. See GitOps for the full reconcile model, and self-hosting for where these files live.

See also

Authoring a pluginThe manifest, dependencies, and the install review card.

GitOpsExact-state plugins.json fleet control.

Agent engineThe durable engine plugin workflow bundles run on.

Environment variablesSUBSPACE_PLUGINS and other boot configuration.