nanobot/docs/extensions.md

Extensions

Extensions add capabilities to nanobot without modifying the agent loop. One extension package can contribute tools, commands, hooks, skills, channels, providers, MCP servers, or WebUI surfaces. nanobot also recognizes compatible Pi packages and OpenClaw plugins, with capability-by-capability diagnostics.

Use this page to install and manage extensions. To publish one, read Extension Authoring. For the internal design, read Extension System.

Install Safely

The WebUI Extensions page and the nanobot extensions commands use the same local extension store. The safe lifecycle is:

1. Find or install a package.
2. Inspect its source, runtime, dependencies, requested permissions, and diagnostics.
3. Grant only the permissions you understand.
4. Mark the package trusted.
5. Enable it.

Installation does not grant trust. An installed package remains visible but inactive until it is enabled, trusted, has all requested permissions, and passes dependency checks.

WebUI

Open Extensions in the sidebar:

• Installed manages packages in ~/.nanobot/extensions/.
• Discover searches npm packages marked for nanobot, Pi, or OpenClaw.
• Built in shows native nanobot capabilities projected into the same catalog. Built-in entries are informational and are not uninstallable.

Select an entry to see its contributions, dependencies, permission reasons, source, compatibility notices, and activation errors. Trust and permission controls are intentionally separate.

CLI

# Search all supported npm ecosystems
nanobot extensions search "memory"

# Search one compatibility ecosystem
nanobot extensions search "review" --ecosystem pi

# Install without trusting the package
nanobot extensions install @scope/package

# Inspect before activation
nanobot extensions inspect pi.scope.package

# Grant exactly the requested host permissions
nanobot extensions permissions pi.scope.package network.http workspace.read

# Trust and enable
nanobot extensions trust pi.scope.package
nanobot extensions enable pi.scope.package

Install from Git or a local directory when the package is not published:

nanobot extensions install https://github.com/acme/nanobot-tool.git --kind git
nanobot extensions install ./my-extension --kind local

Local-directory installation is available only to local WebUI requests. Remote browser clients cannot ask the gateway to read an arbitrary server path.

Sources and Scopes

Extensions can come from three scopes:

Scope	Typical source	Behavior
Built in	nanobot package	Trusted by construction; shown for ownership and diagnostics
User	~/.nanobot/extensions/	Installed and governed through the WebUI or CLI
Workspace	<workspace>/.nanobot/extensions/	Project-local code; controlled by workspace trust policy

When the same extension ID exists in multiple scopes, the nearest scope wins: workspace over user, user over built in. A contribution cannot silently replace another extension's contribution. Explicit replacement metadata and sufficient scope are required.

Pi and OpenClaw Packages

nanobot reads native Pi and OpenClaw package metadata and runs supported JavaScript or TypeScript entries in a Node.js sidecar. Compatibility is not all-or-nothing:

• Tools, slash commands, and supported lifecycle observation hooks can run.
• Provider-like registrations and several host-specific capabilities may be cataloged but not executable.
• Terminal UI, session-tree, renderer, shortcut, and model-control APIs do not have equivalent nanobot host surfaces.
• Every degraded or unsupported registration appears in diagnostics.

Check the compatibility matrix before depending on a package. A package appearing in search results means its metadata is recognizable, not that every upstream API is implemented.

Trust and Permissions

An extension is executable code. Review it with the same care as a Python or npm dependency.

• Enabled says the extension may activate.
• Trusted says you approve executing its code.
• Granted permissions are exact host capabilities approved for that extension.
• Dependencies must be present before activation.

Permissions are host policy, not an operating-system sandbox. A trusted native Python extension executes in the nanobot process. A Pi or OpenClaw extension executes in a separate Node.js process, which improves failure isolation but is not a strong OS security boundary. Use containers or another OS sandbox for untrusted third-party code.

npm installation uses lifecycle scripts disabled. This prevents package preinstall and postinstall scripts from running during installation, but the extension entry itself will run after you explicitly trust and enable it.

Configuration

Most users should manage installed packages in the WebUI or CLI. Advanced deployments can also define extension policy in ~/.nanobot/config.json:

{
  "extensions": {
    "enabled": true,
    "paths": ["/opt/nanobot/extensions"],
    "allow": [],
    "deny": ["acme.blocked"],
    "workspaceTrust": "ask",
    "entries": {
      "acme.review": {
        "enabled": true,
        "trusted": true,
        "permissions": ["workspace.read"],
        "config": {
          "mode": "strict"
        }
      }
    }
  }
}

Config entries do not rewrite the installation registry. See Configuration for exact fields.

Diagnose an Inactive Extension

Start with:

nanobot extensions list
nanobot extensions inspect <extension-id>

Common causes:

State or diagnostic	What to do
Untrusted	Review the package, then use trust
Requested permission pending	Grant the exact requested permission set
Disabled	Use enable or remove it from extensions.deny
Missing dependency	Install the named package, executable, environment variable, or extension
Contribution conflict	Disable one owner or use an explicit replacement from an appropriate scope
Compatibility notice	Read which upstream API was translated, degraded, or unsupported
Activation failed	Check the package entry, runtime dependency, and gateway logs

Policy changes reload the active extension host. A broken extension becomes a diagnostic and does not prevent unrelated extensions from being discovered.

Remove an Extension

nanobot extensions disable <extension-id>
nanobot extensions uninstall <extension-id>

Uninstall removes the user-scope package and its local policy record. It does not remove a built-in capability or a separately configured workspace copy.