nanobot/docs/extensions.md

Extensions

Extensions add capabilities to nanobot without modifying the agent loop. A package can declare tools, commands, hooks, skills, channels, providers, MCP servers, or WebUI surfaces in one governable manifest. Extension API v1 executes native Python tools, commands, and hooks plus the compatible Pi and OpenClaw surfaces listed below; other contribution kinds are catalog metadata until their owning nanobot subsystem provides an activation adapter.

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 integrity and 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 eligible copy wins: workspace over user, user over built in. An untrusted, disabled, denied, or invalid copy does not hide a usable lower-scope copy. A contribution cannot silently replace another extension's contribution. Disable one owner before activating the other; extension API v1 does not let packages replace core or third-party registrations.

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:

• Adapted packages always request runtime.node, making process-level code execution explicit before trust and activation.
• 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 record the exact capabilities you reviewed and approved.
• Dependencies must themselves be active before activation.

Permissions are consent and activation gates, not runtime capability enforcement or an operating-system sandbox. Direct extension code may access anything available to its process. A trusted native Python extension executes inside nanobot. A Pi or OpenClaw extension executes in a separate Node.js process, which improves failure isolation but is not a strong security boundary. Their generated manifests therefore request runtime.node; granting it acknowledges this execution model but does not confine the process. Use containers or another OS sandbox for untrusted third-party code.

nanobot records a package content hash at installation. If files change later, the package cannot activate, even if configuration marks it trusted; reinstall it so the new contents can be reviewed.

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. Actions from the Extensions WebUI or CLI reload the extension host. Direct edits to advanced extensions config fields are applied on the next process start.

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
Integrity mismatch	Reinstall and review the changed package
Missing dependency	Install and activate the named package, executable, environment variable, or extension
Contribution conflict	Disable one owner before activating the other
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.