diff --git a/README.md b/README.md index 944f3425..5988f67f 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,32 @@ | Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) | | Understand or extend the internals | [Architecture](./docs/architecture.md) and [Development](./docs/development.md) | +## What can nanobot do? + +nanobot is a self-hosted personal AI agent runtime. It can: + +- run in a browser WebUI or terminal +- connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, and other chat apps +- use tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents +- keep session history and long-term memory through Dream +- run long-horizon goals and scheduled automations +- expose a Python SDK and OpenAI-compatible API for integrations +- deploy as a long-running local or server-side agent gateway + +## Latest Release + +**v0.2.2 - Durability Release** + +Highlights: + +- Segmented WebUI transcripts +- Python SDK runtime controls +- Automation management +- Search/STT provider improvements +- Gateway/session/provider reliability + +[See full changelog](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2) + ## Open Source Partners

@@ -54,7 +80,10 @@ MiniMax

-## ๐Ÿ“ข News +## Release Archive + +
+Release and daily update highlights - **2026-06-22** ๐Ÿš€ Released **v0.2.2** โ€” **The Durability Release** makes nanobot sturdier for daily agent work: segmented WebUI transcripts, first-class Python SDK runtime controls, automation management, richer search/STT providers, and stronger gateway/session/provider reliability. Please see [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2) for details. - **2026-06-21** ๐Ÿงฐ Python SDK runtime controls, optional Keenable key, cleaner run hooks. @@ -67,9 +96,6 @@ - **2026-06-14** ๐Ÿ–ผ๏ธ Themed cover, partner links, stronger Codex image streaming. - **2026-06-13** ๐Ÿ—“๏ธ Session-bound automations, sturdier WhatsApp, faster WebUI startup. -
-Earlier news - - **2026-06-12** ๐Ÿ’ฌ Slack allowlisted channels can require mentions. - **2026-06-11** โœ‚๏ธ Fenced-code message splitting. - **2026-06-10** ๐Ÿ“œ Segmented transcripts, Exa/Bocha search, StepFun/SiliconFlow ASR. @@ -446,6 +472,7 @@ The WebUI is served by the WebSocket channel on port `8765` by default. The gate Browse the [repo docs](./docs/README.md) for the latest features and GitHub development version, or visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) for the stable release documentation. +- Use task-oriented guides: [Guides](./docs/guides/README.md) - Start with no technical background: [Start Without Technical Background](./docs/start-without-technical-background.md) - Start from zero with developer basics: [Install and Quick Start](./docs/quick-start.md) - Understand the runtime model: [Concepts](./docs/concepts.md) @@ -453,7 +480,7 @@ Browse the [repo docs](./docs/README.md) for the latest features and GitHub deve - Choose a provider/model: [Providers and Models](./docs/providers.md) - Copy provider setup recipes: [Provider Cookbook](./docs/provider-cookbook.md) - Debug setup and runtime failures: [Troubleshooting](./docs/troubleshooting.md) -- Talk to your nanobot with familiar chat apps: [Chat Apps](./docs/chat-apps.md) +- Talk to your nanobot with familiar chat apps: [Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) ยท [Chat Apps](./docs/chat-apps.md) - Configure providers, web search, MCP, and runtime behavior: [Configuration](./docs/configuration.md) - Integrate nanobot with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) ยท [Python SDK](./docs/python-sdk.md) - Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.md) diff --git a/docs/README.md b/docs/README.md index 5e4f1230..aa7822bc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,6 +30,41 @@ If you find a docs mistake, outdated command, or confusing step, please open an | Copy a provider setup recipe | [`provider-cookbook.md`](./provider-cookbook.md) | Pasteable OpenRouter, OpenAI, Anthropic, local model, fallback, and Langfuse setups | | Fix a first-run or runtime problem | [`troubleshooting.md`](./troubleshooting.md) | A diagnosis order and targeted checks for common failures | +## Task Guides + +Use these pages when you know the workflow you want and do not want to scan the +full reference first. + +| Goal | Guide | +|---|---| +| Build a personal AI agent | [`guides/build-a-personal-ai-agent.md`](./guides/build-a-personal-ai-agent.md) | +| Run a self-hosted AI agent | [`guides/self-hosted-ai-agent.md`](./guides/self-hosted-ai-agent.md) | +| Use a browser AI agent WebUI | [`guides/ai-agent-webui.md`](./guides/ai-agent-webui.md) | +| Connect an AI agent to chat apps | [`guides/chat-app-ai-agent.md`](./guides/chat-app-ai-agent.md) | +| Run long-running agent tasks | [`guides/long-running-ai-agent.md`](./guides/long-running-ai-agent.md) | +| Add long-term agent memory | [`guides/ai-agent-memory.md`](./guides/ai-agent-memory.md) | +| Add MCP tools to an agent | [`guides/mcp-tools-for-ai-agents.md`](./guides/mcp-tools-for-ai-agents.md) | +| Run an agent from Python | [`guides/python-ai-agent-sdk.md`](./guides/python-ai-agent-sdk.md) | +| Expose an OpenAI-compatible agent API | [`guides/openai-compatible-agent-api.md`](./guides/openai-compatible-agent-api.md) | +| Deploy a long-running agent gateway | [`guides/deploy-ai-agent-gateway.md`](./guides/deploy-ai-agent-gateway.md) | + +Platform-specific chat guides: +[`Telegram`](./guides/telegram-ai-agent.md), +[`Discord`](./guides/discord-ai-agent.md), +[`Slack`](./guides/slack-ai-agent.md), +[`WeChat`](./guides/wechat-ai-agent.md), +[`Email`](./guides/email-ai-agent.md), and +[`Mattermost`](./guides/mattermost-ai-agent.md). + +Configuration guides: +[`MCP tools`](./guides/configure-mcp-tools.md), +[`web search`](./guides/configure-web-search.md), +[`model fallback`](./guides/configure-model-fallback.md), +[`OpenAI-compatible providers`](./guides/configure-openai-compatible-provider.md), +[`Langfuse`](./guides/configure-langfuse-observability.md), +[`local security`](./guides/secure-local-ai-agent.md), and +[`gateway deployment`](./guides/deploy-nanobot-gateway.md). + ## After the First Reply Works Do not configure everything at once. Pick one next surface: diff --git a/docs/agent-social-network.md b/docs/agent-social-network.md index 74579b8b..110aad35 100644 --- a/docs/agent-social-network.md +++ b/docs/agent-social-network.md @@ -1,10 +1,93 @@ # Agent Social Network -๐Ÿˆ nanobot is capable of linking to the agent social network (agent community). **Just send one message and your nanobot joins automatically!** +An agent social network lets a nanobot instance join an external agent community +or chat network as a bot identity. After joining, nanobot can receive messages +through that network, answer with its normal agent runtime, and use the same +workspace, tools, memory, and channel access controls that apply elsewhere. -| Platform | How to Join (send this message to your bot) | -|----------|-------------| -| [**Moltbook**](https://www.moltbook.com/) | `Read https://moltbook.com/skill.md and follow the instructions to join Moltbook` | -| [**ClawdChat**](https://clawdchat.ai/) | `Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat` | +This page describes the current entry points and the safety model. Treat each +network as an external integration: only join networks you trust, keep owner +approval narrow, and review the skill instructions before asking nanobot to +follow them. -Simply send the command above to your nanobot (via CLI or any chat channel), and it will handle the rest. +## What is an agent social network? + +In nanobot docs, an agent social network is an external community that publishes +setup instructions for nanobot-compatible agents. The setup usually lives in a +remote `skill.md` file. You send nanobot a message asking it to read that file +and follow the network's registration flow. + +The external network is not part of nanobot core. nanobot provides the runtime: +model calls, tools, memory, sessions, and channel delivery. + +## What nanobot can do after joining + +After setup, the exact behavior depends on the network, but the normal pattern +is: + +- receive direct messages or community messages addressed to the bot +- reply through the configured network channel +- use normal nanobot tools allowed by your configuration +- keep session history for conversations that flow through the network +- use Dream memory if memory is enabled for the workspace + +## Supported networks + +| Platform | Join message to send to your bot | +|---|---| +| [Moltbook](https://www.moltbook.com/) | `Read https://moltbook.com/skill.md and follow the instructions to join Moltbook` | +| [ClawdChat](https://clawdchat.ai/) | `Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat` | + +Send the message from the CLI, WebUI, or an already configured chat channel. +nanobot will read the public setup instructions and perform the requested setup +using its available tools. + +## Security model + +- The remote setup instructions are external content. Read them yourself before + running the join prompt if the bot has file, shell, or network tools enabled. +- Keep `allowFrom` narrow on the channel you use for setup so only trusted users + can issue registration commands. +- Keep `tools.restrictToWorkspace` enabled unless the network setup explicitly + needs another path. +- Avoid `allowFrom: ["*"]` during setup unless the bot is isolated in a test + workspace. +- Store network tokens through environment variables when the integration + supports secrets. + +## Example workflow + +1. Confirm the local agent works: + +```bash +nanobot agent -m "Hello!" +``` + +2. Open the WebUI or a trusted chat channel. + +3. Send the join message for the network you want. + +4. Restart the gateway if the setup changes channel configuration: + +```bash +nanobot gateway +``` + +5. Send a test message through the external network and confirm the session is + routed to the expected workspace and model. + +## Limitations + +- Network features, identity, and moderation rules are controlled by the + external network. +- Availability depends on the remote setup instructions remaining reachable. +- nanobot does not automatically audit remote skills for you. +- Some networks may require public callbacks, tokens, or channel-specific + account setup. + +## Related docs + +- [Chat Apps](./chat-apps.md) +- [Security configuration](./configuration.md#security) +- [Pairing](./configuration.md#pairing) +- [Runtime self-inspection](./my-tool.md) diff --git a/docs/chat-apps.md b/docs/chat-apps.md index a71609df..4e24788e 100644 --- a/docs/chat-apps.md +++ b/docs/chat-apps.md @@ -1,6 +1,19 @@ -# Chat Apps +# Chat Apps for Self-Hosted AI Agents -Connect nanobot to your favorite chat platform. Want to build your own? See the [Channel Plugin Guide](./channel-plugin-guide.md). +Connect nanobot to Telegram, Discord, Slack, WeChat, Email, Mattermost, and +other chat platforms. This page is the full chat-channel reference. If you want +a focused setup path for one platform, start with a guide: + +| Platform | Guide | +|---|---| +| Telegram | [Build a Telegram AI Agent with nanobot](./guides/telegram-ai-agent.md) | +| Discord | [Build a Discord AI Agent with nanobot](./guides/discord-ai-agent.md) | +| Slack | [Build a Slack AI Agent with nanobot](./guides/slack-ai-agent.md) | +| WeChat | [Build a WeChat AI Agent with nanobot](./guides/wechat-ai-agent.md) | +| Email | [Build an Email AI Agent with nanobot](./guides/email-ai-agent.md) | +| Mattermost | [Build a Mattermost AI Agent with nanobot](./guides/mattermost-ai-agent.md) | + +Want to build your own channel? See the [Channel Plugin Guide](./channel-plugin-guide.md). Before configuring a chat app, make sure the local CLI path works: diff --git a/docs/configuration.md b/docs/configuration.md index 35e15704..d6c8b84a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -13,6 +13,21 @@ For setup and runtime failures, follow the diagnosis order in [`troubleshooting. > [!NOTE] > If your config file is older than the current schema, you can refresh it without overwriting your existing values: run `nanobot onboard`, then answer `N` when asked whether to overwrite the config. nanobot will merge in missing default fields and keep your current settings. +## Configuration Guides + +This page is the complete configuration reference. For task-oriented setup, use +the focused guides first and come back here for exact fields and defaults. + +| Task | Guide | +|---|---| +| Add MCP tools | [`guides/configure-mcp-tools.md`](./guides/configure-mcp-tools.md) | +| Enable web search and web fetch | [`guides/configure-web-search.md`](./guides/configure-web-search.md) | +| Configure model fallback | [`guides/configure-model-fallback.md`](./guides/configure-model-fallback.md) | +| Add an OpenAI-compatible provider | [`guides/configure-openai-compatible-provider.md`](./guides/configure-openai-compatible-provider.md) | +| Add Langfuse observability | [`guides/configure-langfuse-observability.md`](./guides/configure-langfuse-observability.md) | +| Secure a local AI agent | [`guides/secure-local-ai-agent.md`](./guides/secure-local-ai-agent.md) | +| Deploy the gateway | [`guides/deploy-nanobot-gateway.md`](./guides/deploy-nanobot-gateway.md) | + ## Quick Jump | Need | Section | diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 00000000..76f57771 --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,42 @@ +# nanobot Guides + +These guides are short task entry points. Use them when you know what you want +to build, then follow the linked reference docs for complete option tables and +edge cases. + +## Build and operate + +| Goal | Guide | +|---|---| +| Build a personal AI agent | [Build a personal AI agent](./build-a-personal-ai-agent.md) | +| Run a self-hosted AI agent | [Self-hosted AI agent](./self-hosted-ai-agent.md) | +| Use the browser workbench | [AI agent WebUI](./ai-agent-webui.md) | +| Run long-running tasks | [Long-running AI agent](./long-running-ai-agent.md) | +| Add memory | [AI agent memory](./ai-agent-memory.md) | +| Deploy a gateway | [Deploy an AI agent gateway](./deploy-ai-agent-gateway.md) | + +## Connect and integrate + +| Goal | Guide | +|---|---| +| Connect chat apps | [Chat app AI agent](./chat-app-ai-agent.md) | +| Connect Telegram | [Telegram AI agent](./telegram-ai-agent.md) | +| Connect Discord | [Discord AI agent](./discord-ai-agent.md) | +| Connect Slack | [Slack AI agent](./slack-ai-agent.md) | +| Connect WeChat | [WeChat AI agent](./wechat-ai-agent.md) | +| Connect Email | [Email AI agent](./email-ai-agent.md) | +| Connect Mattermost | [Mattermost AI agent](./mattermost-ai-agent.md) | +| Run from Python | [Python AI agent SDK](./python-ai-agent-sdk.md) | +| Expose `/v1/chat/completions` | [OpenAI-compatible agent API](./openai-compatible-agent-api.md) | + +## Configure + +| Goal | Guide | +|---|---| +| Add MCP tools | [Configure MCP tools](./configure-mcp-tools.md) | +| Enable web search | [Configure web search](./configure-web-search.md) | +| Add model fallback | [Configure model fallback](./configure-model-fallback.md) | +| Add an OpenAI-compatible provider | [Configure an OpenAI-compatible provider](./configure-openai-compatible-provider.md) | +| Add Langfuse tracing | [Configure Langfuse observability](./configure-langfuse-observability.md) | +| Secure local tools | [Secure a local AI agent](./secure-local-ai-agent.md) | +| Deploy the gateway | [Deploy nanobot gateway](./deploy-nanobot-gateway.md) | diff --git a/docs/guides/ai-agent-memory.md b/docs/guides/ai-agent-memory.md new file mode 100644 index 00000000..48191737 --- /dev/null +++ b/docs/guides/ai-agent-memory.md @@ -0,0 +1,72 @@ +# How AI Agent Memory Works in nanobot + +This guide explains how to use nanobot's long-term AI agent memory: session +history, compressed archives, durable memory files, Dream consolidation, and +Git-backed memory changes. + +## What you will build + +- a workspace with persistent session history +- compressed history archives for older turns +- durable memory files such as `USER.md` and `MEMORY.md` +- a Dream workflow for curating long-term memory + +## When to use this + +Use memory when an agent should remember stable preferences, project facts, +decisions, and recurring context across sessions. Do not use memory as a dumping +ground for every raw transcript; nanobot separates short-term messages from +curated durable knowledge. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +## Minimal working example + +Ask the agent to remember a stable fact in a normal session, then run Dream: + +```text +/dream +``` + +Inspect recent memory changes: + +```text +/dream-log +``` + +The exact files live in the active workspace, usually under +`~/.nanobot/workspace/`. + +## Production notes + +- Use one workspace per project or personal context. +- Keep durable facts concise; old session details belong in `history.jsonl`. +- Use `/dream-prompt init` when a workspace needs custom memory guidance. +- Review Git-backed memory changes when memory affects important workflows. + +## Security notes + +- Memory files may contain sensitive user or project facts. +- Avoid sharing workspaces without reviewing `SOUL.md`, `USER.md`, and + `memory/MEMORY.md`. +- Use separate workspaces for personal and team contexts. + +## Troubleshooting + +- If memory feels stale, run `/dream` and inspect `/dream-log`. +- If memory changed incorrectly, use `/dream-restore` to inspect and restore + previous versions. +- If a new session lacks context, confirm it uses the same workspace. + +## Related nanobot docs + +- [AI Agent Memory in nanobot](../memory.md) +- [Concepts](../concepts.md) +- [Configuration](../configuration.md#auto-compact) +- [Chat Commands](../chat-commands.md) diff --git a/docs/guides/ai-agent-webui.md b/docs/guides/ai-agent-webui.md new file mode 100644 index 00000000..f94b5bae --- /dev/null +++ b/docs/guides/ai-agent-webui.md @@ -0,0 +1,67 @@ +# How to Use an AI Agent WebUI with nanobot + +nanobot includes a browser WebUI for persistent chat sessions, visible agent +activity, workspace controls, Apps, MCP presets, Skills, settings, and +Automations. + +## What you will build + +- a local browser workbench +- one persistent chat session +- a visible timeline of agent messages, tool calls, and file activity +- a gateway-backed WebSocket connection + +## When to use this + +Use the WebUI when you want a local AI agent interface that is easier to operate +than a terminal, especially for project work, file attachments, model switching, +workspace selection, Apps, Skills, and scheduled automations. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +The published wheel already includes the WebUI bundle. You only need the +`webui/` source directory when changing the frontend. + +## Minimal working example + +```bash +nanobot webui +``` + +The launcher checks setup, enables the local WebSocket channel after +confirmation, starts the gateway, and opens the browser. + +## Production notes + +- Use `nanobot webui --background` when you do not want to keep a terminal open. +- Use `nanobot gateway status`, `logs`, `restart`, and `stop` to manage a + background gateway. +- If you expose the WebUI beyond localhost, set a token issue secret and review + workspace/tool access. + +## Security notes + +- The first-run WebUI path binds to `127.0.0.1` by default. +- Do not expose the WebUI on a LAN or public host without an intentional access + model. +- Keep file and shell tools scoped to the workspace before inviting other users. + +## Troubleshooting + +- The WebUI is served by the WebSocket channel on port `8765` by default. +- The gateway health endpoint is separate from the browser UI. +- If the page opens but messages fail, check provider setup with + `nanobot agent -m "Hello!"`. + +## Related nanobot docs + +- [Nanobot WebUI](../webui.md) +- [Quick Start](../quick-start.md) +- [WebSocket protocol](../websocket.md) +- [Configuration](../configuration.md) diff --git a/docs/guides/build-a-personal-ai-agent.md b/docs/guides/build-a-personal-ai-agent.md new file mode 100644 index 00000000..1c0c2da6 --- /dev/null +++ b/docs/guides/build-a-personal-ai-agent.md @@ -0,0 +1,82 @@ +# How to Build a Personal AI Agent with nanobot + +This guide builds a personal AI agent you can run locally, talk to from the +terminal or browser, and later connect to chat apps, memory, tools, and +automations. + +## What you will build + +- a configured nanobot install +- one working model provider +- one local agent reply +- a browser WebUI session for ongoing work + +## When to use this + +Use this when you want a personal AI agent that you control rather than a hosted +chat-only interface. nanobot is useful when the agent needs local workspace +access, tool calls, session history, memory, scheduled work, or chat app +delivery. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +The wizard creates `~/.nanobot/config.json` and helps you choose a provider and +model. If terminals and config files are new to you, use +[Start Without Technical Background](../start-without-technical-background.md) +instead. + +## Minimal working example + +First prove the runtime can answer: + +```bash +nanobot agent -m "Hello!" +``` + +Then open the browser workbench: + +```bash +nanobot webui +``` + +The WebUI starts the local gateway, opens a browser, and keeps persistent chat +sessions for longer work. + +## Production notes + +- Keep one workspace per project or personal context. +- Use `modelPresets` when you want stable names for fast, deep, local, or + fallback models. +- Keep `nanobot gateway` running for WebUI, chat apps, automations, and the + WebSocket channel. +- Use the Python SDK or OpenAI-compatible API when another program should call + the agent. + +## Security notes + +- Do not store API keys directly in shared files; use environment variables. +- Keep chat app `allowFrom` lists narrow. +- Enable workspace restriction before exposing file or shell tools to other + users. +- Use a separate workspace for experiments that can modify files. + +## Troubleshooting + +- `nanobot status` shows the config path, workspace path, and active model. +- If `nanobot agent -m "Hello!"` fails, fix provider setup before opening the + WebUI or chat apps. +- If the WebUI opens but does not answer, check gateway logs and provider + credentials. + +## Related nanobot docs + +- [Quick Start](../quick-start.md) +- [Concepts](../concepts.md) +- [WebUI](../webui.md) +- [Configuration](../configuration.md) +- [Troubleshooting](../troubleshooting.md) diff --git a/docs/guides/chat-app-ai-agent.md b/docs/guides/chat-app-ai-agent.md new file mode 100644 index 00000000..fb4127ff --- /dev/null +++ b/docs/guides/chat-app-ai-agent.md @@ -0,0 +1,83 @@ +# How to Connect an AI Agent to Chat Apps with nanobot + +nanobot can run as a self-hosted chatbot or AI agent in Telegram, Discord, +Slack, WeChat, Email, Mattermost, and other chat apps. The gateway receives chat +messages, runs the agent, and sends replies back to the same channel. + +## What you will build + +- a working local agent +- one enabled chat channel +- a running gateway +- a narrow access-control rule for the first test user + +## When to use this + +Use chat apps when the agent should live where users already communicate: +private DMs, team channels, group chats, email threads, or bot workspaces. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +Then choose one platform guide: + +- [Telegram AI agent](./telegram-ai-agent.md) +- [Discord AI agent](./discord-ai-agent.md) +- [Slack AI agent](./slack-ai-agent.md) +- [WeChat AI agent](./wechat-ai-agent.md) +- [Email AI agent](./email-ai-agent.md) +- [Mattermost AI agent](./mattermost-ai-agent.md) + +## Minimal working example + +Every channel follows the same pattern: + +1. Get the platform token, login state, webhook, or mailbox credentials. +2. Merge the channel snippet into `~/.nanobot/config.json`. +3. Keep access narrow with `allowFrom`, `allowChannels`, or pairing. +4. Check status: + +```bash +nanobot channels status +``` + +5. Start the gateway: + +```bash +nanobot gateway +``` + +6. Send a test message from an allowed account. + +## Production notes + +- Keep the gateway running as a service for always-on chat apps. +- Use mention-only group policies before opening a bot to busy channels. +- Use one channel at a time while debugging. +- Prefer DMs for first tests; group chats add permissions and routing behavior. + +## Security notes + +- Do not use `allowFrom: ["*"]` outside an intentional sandbox. +- Rotate bot tokens if they are pasted into logs or shared files. +- Review file, shell, and web tool access before inviting other users. + +## Troubleshooting + +- If `nanobot channels status` does not show the channel, the config key or + optional dependency is likely missing. +- If messages do not arrive, run `nanobot gateway --verbose` and compare + platform credentials, event permissions, and allow lists. +- If group replies are unexpected, review that channel's group policy. + +## Related nanobot docs + +- [Chat Apps](../chat-apps.md) +- [Configuration](../configuration.md#channel-settings) +- [Pairing](../configuration.md#pairing) +- [Deployment](../deployment.md) diff --git a/docs/guides/configure-langfuse-observability.md b/docs/guides/configure-langfuse-observability.md new file mode 100644 index 00000000..140a24d0 --- /dev/null +++ b/docs/guides/configure-langfuse-observability.md @@ -0,0 +1,79 @@ +# How to Configure Langfuse Observability for nanobot + +nanobot can trace supported OpenAI-compatible provider calls through Langfuse's +OpenAI SDK wrapper. + +## What you will build + +- Langfuse installed in the same Python environment as nanobot +- Langfuse environment variables set before startup +- one traced nanobot model call + +## When to use this + +Use Langfuse when you need observability for model requests, latency, errors, +cost, or prompt behavior during development or production operation. + +## Install + +Install nanobot and prove the agent works: + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +Install Langfuse: + +```bash +python -m pip install langfuse +``` + +## Minimal working example + +Set credentials before starting nanobot: + +```bash +export LANGFUSE_SECRET_KEY="sk-lf-..." +export LANGFUSE_PUBLIC_KEY="pk-lf-..." +export LANGFUSE_BASE_URL="https://cloud.langfuse.com" +nanobot agent -m "Hello!" +``` + +PowerShell: + +```powershell +$env:LANGFUSE_SECRET_KEY = "sk-lf-..." +$env:LANGFUSE_PUBLIC_KEY = "pk-lf-..." +$env:LANGFUSE_BASE_URL = "https://cloud.langfuse.com" +nanobot agent -m "Hello!" +``` + +## Production notes + +- Langfuse is configured with environment variables, not `config.json`. +- Start services from an environment that exports the same variables. +- Add tracing after the provider works; it should not be the first setup step. +- Native providers that do not use the OpenAI-compatible client path may not + produce Langfuse OpenAI-wrapper traces. + +## Security notes + +- Treat Langfuse projects as observability stores for sensitive prompts and + outputs. +- Use separate projects for personal, staging, and production traffic. +- Keep Langfuse keys out of committed service files. + +## Troubleshooting + +- If no traces appear, confirm the service process sees the environment + variables. +- Confirm the provider path is OpenAI-compatible. +- Run one local `nanobot agent -m "Hello!"` call before debugging service logs. + +## Related nanobot docs + +- [Configuration: Langfuse Observability](../configuration.md#langfuse-observability) +- [Provider Cookbook: Langfuse Tracing](../provider-cookbook.md#recipe-langfuse-tracing) +- [Deployment](../deployment.md) diff --git a/docs/guides/configure-mcp-tools.md b/docs/guides/configure-mcp-tools.md new file mode 100644 index 00000000..ae014b59 --- /dev/null +++ b/docs/guides/configure-mcp-tools.md @@ -0,0 +1,74 @@ +# How to Configure MCP Tools in nanobot + +This guide adds an MCP server to nanobot so the agent can use external tools +through the Model Context Protocol. + +## What you will build + +- a working nanobot agent +- one MCP server entry in `~/.nanobot/config.json` +- a restricted set of MCP tools exposed to the model + +## When to use this + +Use MCP when the capability you need already exists as an MCP server, or when +you want external tools to be managed outside nanobot core. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +Install the MCP server runtime separately. Many examples use `npx`, `uvx`, or a +remote HTTP endpoint. + +## Minimal working example + +Add this to `~/.nanobot/config.json`: + +```json +{ + "tools": { + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"], + "enabledTools": ["read_file"] + } + } + } +} +``` + +Restart nanobot and ask a question that requires the MCP tool. + +## Production notes + +- Prefer `enabledTools` over exposing every tool by default. +- Use `toolTimeout` for slow MCP operations. +- Use HTTP MCP only for endpoints you trust. +- Keep MCP server commands stable and versioned in deployment docs or scripts. + +## Security notes + +- Stdio MCP starts a local process; review the command before enabling it. +- HTTP/SSE MCP uses nanobot's SSRF guard. +- Allow private HTTP MCP hosts only with narrow `tools.ssrfWhitelist` CIDRs. +- Do not place secrets in command arguments when environment variables or + headers can be used. + +## Troubleshooting + +- Run the MCP command outside nanobot first. +- Start `nanobot gateway --verbose` and inspect tool registration logs. +- If an HTTP MCP URL is blocked, check whether it points to loopback or a + private address that needs explicit allowlisting. + +## Related nanobot docs + +- [MCP tools for AI agents](./mcp-tools-for-ai-agents.md) +- [Configuration: MCP](../configuration.md#mcp-model-context-protocol) +- [Security](../configuration.md#security) diff --git a/docs/guides/configure-model-fallback.md b/docs/guides/configure-model-fallback.md new file mode 100644 index 00000000..2b78d475 --- /dev/null +++ b/docs/guides/configure-model-fallback.md @@ -0,0 +1,90 @@ +# How to Configure Model Fallback in nanobot + +Model fallback lets nanobot try a primary model first, then fall back to one or +more named presets when the primary provider fails or rate-limits. + +## What you will build + +- two or more `modelPresets` +- a primary `agents.defaults.modelPreset` +- an ordered `agents.defaults.fallbackModels` chain + +## When to use this + +Use fallback when you want better reliability across rate limits, provider +outages, local model downtime, or cost-sensitive routing. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +Verify each provider works before adding it as a fallback. + +## Minimal working example + +Merge this shape into `~/.nanobot/config.json` and replace provider/model names +with ones you control: + +```json +{ + "modelPresets": { + "fast": { + "label": "Fast", + "provider": "openrouter", + "model": "anthropic/claude-sonnet-4.5", + "maxTokens": 4096, + "contextWindowTokens": 65536, + "temperature": 0.1 + }, + "deep": { + "label": "Deep", + "provider": "anthropic", + "model": "claude-sonnet-4-5", + "maxTokens": 4096, + "contextWindowTokens": 200000, + "temperature": 0.1 + } + }, + "agents": { + "defaults": { + "modelPreset": "fast", + "fallbackModels": ["deep"] + } + } +} +``` + +String entries in `fallbackModels` are preset names, not raw model IDs. + +## Production notes + +- Keep fallback context windows realistic; smaller fallback windows constrain + how much context can fit. +- Put cheaper or faster fallbacks before expensive ones when acceptable. +- Use `/model ` for runtime switching without editing config. +- Keep labels human-readable for WebUI model lists. + +## Security notes + +- Different providers may have different data handling policies. +- Do not put provider keys directly in shared config files. +- Confirm fallback models can safely receive the same prompts and files. + +## Troubleshooting + +- If a fallback never triggers, confirm the primary error is treated as + retryable/fallbackable. +- If startup fails, check that each fallback string matches a key under + `modelPresets`. +- If output is truncated after fallback, review `maxTokens` and + `contextWindowTokens`. + +## Related nanobot docs + +- [Providers and Models](../providers.md) +- [Provider Cookbook: Fallback Presets](../provider-cookbook.md#recipe-fallback-presets) +- [Configuration: Model Fallbacks](../configuration.md#model-fallbacks) diff --git a/docs/guides/configure-openai-compatible-provider.md b/docs/guides/configure-openai-compatible-provider.md new file mode 100644 index 00000000..60345a0b --- /dev/null +++ b/docs/guides/configure-openai-compatible-provider.md @@ -0,0 +1,93 @@ +# How to Configure an OpenAI-Compatible Provider in nanobot + +nanobot can call OpenAI-compatible model providers by configuring an `apiBase`, +optional `apiKey`, and a model preset that references that provider name. + +## What you will build + +- a custom provider entry +- a model preset pointing at that provider +- one successful `nanobot agent` run + +## When to use this + +Use this for local or hosted services that expose OpenAI-compatible endpoints, +including internal gateways, local model servers, and provider proxies that are +not already named in nanobot. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +Verify the endpoint responds before debugging nanobot: + +```bash +curl -sS https://api.example.com/v1/models +``` + +## Minimal working example + +Merge this into `~/.nanobot/config.json`: + +```json +{ + "providers": { + "custom": { + "apiKey": "${CUSTOM_API_KEY}", + "apiBase": "https://api.example.com/v1" + } + }, + "modelPresets": { + "primary": { + "label": "Custom", + "provider": "custom", + "model": "provider-model-name", + "maxTokens": 4096, + "contextWindowTokens": 65536, + "temperature": 0.1 + } + }, + "agents": { + "defaults": { + "modelPreset": "primary" + } + } +} +``` + +Then run: + +```bash +nanobot agent -m "Hello!" +``` + +## Production notes + +- Include the version path in `apiBase` when the service expects `/v1`. +- Use separate provider names for separate endpoints. +- Use a placeholder key such as `EMPTY` only when the endpoint requires a + non-empty key but does not validate it. +- Leave `apiType` unset for OpenAI-compatible custom endpoints. + +## Security notes + +- Keep provider keys in environment variables. +- Treat internal model gateways as sensitive network services. +- Do not point nanobot at untrusted proxy endpoints for private workspaces. + +## Troubleshooting + +- If `curl /models` fails, fix the provider endpoint before changing nanobot. +- If nanobot says the model is unknown, check the model ID expected by the + provider. +- If auth fails, confirm whether the provider wants Bearer auth and whether the + key is present in the environment that starts nanobot. + +## Related nanobot docs + +- [Provider Cookbook: Custom OpenAI-Compatible Provider](../provider-cookbook.md#recipe-custom-openai-compatible-provider) +- [Providers: Custom OpenAI-Compatible Endpoint](../providers.md#custom-openai-compatible-endpoint) +- [OpenAI-Compatible Agent API](./openai-compatible-agent-api.md) diff --git a/docs/guides/configure-web-search.md b/docs/guides/configure-web-search.md new file mode 100644 index 00000000..610f6394 --- /dev/null +++ b/docs/guides/configure-web-search.md @@ -0,0 +1,90 @@ +# How to Configure Web Search for a nanobot AI Agent + +nanobot includes built-in web search and web fetch tools. Search uses +DuckDuckGo by default and can be configured for API-backed or self-hosted +providers. + +## What you will build + +- web tools enabled in nanobot +- one search provider selected in `config.json` +- optional web fetch settings for page reading + +## When to use this + +Configure web search when the agent needs current information, public web +research, source discovery, or page fetching during a task. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +Web tools are enabled by default. Configure them only when you want a specific +provider, API key, proxy, fetch behavior, or SSRF allowlist. + +## Minimal working example + +Use the default search provider: + +```json +{ + "tools": { + "web": { + "enable": true, + "search": { + "provider": "duckduckgo" + } + } + } +} +``` + +Or use an API-backed provider: + +```json +{ + "tools": { + "web": { + "search": { + "provider": "brave", + "apiKey": "${BRAVE_API_KEY}" + } + } + } +} +``` + +Ask a question that requires current information and inspect the tool activity +in the WebUI or logs. + +## Production notes + +- Keep API keys in environment variables. +- Set `maxResults` when you need fewer or more search results per query. +- Set `tools.web.proxy` only to a proxy you trust. +- Use `fetch.useJinaReader: false` if you need local page conversion. + +## Security notes + +- Web fetch and HTTP MCP share an SSRF guard. +- Private, loopback, link-local, and cloud metadata addresses are blocked by + default. +- Add `tools.ssrfWhitelist` only for narrow trusted CIDRs. +- Do not give public chat users unrestricted web and shell access without + review. + +## Troubleshooting + +- If search returns no results, switch provider or check the provider API key. +- If fetch is blocked, inspect the target URL and SSRF whitelist. +- If a proxy changes network behavior, verify `NO_PROXY` and proxy settings. + +## Related nanobot docs + +- [Configuration: Web Tools](../configuration.md#web-tools) +- [Security](../configuration.md#security) +- [WebUI](../webui.md) diff --git a/docs/guides/deploy-ai-agent-gateway.md b/docs/guides/deploy-ai-agent-gateway.md new file mode 100644 index 00000000..5b9303f9 --- /dev/null +++ b/docs/guides/deploy-ai-agent-gateway.md @@ -0,0 +1,68 @@ +# How to Deploy a Long-Running AI Agent Gateway with nanobot + +The nanobot gateway is the long-running process behind WebUI sessions, chat app +messages, automations, local triggers, and WebSocket delivery. + +## What you will build + +- a configured nanobot instance +- a gateway process that survives terminal exits +- a service or container deployment path + +## When to use this + +Deploy the gateway when nanobot must keep receiving messages or running +automations after a one-off CLI command ends. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +## Minimal working example + +Start the gateway in the foreground: + +```bash +nanobot gateway +``` + +For browser usage, the WebUI launcher can manage the gateway: + +```bash +nanobot webui --background +``` + +For server usage, configure Docker, systemd, or macOS LaunchAgent from the +deployment reference. + +## Production notes + +- Keep config and workspace paths explicit in services. +- Persist `~/.nanobot/config.json`, the workspace, sessions, and memory files. +- Use one process per config/workspace pair. +- Expose only the ports required by the surfaces you use. + +## Security notes + +- Bind local-only surfaces to `127.0.0.1`. +- Add an API key before exposing `nanobot serve` beyond localhost. +- Restrict chat app access and workspace tools before putting the gateway on a + shared server. + +## Troubleshooting + +- Use `nanobot status` with the same config/workspace as the service. +- Check service logs for provider, port, channel, and permission errors. +- If WebUI works locally but not remotely, verify host binding, token settings, + and firewall rules. + +## Related nanobot docs + +- [Deploy nanobot gateway](./deploy-nanobot-gateway.md) +- [Deployment](../deployment.md) +- [Multiple Instances](../multiple-instances.md) +- [WebUI](../webui.md) diff --git a/docs/guides/deploy-nanobot-gateway.md b/docs/guides/deploy-nanobot-gateway.md new file mode 100644 index 00000000..6551b63f --- /dev/null +++ b/docs/guides/deploy-nanobot-gateway.md @@ -0,0 +1,75 @@ +# How to Deploy nanobot Gateway + +The nanobot gateway is the process that keeps WebUI, chat apps, automations, +heartbeat jobs, Dream, and WebSocket delivery online. + +## What you will build + +- a verified nanobot config +- a gateway process +- an optional Docker, systemd, or macOS LaunchAgent deployment + +## When to use this + +Use this when nanobot should keep running after a single CLI turn: chat apps, +browser sessions, background automations, local triggers, and server-side +integrations all depend on a live gateway. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot status +nanobot agent -m "Hello!" +``` + +## Minimal working example + +Run the gateway in the foreground: + +```bash +nanobot gateway +``` + +For WebUI background usage: + +```bash +nanobot webui --background +nanobot gateway status +nanobot gateway logs +``` + +## Production notes + +- Docker Compose is the most repeatable Linux container path. +- systemd user services are useful for Linux user-level gateway deployments. +- macOS LaunchAgent keeps the gateway alive after login. +- Persist config, workspace, sessions, memory files, channel login state, and + generated artifacts. +- Restart the gateway after editing `config.json`. + +## Security notes + +- Plan ports before exposing services. Gateway health defaults to `18790`, + WebUI/WebSocket defaults to `8765`, and `nanobot serve` defaults to `8900`. +- Bind externally only when you have configured tokens or API keys. +- Keep chat access control intentional before deploying. +- Use Docker or Linux sandboxing when shell tools are enabled for unattended + work. + +## Troubleshooting + +- Use the same `--config` and `--workspace` flags for status checks and service + startup. +- Check logs with `docker compose logs`, `journalctl`, LaunchAgent logs, or + `nanobot gateway --verbose`. +- If Docker port publishing does not work, confirm the service is not bound only + to container loopback. + +## Related nanobot docs + +- [Deploy a long-running AI agent gateway](./deploy-ai-agent-gateway.md) +- [Deployment](../deployment.md) +- [Multiple Instances](../multiple-instances.md) +- [Configuration](../configuration.md) diff --git a/docs/guides/discord-ai-agent.md b/docs/guides/discord-ai-agent.md new file mode 100644 index 00000000..6bdf67af --- /dev/null +++ b/docs/guides/discord-ai-agent.md @@ -0,0 +1,97 @@ +# Build a Discord AI Agent with nanobot + +This guide connects nanobot to Discord so a Discord user or server channel can +talk to your self-hosted AI agent through the nanobot gateway. + +## What this guide builds + +- a Discord bot application +- Message Content intent enabled +- the `discord` channel enabled in nanobot +- one direct message or mention test + +## Prerequisites + +- A working local nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- Access to the Discord Developer Portal. +- A Discord server where you can invite a bot. +- Your Discord user ID. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the Discord channel + +Install the optional channel dependency: + +```bash +nanobot plugins enable discord +``` + +Create a Discord application, add a bot, copy the token, and enable +`MESSAGE CONTENT INTENT` in the bot settings. + +Merge this snippet into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "discord": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allowFrom": ["YOUR_USER_ID"], + "allowChannels": [], + "groupPolicy": "mention", + "streaming": true + } + } +} +``` + +Invite the bot with permissions to read history and send messages. + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +Send the bot a DM from your allowed account, or mention it in an allowed server +channel: + +```text +@your-bot Hello from Discord +``` + +## Security notes + +- Keep `groupPolicy` as `mention` for first deployment. +- Use `allowChannels` for server channels where the bot should operate. +- Avoid open group behavior in busy channels until session routing is clear. +- Review tool access before inviting the bot into shared servers. + +## Troubleshooting + +- If no messages arrive, confirm Message Content intent is enabled. +- If server messages are ignored, check `allowFrom`, `allowChannels`, and + whether the bot was mentioned. +- If the bot cannot reply, confirm the invite permissions and channel overrides. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [Pairing](../configuration.md#pairing) +- [AI Agent Memory](./ai-agent-memory.md) +- [Configure MCP tools](./configure-mcp-tools.md) diff --git a/docs/guides/email-ai-agent.md b/docs/guides/email-ai-agent.md new file mode 100644 index 00000000..fcf1b2fd --- /dev/null +++ b/docs/guides/email-ai-agent.md @@ -0,0 +1,92 @@ +# Build an Email AI Agent with nanobot + +This guide turns nanobot into an email AI agent that polls IMAP for accepted +messages and replies through SMTP. + +## What this guide builds + +- a dedicated mailbox for nanobot +- IMAP and SMTP credentials in `config.json` +- an allowed sender list +- a gateway process that polls and replies + +## Prerequisites + +- A working local nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- A mailbox for the bot. +- IMAP and SMTP access. For Gmail, use an app password rather than your account + password. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the Email channel + +Merge this snippet into `~/.nanobot/config.json` and replace the addresses and +passwords: + +```json +{ + "channels": { + "email": { + "enabled": true, + "consentGranted": true, + "imapHost": "imap.gmail.com", + "imapPort": 993, + "imapUsername": "my-nanobot@gmail.com", + "imapPassword": "your-app-password", + "smtpHost": "smtp.gmail.com", + "smtpPort": 587, + "smtpUsername": "my-nanobot@gmail.com", + "smtpPassword": "your-app-password", + "fromAddress": "my-nanobot@gmail.com", + "allowFrom": ["your-real-email@gmail.com"], + "autoReplyEnabled": true + } + } +} +``` + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +Send an email from an address in `allowFrom` to the bot mailbox. Keep the +gateway running long enough for the polling interval to receive it. + +## Security notes + +- Use a dedicated mailbox, not your primary personal inbox. +- Set `consentGranted` to `false` to fully disable mailbox access. +- Keep `allowFrom` narrow; `["*"]` accepts mail from anyone. +- Use environment variables for mailbox passwords. +- Enable attachment types only when the agent needs them. + +## Troubleshooting + +- If login fails, confirm IMAP/SMTP access and app-password setup. +- If the bot reads but does not reply, check `autoReplyEnabled`, SMTP settings, + and allowed sender addresses. +- If attachments are missing, review `allowedAttachmentTypes`, size limits, and + gateway logs. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [Secure local AI agent](./secure-local-ai-agent.md) +- [AI Agent Memory](./ai-agent-memory.md) +- [OpenAI-compatible agent API](./openai-compatible-agent-api.md) diff --git a/docs/guides/long-running-ai-agent.md b/docs/guides/long-running-ai-agent.md new file mode 100644 index 00000000..dde41d39 --- /dev/null +++ b/docs/guides/long-running-ai-agent.md @@ -0,0 +1,72 @@ +# How to Run a Long-Running AI Agent with nanobot + +nanobot can keep agent work alive across turns through sustained goals, +persistent sessions, scheduled automations, local triggers, and a gateway +process that stays running. + +## What you will build + +- a working local agent +- a persistent chat session +- a long-running goal or automation +- a gateway process for background delivery + +## When to use this + +Use this when the task is not a one-shot answer: project work, recurring checks, +scheduled summaries, file maintenance, multi-step research, or local triggers +from scripts and build jobs. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +## Minimal working example + +Start a gateway: + +```bash +nanobot gateway +``` + +From the WebUI or a chat session, start a sustained goal: + +```text +/goal Review this workspace, identify missing tests, and propose the smallest next fix. +``` + +For scheduled or trigger-based runs, create the automation from the target chat +so nanobot can link it to the correct session and workspace. + +## Production notes + +- Keep the gateway running for chat apps, WebUI sessions, automations, and local + triggers. +- Use stable session keys or chat sessions for work that should preserve context. +- Keep goals bounded and explicit about done-ness. +- Review Automations in the WebUI before relying on a schedule. + +## Security notes + +- Treat long-running goals as delegated work with real tool access. +- Restrict workspaces and shell execution before scheduling unattended tasks. +- Keep chat access narrow so unknown users cannot create goals or automations. + +## Troubleshooting + +- If a goal appears stuck, inspect the active session and gateway logs. +- If an automation does not run, check that it is linked to a chat/session and + that the gateway is still running. +- If a local trigger fails, check the command copied from the WebUI Automations + view. + +## Related nanobot docs + +- [WebUI Automations](../webui.md#automations) +- [Chat Commands](../chat-commands.md) +- [Memory](../memory.md) +- [Deployment](../deployment.md) diff --git a/docs/guides/mattermost-ai-agent.md b/docs/guides/mattermost-ai-agent.md new file mode 100644 index 00000000..390db79e --- /dev/null +++ b/docs/guides/mattermost-ai-agent.md @@ -0,0 +1,94 @@ +# Build a Mattermost AI Agent with nanobot + +This guide connects nanobot to Mattermost through the built-in Mattermost +channel, using WebSocket events and the Mattermost REST API. + +## What this guide builds + +- a Mattermost bot account or token +- the `mattermost` channel enabled in nanobot +- mention-only group behavior for first deployment +- one DM or mention test + +## Prerequisites + +- A working local nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- A Mattermost server URL. +- A bot token or personal access token for the bot account. +- Your Mattermost user ID, username, or email depending on + `allowFromMatchMode`. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the Mattermost channel + +Merge this snippet into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "mattermost": { + "enabled": true, + "serverUrl": "https://mattermost.example.com", + "token": "YOUR_MATTERMOST_TOKEN", + "teamId": "YOUR_TEAM_ID", + "allowFromMatchMode": "id", + "allowFrom": ["YOUR_USER_ID"], + "groupPolicy": "mention", + "replyInThread": true + } + } +} +``` + +`teamId` scopes the channel to a Mattermost team. Keep `groupPolicy` as +`mention` for the first test. + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +DM the bot account or mention it in a channel where the bot has access: + +```text +@nanobot Hello from Mattermost +``` + +## Security notes + +- Store the Mattermost token in an environment variable for deployed services. +- Keep `allowFrom` narrow until pairing or team policy is intentional. +- Use mention-only group behavior before opening the bot to busy channels. +- Review file and shell tools before inviting broad channel access. + +## Troubleshooting + +- If startup logs say `serverUrl and token must be configured`, check the + camelCase config keys. +- If DMs are ignored, review the `dm` policy and `allowFrom` values. +- If channel messages are ignored, confirm the bot is mentioned and belongs to + the team/channel. +- If thread replies are surprising, review `replyInThread` and + `includeThreadContext`. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [Pairing](../configuration.md#pairing) +- [Long-running AI Agent](./long-running-ai-agent.md) +- [Deployment](../deployment.md) diff --git a/docs/guides/mcp-tools-for-ai-agents.md b/docs/guides/mcp-tools-for-ai-agents.md new file mode 100644 index 00000000..68c7aa91 --- /dev/null +++ b/docs/guides/mcp-tools-for-ai-agents.md @@ -0,0 +1,75 @@ +# How to Add MCP Tools to an AI Agent with nanobot + +nanobot can connect MCP servers and expose their tools to the agent alongside +built-in file, shell, web, cron, image generation, and subagent tools. + +## What you will build + +- a working nanobot agent +- one MCP server configured in `config.json` +- a restricted set of tools available to the model + +## When to use this + +Use MCP when a tool already exists as an MCP server, when another application +publishes an MCP adapter, or when you want a clean boundary between nanobot and +external tool logic. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +Install the MCP server's own runtime separately. For example, many local MCP +servers use `npx` or `uvx`. + +## Minimal working example + +Add a stdio MCP server to `~/.nanobot/config.json`: + +```json +{ + "tools": { + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"], + "enabledTools": ["read_file"] + } + } + } +} +``` + +Restart nanobot, then ask a question that needs the MCP tool. + +## Production notes + +- Use `enabledTools` to expose only the tools the agent actually needs. +- Set `toolTimeout` for slow MCP servers. +- Prefer stdio MCP for local tools and HTTP MCP for trusted remote services. +- Keep MCP server install/update steps outside nanobot config when possible. + +## Security notes + +- HTTP/SSE MCP URLs use the same SSRF guard as web fetch. +- Local/private HTTP endpoints require an explicit `tools.ssrfWhitelist` entry. +- Stdio MCP servers run local processes; review their command and arguments. +- Do not pass secrets in command-line args when environment variables or headers + are available. + +## Troubleshooting + +- Start `nanobot gateway --verbose` and check MCP startup logs. +- Confirm the MCP command works by itself before debugging nanobot. +- If an HTTP MCP server is blocked, review the SSRF whitelist and use a narrow + host CIDR. + +## Related nanobot docs + +- [Configure MCP tools](./configure-mcp-tools.md) +- [Configuration: MCP](../configuration.md#mcp-model-context-protocol) +- [Security](../configuration.md#security) diff --git a/docs/guides/openai-compatible-agent-api.md b/docs/guides/openai-compatible-agent-api.md new file mode 100644 index 00000000..4b12c441 --- /dev/null +++ b/docs/guides/openai-compatible-agent-api.md @@ -0,0 +1,74 @@ +# How to Run an OpenAI-Compatible Agent API with nanobot + +nanobot can expose a local OpenAI-compatible endpoint behind +`/v1/chat/completions`. This lets existing OpenAI-style clients talk to a +tool-using nanobot agent instead of a raw model. + +## What you will build + +- a working nanobot agent +- a local API server on `127.0.0.1:8900` +- a `/v1/chat/completions` request +- optional session isolation with `session_id` + +## When to use this + +Use this when an existing client, another language, or a separate process +already knows how to call an OpenAI-compatible API. Use the Python SDK when you +want in-process access to sessions, memory, runtime helpers, and hooks. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot plugins enable api +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +## Minimal working example + +Start the API server: + +```bash +nanobot serve +``` + +Call the chat endpoint: + +```bash +curl http://127.0.0.1:8900/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [{"role": "user", "content": "hi"}], + "session_id": "demo" + }' +``` + +## Production notes + +- Pass `session_id` to isolate users, jobs, or workflows. +- Streaming uses Server-Sent Events when `stream` is `true`. +- `/v1/models` reports the fixed model surface expected by compatible clients. +- File uploads are supported through JSON base64 or multipart form data. + +## Security notes + +- Local `127.0.0.1` usage does not require an API key. +- If `api.host` is `0.0.0.0` or `::`, configure `api.apiKey` before startup. +- Treat the API as agent access, not just model access: tools and workspace + permissions still matter. + +## Troubleshooting + +- If `/v1/chat/completions` fails, test `nanobot agent -m "Hello!"` first. +- If remote clients cannot connect, check `api.host`, `api.port`, firewall, and + API key configuration. +- If sessions mix together, pass unique `session_id` values. + +## Related nanobot docs + +- [Nanobot OpenAI-Compatible API](../openai-api.md) +- [Python SDK](../python-sdk.md) +- [Configuration](../configuration.md) +- [Deployment](../deployment.md) diff --git a/docs/guides/python-ai-agent-sdk.md b/docs/guides/python-ai-agent-sdk.md new file mode 100644 index 00000000..283dea95 --- /dev/null +++ b/docs/guides/python-ai-agent-sdk.md @@ -0,0 +1,75 @@ +# Nanobot Python SDK: Run an AI Agent from Python + +This guide shows when to use the Nanobot Python SDK instead of calling a model +directly. The SDK runs the same agent runtime used by the CLI: model routing, +tools, workspace access, session history, memory, streaming events, and runtime +helpers. + +## What you will build + +- a Python script that creates a `Nanobot` +- one agent run from code +- an optional streamed run with tool visibility + +## When to use this + +Use the Python SDK for notebooks, evals, product backends, local scripts, +workflow runners, and integrations that need direct access to agent sessions, +memory, hooks, runtime state, or structured run results. + +Use the OpenAI-compatible API instead when another language or process should +call nanobot over HTTP. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +## Minimal working example + +```python +import asyncio + +from nanobot import Nanobot + + +async def main() -> None: + async with Nanobot.from_config() as bot: + result = await bot.run("List the top-level files in this workspace.") + print(result.content) + + +asyncio.run(main()) +``` + +## Production notes + +- Reuse one `Nanobot` instance for related work. +- Pass `session_key` when a user, job, or eval case needs persistent history. +- Use `bot.stream(...)` when the caller needs live text, tool, or failure + events. +- Use hooks for audit logs or custom observability. + +## Security notes + +- The SDK uses the same config, workspace, tools, and secrets as the CLI. +- Do not run untrusted prompts with broad file or shell access. +- Keep separate config/workspace paths for separate products or tenants. + +## Troubleshooting + +- If SDK code fails, first run `nanobot agent -m "Hello!"` in the same + environment. +- Print `bot.runtime.workspace` and `bot.runtime.model` to confirm the expected + config loaded. +- Use explicit `config_path` and `workspace` when scripts run from services. + +## Related nanobot docs + +- [Nanobot Python SDK](../python-sdk.md) +- [OpenAI-Compatible API](../openai-api.md) +- [Configuration](../configuration.md) +- [Concepts](../concepts.md) diff --git a/docs/guides/secure-local-ai-agent.md b/docs/guides/secure-local-ai-agent.md new file mode 100644 index 00000000..8f9d4f4a --- /dev/null +++ b/docs/guides/secure-local-ai-agent.md @@ -0,0 +1,76 @@ +# How to Secure a Local AI Agent with nanobot + +This guide covers the practical controls to review before letting a nanobot +agent access files, shell commands, web fetch, chat apps, or remote users. + +## What you will build + +- a workspace-scoped agent setup +- narrow channel access +- safer secrets handling +- optional shell sandboxing on Linux + +## When to use this + +Use this before exposing nanobot to teammates, chat apps, public networks, broad +web access, or unattended automations. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +## Minimal working example + +Start with workspace restriction: + +```json +{ + "tools": { + "restrictToWorkspace": true, + "exec": { + "enable": true, + "sandbox": "bwrap" + } + } +} +``` + +`bwrap` is Linux-only and requires bubblewrap. On macOS or Windows, keep +`restrictToWorkspace` enabled and review shell access carefully. + +## Production notes + +- Use environment variables for provider keys, bot tokens, and mailbox + passwords. +- Keep one workspace per trust boundary. +- Use `allowFrom`, pairing, and mention-only group policy for chat apps. +- Bind WebUI, WebSocket, and API services to localhost unless remote access is + intentional. + +## Security notes + +- `restrictToWorkspace` is an application-level guard, not an OS sandbox. +- `tools.exec.enable: false` removes shell execution entirely. +- HTTP web fetch and HTTP MCP use SSRF protections by default. +- Adding broad `tools.ssrfWhitelist` ranges increases exposure. +- `allowFrom: ["*"]` means anyone who can reach that channel can talk to the + bot. + +## Troubleshooting + +- If a needed file cannot be read, confirm the active workspace path. +- If a shell command fails under `bwrap`, check whether the command needs files + outside the sandbox. +- If local HTTP tools are blocked, review the SSRF whitelist and use a narrow + CIDR. + +## Related nanobot docs + +- [Configuration: Security](../configuration.md#security) +- [Pairing](../configuration.md#pairing) +- [Deployment](../deployment.md) +- [Chat Apps](../chat-apps.md) diff --git a/docs/guides/self-hosted-ai-agent.md b/docs/guides/self-hosted-ai-agent.md new file mode 100644 index 00000000..352a0509 --- /dev/null +++ b/docs/guides/self-hosted-ai-agent.md @@ -0,0 +1,82 @@ +# How to Run a Self-Hosted AI Agent with nanobot + +This guide sets up nanobot as a self-hosted AI agent runtime on your own +machine or server. The result is a gateway process that can serve the WebUI, +chat apps, automations, and API integrations. + +## What you will build + +- a nanobot config and workspace under your control +- a model provider connected through `config.json` +- a long-running `nanobot gateway` +- optional browser, chat app, and API access + +## When to use this + +Use this path when you want local or server-side ownership of the agent process, +workspace files, memory files, and provider keys. It is also the right path when +the agent must keep running after one terminal command finishes. + +## Install + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +nanobot agent -m "Hello!" +``` + +Complete the CLI check before deploying the gateway. A deployment problem is +much easier to debug after the provider and model are known to work. + +## Minimal working example + +For chat apps, automations, and WebSocket delivery, start the gateway: + +```bash +nanobot gateway +``` + +For the browser surface, use the WebUI launcher instead. It can start and manage +the local gateway for you: + +```bash +nanobot webui +``` + +Or connect a channel in `~/.nanobot/config.json`, then keep the same gateway +process running for messages. + +## Production notes + +- Use Docker, systemd, or a macOS LaunchAgent when the process should survive + terminal exits. +- Give every deployed instance a distinct config path, workspace path, and port + set. +- Keep secrets in environment variables and start the service from the same + environment. +- Use health checks against the gateway or API process, not chat app delivery as + the only signal. + +## Security notes + +- Bind local-only services to `127.0.0.1` unless you intentionally expose them. +- Set an API key before binding the OpenAI-compatible API to a public interface. +- Keep `allowFrom` or pairing rules strict on every chat app. +- Enable `tools.restrictToWorkspace`; on Linux, use the bubblewrap sandbox for + shell execution. + +## Troubleshooting + +- Run `nanobot status` with the same `--config` and `--workspace` flags used by + the service. +- Run `nanobot gateway --verbose` while debugging channel startup. +- Check port conflicts if the WebUI, WebSocket channel, or API endpoint fails to + bind. + +## Related nanobot docs + +- [Deployment](../deployment.md) +- [Multiple Instances](../multiple-instances.md) +- [Configuration](../configuration.md) +- [Chat Apps](../chat-apps.md) +- [OpenAI-Compatible API](../openai-api.md) diff --git a/docs/guides/slack-ai-agent.md b/docs/guides/slack-ai-agent.md new file mode 100644 index 00000000..730e39c6 --- /dev/null +++ b/docs/guides/slack-ai-agent.md @@ -0,0 +1,94 @@ +# Build a Slack AI Agent with nanobot + +This guide connects nanobot to Slack through Socket Mode. No public webhook URL +is required for the first working setup. + +## What this guide builds + +- a Slack app with Socket Mode +- a bot token and app-level token +- the `slack` channel enabled in nanobot +- a DM or mention test from an allowed Slack user + +## Prerequisites + +- A working nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- Permission to create a Slack app in a workspace. +- Your Slack user ID. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the Slack channel + +Install the optional channel dependency: + +```bash +nanobot plugins enable slack +``` + +In Slack, create an app, enable Socket Mode, create an app-level token with +`connections:write`, add bot scopes, subscribe to bot events, and install the +app to your workspace. + +Merge this snippet into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "slack": { + "enabled": true, + "botToken": "xoxb-...", + "appToken": "xapp-...", + "allowFrom": ["YOUR_SLACK_USER_ID"], + "groupPolicy": "mention" + } + } +} +``` + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +DM the Slack bot directly, or mention it in a channel: + +```text +@nanobot Hello from Slack +``` + +## Security notes + +- Keep `groupPolicy` as `mention` unless the bot is intentionally listening to + every channel message. +- Use `groupAllowFrom` with allowlist mode for approved channels. +- Reinstall the Slack app after changing scopes. +- Keep bot and app tokens out of committed config files. + +## Troubleshooting + +- If Socket Mode fails, confirm the app-level token starts with `xapp-`. +- If the bot cannot send files, add `files:write`, reinstall the app, and + restart nanobot. +- If channel messages are ignored, check event subscriptions and group policy. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [Configure web search](./configure-web-search.md) +- [Long-running AI Agent](./long-running-ai-agent.md) +- [Deployment](../deployment.md) diff --git a/docs/guides/telegram-ai-agent.md b/docs/guides/telegram-ai-agent.md new file mode 100644 index 00000000..9792f199 --- /dev/null +++ b/docs/guides/telegram-ai-agent.md @@ -0,0 +1,98 @@ +# Build a Telegram AI Agent with nanobot + +This guide connects nanobot to Telegram so an allowed Telegram user can message +a self-hosted AI agent backed by your normal nanobot config, tools, memory, and +workspace. + +## What this guide builds + +- a Telegram bot created through BotFather +- the `telegram` channel enabled in nanobot +- a running nanobot gateway +- one test message from an allowed Telegram account + +## Prerequisites + +- A working nanobot CLI reply: + +```bash +nanobot agent -m "Hello!" +``` + +- A Telegram account. +- A bot token from `@BotFather`. +- Your Telegram user ID for `allowFrom`. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the Telegram channel + +Install the optional channel dependency: + +```bash +nanobot plugins enable telegram +``` + +Merge this snippet into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allowFrom": ["YOUR_USER_ID"] + } + } +} +``` + +Telegram uses long polling by default. Webhook mode is available for public +HTTPS deployments; start with long polling for the first test. + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +Leave the gateway running while you test messages. + +## Test a message + +Open Telegram, message the bot from the user in `allowFrom`, and send: + +```text +Hello from Telegram +``` + +The reply should use the same model and workspace as your local CLI check. + +## Security notes + +- Keep `allowFrom` to your own user ID until the bot is stable. +- Do not use `allowFrom: ["*"]` unless the bot is isolated or intentionally + public. +- Rotate the BotFather token if it is pasted into logs or shared files. +- Review tool access before adding group chats or more users. + +## Troubleshooting + +- If the channel is not listed, run `nanobot plugins enable telegram` again in + the same Python environment. +- If messages do not arrive, run `nanobot gateway --verbose` and check the bot + token and allowed user ID. +- If Telegram Web shows unsupported rich messages, keep `richMessages` disabled. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [AI Agent Memory](./ai-agent-memory.md) +- [Long-running AI Agent](./long-running-ai-agent.md) +- [Configure MCP tools](./configure-mcp-tools.md) diff --git a/docs/guides/wechat-ai-agent.md b/docs/guides/wechat-ai-agent.md new file mode 100644 index 00000000..54042f87 --- /dev/null +++ b/docs/guides/wechat-ai-agent.md @@ -0,0 +1,92 @@ +# Build a WeChat AI Agent with nanobot + +This guide connects nanobot to WeChat through the `weixin` channel. The channel +uses HTTP long polling with QR-code login through the supported upstream API. + +## What this guide builds + +- the `weixin` channel enabled in nanobot +- a QR-code login session +- one allowed WeChat sender +- a running gateway for message delivery + +## Prerequisites + +- A working local nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- A WeChat account that can complete QR-code login. +- The sender ID from logs for `allowFrom`, or a temporary private test setup. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the WeChat channel + +Install the optional channel dependency: + +```bash +nanobot plugins enable weixin +``` + +Merge this snippet into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "weixin": { + "enabled": true, + "allowFrom": ["YOUR_WECHAT_USER_ID"] + } + } +} +``` + +Log in: + +```bash +nanobot channels login weixin +``` + +Use `--force` if you need to discard saved login state and authenticate again. + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +Send a private WeChat message from the allowed account and watch gateway logs for +the sender ID and reply. + +## Security notes + +- Keep `allowFrom` narrow after you identify the sender ID. +- Treat saved login state as sensitive account access. +- Avoid connecting personal accounts to untrusted workspaces or broad tool + permissions. + +## Troubleshooting + +- If login fails, rerun `nanobot channels login weixin --force`. +- If messages arrive but are ignored, update `allowFrom` with the sender ID + shown in logs. +- If polling disconnects, restart the gateway and check network reachability to + the upstream service. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [AI Agent Memory](./ai-agent-memory.md) +- [Secure local AI agent](./secure-local-ai-agent.md) +- [Deployment](../deployment.md) diff --git a/docs/memory.md b/docs/memory.md index 2b847497..c8d899d4 100644 --- a/docs/memory.md +++ b/docs/memory.md @@ -1,4 +1,8 @@ -# Memory in nanobot +# AI Agent Memory in nanobot + +This page explains how nanobot implements long-term AI agent memory: session +history, compressed archives, durable knowledge files, Dream consolidation, and +Git-backed memory changes. nanobot's memory is built on a simple belief: memory should feel alive, but it should not feel chaotic. diff --git a/docs/openai-api.md b/docs/openai-api.md index f31e7e42..7c315a87 100644 --- a/docs/openai-api.md +++ b/docs/openai-api.md @@ -1,4 +1,4 @@ -# OpenAI-Compatible API +# Nanobot OpenAI-Compatible API: Run a Local Agent Behind /v1/chat/completions nanobot can expose a minimal OpenAI-compatible endpoint for local integrations: diff --git a/docs/python-sdk.md b/docs/python-sdk.md index 967872fe..97c7e13c 100644 --- a/docs/python-sdk.md +++ b/docs/python-sdk.md @@ -1,4 +1,4 @@ -# Python SDK +# Nanobot Python SDK: Run an AI Agent from Python Use nanobot as a Python library. The SDK gives you the same agent runtime used by the CLI, but from code: model routing, tools, workspace access, conversation diff --git a/docs/webui.md b/docs/webui.md index 40515c31..edda9cbd 100644 --- a/docs/webui.md +++ b/docs/webui.md @@ -1,4 +1,6 @@ -# WebUI +# Nanobot WebUI: Browser Workbench for Self-Hosted AI Agents + + The WebUI is nanobot's browser workbench for persistent chat sessions, visible agent activity, workspace controls, Apps, Skills, settings, and Automations in