{
    "product": "Cenvero Stratum",
    "generated_at": "2026-08-03T07:16:18+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "plugins/installing",
            "title": "Installing Plugins",
            "category": "Plugins",
            "url": "https://stratum.cenvero.com/docs/plugins/installing",
            "headings": [
                {
                    "level": 1,
                    "text": "Installing Plugins"
                },
                {
                    "level": 2,
                    "text": "Installing a plugin"
                },
                {
                    "level": 2,
                    "text": "Verifying a plugin before installing"
                },
                {
                    "level": 2,
                    "text": "Listing installed plugins"
                },
                {
                    "level": 2,
                    "text": "Disabling and re-enabling"
                },
                {
                    "level": 2,
                    "text": "Removing a plugin"
                },
                {
                    "level": 2,
                    "text": "Updating a plugin"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 791,
            "markdown": "# Installing Plugins\n\nThis page covers the full plugin lifecycle on a node: installing a package, verifying its signature, listing what is loaded, and removing a plugin cleanly. All plugin commands require `root` for mutations.\n\n## Installing a plugin\n\nPlugins are distributed as `.cenvero-plugin` files. To install one:\n\n```bash\nsudo cenvero-str-ctl plugin install /path/to/my-plugin-1.2.0.cenvero-plugin\n```\n\n**Plugins run sandboxed.** A plugin is a signed executable that the agent launches as a **supervised, unprivileged child process** under a dedicated `cenvero-str-plugin` user — never inside the agent and never as root. The agent verifies everything below **before it launches the executable**, so a bad package never starts a process. See [Building Plugins → How plugins run](/docs/plugins/overview) for the security model.\n\nBefore launching, the agent performs these checks in order:\n\n1. **Signature** — verifies that the package is intact and was genuinely signed with the developer certificate Cenvero issued, and that the certificate is authentic. A package that is tampered with, or signed with a key Cenvero never certified, is rejected.\n2. **Certificate validity** — checks that the developer certificate has not expired and has not been revoked.\n3. **Scope** — checks that the developer certificate's scope (`any`, `license:<serial>`, or `hardware:<id>`) covers this node.\n4. **Manifest** — validates that `manifest.json` declares a compatible agent API version, a valid entrypoint, and only known requested capabilities.\n5. **Dependencies** — checks that all declared dependencies are installed and satisfy the version constraints.\n\nOnly after all checks pass does the agent write the files and **launch the sandboxed child**. The capabilities the plugin is actually granted are the intersection of its requested capabilities and what its certificate's scope allows. If any check fails, nothing is written, no child is launched, and the agent prints a specific rejection reason. The agent state is unchanged.\n\n```text\nerror: plugin install failed\n  reason: developer certificate scope mismatch\n  scope:  license:ENT-2024-00042\n  node:   license ENT-2024-00099\n  action: obtain a plugin package signed with a certificate scoped to your license serial\n```\n\nOn success, the agent loads the plugin and confirms:\n\n```text\nplugin my-plugin 1.2.0 installed and loaded\n  signed by: Acme Corp Developer Certificate\n  scope:      any\n  api:        stratum/plugin/v2\n```\n\n## Verifying a plugin before installing\n\nInspect a `.cenvero-plugin` file without installing it:\n\n```bash\ncenvero-str-ctl plugin verify /path/to/my-plugin-1.2.0.cenvero-plugin\n```\n\n```text\nFIELD            VALUE\nName             my-plugin\nVersion          1.2.0\nAPI version      stratum/plugin/v2\nDeveloper        Acme Corp\nCertificate      valid (expires 2026-12-31)\nScope            any\nSignature        valid\nDependencies     (none)\nCompatible       yes\n```\n\nThis is a read-only operation and does not require root. Use it to check a plugin before distribution or before installing on a production node.\n\n## Listing installed plugins\n\n```bash\ncenvero-str-ctl plugin list\n```\n\n```text\nNAME           VERSION  STATE   SCOPE               DEVELOPER\nmy-plugin      1.2.0    loaded  any                 Acme Corp\naudit-export   0.8.1    loaded  license:ENT-2024-00042  Cenvero\ndebug-tools    1.0.0    loaded  hardware:a3f2...    Cenvero\n```\n\n| State | Meaning |\n|-------|---------|\n| `loaded` | Plugin's sandboxed child process is running normally (and is restarted with backoff if it crashes). |\n| `error` | Plugin failed to start or its child kept crashing — check `cenvero-str-ctl plugin show <name>` for the error and the captured child stderr. |\n| `disabled` | Plugin was manually disabled; its child is stopped but its files are kept. |\n\nShow full detail for one plugin:\n\n```bash\ncenvero-str-ctl plugin show my-plugin\n```\n\nThis prints the manifest, certificate detail, load time, and any runtime log lines the plugin has emitted.\n\n## Disabling and re-enabling\n\nDisable a plugin without removing it. The plugin binary and its configuration stay on disk; it is simply not loaded on the next agent start:\n\n```bash\nsudo cenvero-str-ctl plugin disable my-plugin\n\n# Re-enable later\nsudo cenvero-str-ctl plugin enable my-plugin\n```\n\nA disabled plugin's signature and certificate are re-verified when it is re-enabled, so an expired developer certificate will cause a re-enable to fail even if the plugin was installed successfully before the certificate expired.\n\n## Removing a plugin\n\n```bash\nsudo cenvero-str-ctl plugin remove my-plugin\n```\n\nThe agent unloads the plugin cleanly, removes its files, and updates the plugin registry.\n\n> Removal is unconditional: the agent does not track dependencies between plugins, so nothing warns you if another plugin expected this one to be present. If your plugins depend on each other, check that yourself before removing one, and disable it first with `plugin disable` if you want to test the effect reversibly.\n\n## Updating a plugin\n\nInstall the new version over the existing one:\n\n```bash\nsudo cenvero-str-ctl plugin install /path/to/my-plugin-1.3.0.cenvero-plugin\n```\n\nThe agent runs all the same verification steps as a fresh install. On success it unloads the old version and loads the new one with no agent restart. The old version's files are removed.\n\nTo roll back to a previous version, install the older `.cenvero-plugin` file.\n\n## See also\n\n- [Building Plugins](/docs/plugins/overview) — create, scope, sign, and ship your own plugin with `cnvstrpack`.\n- [CLI Reference](/docs/cli) — the full `plugin` command surface.\n- [Licensing](/docs/licensing) — how license enforcement affects plugin installs when a node is frozen.\n"
        }
    ]
}