docs: improve search entry pages
This commit is contained in:
chengyongru
Xubin Ren
@@ -47,6 +47,32 @@
|
|||||||
| Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) |
|
| 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) |
|
| 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
|
## Open Source Partners
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
@@ -54,7 +80,10 @@
|
|||||||
<a href="https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link"><img alt="MiniMax" height="40" src="https://mintcdn.com/minimax-zh/1UjvBcdoC6r0UeyA/logo/light.svg?fit=max&auto=format&n=1UjvBcdoC6r0UeyA&q=85&s=672d724b639b2d88d0702fae329ea4f8"></a>
|
<a href="https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link"><img alt="MiniMax" height="40" src="https://mintcdn.com/minimax-zh/1UjvBcdoC6r0UeyA/logo/light.svg?fit=max&auto=format&n=1UjvBcdoC6r0UeyA&q=85&s=672d724b639b2d88d0702fae329ea4f8"></a>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
## 📢 News
|
## Release Archive
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Release and daily update highlights</summary>
|
||||||
|
|
||||||
- **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-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.
|
- **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-14** 🖼️ Themed cover, partner links, stronger Codex image streaming.
|
||||||
- **2026-06-13** 🗓️ Session-bound automations, sturdier WhatsApp, faster WebUI startup.
|
- **2026-06-13** 🗓️ Session-bound automations, sturdier WhatsApp, faster WebUI startup.
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>Earlier news</summary>
|
|
||||||
|
|
||||||
- **2026-06-12** 💬 Slack allowlisted channels can require mentions.
|
- **2026-06-12** 💬 Slack allowlisted channels can require mentions.
|
||||||
- **2026-06-11** ✂️ Fenced-code message splitting.
|
- **2026-06-11** ✂️ Fenced-code message splitting.
|
||||||
- **2026-06-10** 📜 Segmented transcripts, Exa/Bocha search, StepFun/SiliconFlow ASR.
|
- **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.
|
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 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)
|
- Start from zero with developer basics: [Install and Quick Start](./docs/quick-start.md)
|
||||||
- Understand the runtime model: [Concepts](./docs/concepts.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)
|
- Choose a provider/model: [Providers and Models](./docs/providers.md)
|
||||||
- Copy provider setup recipes: [Provider Cookbook](./docs/provider-cookbook.md)
|
- Copy provider setup recipes: [Provider Cookbook](./docs/provider-cookbook.md)
|
||||||
- Debug setup and runtime failures: [Troubleshooting](./docs/troubleshooting.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)
|
- 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)
|
- 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)
|
- Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.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 |
|
| 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 |
|
| 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
|
## After the First Reply Works
|
||||||
|
|
||||||
Do not configure everything at once. Pick one next surface:
|
Do not configure everything at once. Pick one next surface:
|
||||||
|
|||||||
@@ -1,10 +1,93 @@
|
|||||||
# Agent Social Network
|
# 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) |
|
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
|
||||||
| [**Moltbook**](https://www.moltbook.com/) | `Read https://moltbook.com/skill.md and follow the instructions to join Moltbook` |
|
approval narrow, and review the skill instructions before asking nanobot to
|
||||||
| [**ClawdChat**](https://clawdchat.ai/) | `Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat` |
|
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)
|
||||||
|
|||||||
+15
-2
@@ -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:
|
Before configuring a chat app, make sure the local CLI path works:
|
||||||
|
|
||||||
|
|||||||
@@ -13,6 +13,21 @@ For setup and runtime failures, follow the diagnosis order in [`troubleshooting.
|
|||||||
> [!NOTE]
|
> [!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.
|
> 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
|
## Quick Jump
|
||||||
|
|
||||||
| Need | Section |
|
| Need | Section |
|
||||||
|
|||||||
@@ -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) |
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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 <preset>` 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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
+5
-1
@@ -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.
|
nanobot's memory is built on a simple belief: memory should feel alive, but it should not feel chaotic.
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -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:
|
nanobot can expose a minimal OpenAI-compatible endpoint for local integrations:
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -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
|
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
|
by the CLI, but from code: model routing, tools, workspace access, conversation
|
||||||
|
|||||||
+3
-1
@@ -1,4 +1,6 @@
|
|||||||
# WebUI
|
# Nanobot WebUI: Browser Workbench for Self-Hosted AI Agents
|
||||||
|
|
||||||
|
<!-- Meta description: Run nanobot from a browser WebUI with persistent chat sessions, visible tool activity, workspace controls, Apps, MCP presets, Skills, settings, and Automations. -->
|
||||||
|
|
||||||
The WebUI is nanobot's browser workbench for persistent chat sessions, visible
|
The WebUI is nanobot's browser workbench for persistent chat sessions, visible
|
||||||
agent activity, workspace controls, Apps, Skills, settings, and Automations in
|
agent activity, workspace controls, Apps, Skills, settings, and Automations in
|
||||||
|
|||||||
Reference in New Issue
Block a user