mirror/nanobot
1
0
Fork 0
mirror of https://github.com/HKUDS/nanobot.git synced 2026-08-04 16:38:49 +00:00
Code Issues Packages Projects Releases Wiki Activity
nanobot/docs/extensions.md

2.8 KiB
Raw Blame History

Extensions

Extensions add native tools, slash commands, or lifecycle hooks without changing nanobot core. An extension is a Python package with one manifest and one registration entry point.

Use an extension when a capability needs executable integration with nanobot. Use a skill when instructions alone are enough, an App when the agent should call an external CLI, and MCP when a service already exposes an MCP server.

Install

Install from a Git repository:

nanobot extensions install https://github.com/acme/nanobot-review.git

Install a local package while developing it:

nanobot extensions install /absolute/path/to/nanobot-review --kind local

Git installs may select a branch, tag, or commit:

nanobot extensions install https://github.com/acme/nanobot-review.git \
  --ref v1.2.0

The WebUI Extensions page exposes the same Git and local installation flows. Local paths are accepted only from a browser running on the nanobot host.

Review before activation

New packages are installed enabled but untrusted. They cannot execute until you review the manifest, grant every requested permission, and trust them:

nanobot extensions inspect acme.review
nanobot extensions permissions acme.review workspace.read
nanobot extensions trust acme.review

Use list to check the result:

nanobot extensions list

Disable, untrust, or remove a package at any time:

nanobot extensions disable acme.review
nanobot extensions untrust acme.review
nanobot extensions uninstall acme.review

Changes made in the WebUI reload its gateway extension host immediately. Changes made by the standalone CLI take effect the next time the gateway or agent process starts. Failed registrations are rolled back and reported as diagnostics.

Safety model

Extensions are executable Python code. nanobot provides these controls:

  • packages are copied into ~/.nanobot/extensions/ with an integrity digest;
  • package symlinks and special files are rejected;
  • installation, permission grants, trust, and activation are separate steps;
  • changed package contents invalidate trust;
  • registration is transactional, so a failed extension does not leave tools, commands, or hooks behind;
  • remote WebUI clients cannot grant trust or permissions.

Permission declarations are consent gates, not an operating-system sandbox. Only install code you are willing to run with the same account as nanobot.

Package compatibility

The core runtime intentionally executes only the native nanobot Python contract. Pi and OpenClaw packages are not loaded directly. Compatibility adapters can be distributed as separate nanobot extensions later without adding JavaScript runtimes or package-market policy to the agent core.

See Extension Authoring to build a package.