docs: improve search entry pages
This commit is contained in:
chengyongru
Xubin Ren
@@ -30,6 +30,41 @@ If you find a docs mistake, outdated command, or confusing step, please open an
|
||||
| Copy a provider setup recipe | [`provider-cookbook.md`](./provider-cookbook.md) | Pasteable OpenRouter, OpenAI, Anthropic, local model, fallback, and Langfuse setups |
|
||||
| Fix a first-run or runtime problem | [`troubleshooting.md`](./troubleshooting.md) | A diagnosis order and targeted checks for common failures |
|
||||
|
||||
## Task Guides
|
||||
|
||||
Use these pages when you know the workflow you want and do not want to scan the
|
||||
full reference first.
|
||||
|
||||
| Goal | Guide |
|
||||
|---|---|
|
||||
| Build a personal AI agent | [`guides/build-a-personal-ai-agent.md`](./guides/build-a-personal-ai-agent.md) |
|
||||
| Run a self-hosted AI agent | [`guides/self-hosted-ai-agent.md`](./guides/self-hosted-ai-agent.md) |
|
||||
| Use a browser AI agent WebUI | [`guides/ai-agent-webui.md`](./guides/ai-agent-webui.md) |
|
||||
| Connect an AI agent to chat apps | [`guides/chat-app-ai-agent.md`](./guides/chat-app-ai-agent.md) |
|
||||
| Run long-running agent tasks | [`guides/long-running-ai-agent.md`](./guides/long-running-ai-agent.md) |
|
||||
| Add long-term agent memory | [`guides/ai-agent-memory.md`](./guides/ai-agent-memory.md) |
|
||||
| Add MCP tools to an agent | [`guides/mcp-tools-for-ai-agents.md`](./guides/mcp-tools-for-ai-agents.md) |
|
||||
| Run an agent from Python | [`guides/python-ai-agent-sdk.md`](./guides/python-ai-agent-sdk.md) |
|
||||
| Expose an OpenAI-compatible agent API | [`guides/openai-compatible-agent-api.md`](./guides/openai-compatible-agent-api.md) |
|
||||
| Deploy a long-running agent gateway | [`guides/deploy-ai-agent-gateway.md`](./guides/deploy-ai-agent-gateway.md) |
|
||||
|
||||
Platform-specific chat guides:
|
||||
[`Telegram`](./guides/telegram-ai-agent.md),
|
||||
[`Discord`](./guides/discord-ai-agent.md),
|
||||
[`Slack`](./guides/slack-ai-agent.md),
|
||||
[`WeChat`](./guides/wechat-ai-agent.md),
|
||||
[`Email`](./guides/email-ai-agent.md), and
|
||||
[`Mattermost`](./guides/mattermost-ai-agent.md).
|
||||
|
||||
Configuration guides:
|
||||
[`MCP tools`](./guides/configure-mcp-tools.md),
|
||||
[`web search`](./guides/configure-web-search.md),
|
||||
[`model fallback`](./guides/configure-model-fallback.md),
|
||||
[`OpenAI-compatible providers`](./guides/configure-openai-compatible-provider.md),
|
||||
[`Langfuse`](./guides/configure-langfuse-observability.md),
|
||||
[`local security`](./guides/secure-local-ai-agent.md), and
|
||||
[`gateway deployment`](./guides/deploy-nanobot-gateway.md).
|
||||
|
||||
## After the First Reply Works
|
||||
|
||||
Do not configure everything at once. Pick one next surface:
|
||||
|
||||
@@ -1,10 +1,93 @@
|
||||
# Agent Social Network
|
||||
|
||||
🐈 nanobot is capable of linking to the agent social network (agent community). **Just send one message and your nanobot joins automatically!**
|
||||
An agent social network lets a nanobot instance join an external agent community
|
||||
or chat network as a bot identity. After joining, nanobot can receive messages
|
||||
through that network, answer with its normal agent runtime, and use the same
|
||||
workspace, tools, memory, and channel access controls that apply elsewhere.
|
||||
|
||||
| Platform | How to Join (send this message to your bot) |
|
||||
|----------|-------------|
|
||||
| [**Moltbook**](https://www.moltbook.com/) | `Read https://moltbook.com/skill.md and follow the instructions to join Moltbook` |
|
||||
| [**ClawdChat**](https://clawdchat.ai/) | `Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat` |
|
||||
This page describes the current entry points and the safety model. Treat each
|
||||
network as an external integration: only join networks you trust, keep owner
|
||||
approval narrow, and review the skill instructions before asking nanobot to
|
||||
follow them.
|
||||
|
||||
Simply send the command above to your nanobot (via CLI or any chat channel), and it will handle the rest.
|
||||
## What is an agent social network?
|
||||
|
||||
In nanobot docs, an agent social network is an external community that publishes
|
||||
setup instructions for nanobot-compatible agents. The setup usually lives in a
|
||||
remote `skill.md` file. You send nanobot a message asking it to read that file
|
||||
and follow the network's registration flow.
|
||||
|
||||
The external network is not part of nanobot core. nanobot provides the runtime:
|
||||
model calls, tools, memory, sessions, and channel delivery.
|
||||
|
||||
## What nanobot can do after joining
|
||||
|
||||
After setup, the exact behavior depends on the network, but the normal pattern
|
||||
is:
|
||||
|
||||
- receive direct messages or community messages addressed to the bot
|
||||
- reply through the configured network channel
|
||||
- use normal nanobot tools allowed by your configuration
|
||||
- keep session history for conversations that flow through the network
|
||||
- use Dream memory if memory is enabled for the workspace
|
||||
|
||||
## Supported networks
|
||||
|
||||
| Platform | Join message to send to your bot |
|
||||
|---|---|
|
||||
| [Moltbook](https://www.moltbook.com/) | `Read https://moltbook.com/skill.md and follow the instructions to join Moltbook` |
|
||||
| [ClawdChat](https://clawdchat.ai/) | `Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat` |
|
||||
|
||||
Send the message from the CLI, WebUI, or an already configured chat channel.
|
||||
nanobot will read the public setup instructions and perform the requested setup
|
||||
using its available tools.
|
||||
|
||||
## Security model
|
||||
|
||||
- The remote setup instructions are external content. Read them yourself before
|
||||
running the join prompt if the bot has file, shell, or network tools enabled.
|
||||
- Keep `allowFrom` narrow on the channel you use for setup so only trusted users
|
||||
can issue registration commands.
|
||||
- Keep `tools.restrictToWorkspace` enabled unless the network setup explicitly
|
||||
needs another path.
|
||||
- Avoid `allowFrom: ["*"]` during setup unless the bot is isolated in a test
|
||||
workspace.
|
||||
- Store network tokens through environment variables when the integration
|
||||
supports secrets.
|
||||
|
||||
## Example workflow
|
||||
|
||||
1. Confirm the local agent works:
|
||||
|
||||
```bash
|
||||
nanobot agent -m "Hello!"
|
||||
```
|
||||
|
||||
2. Open the WebUI or a trusted chat channel.
|
||||
|
||||
3. Send the join message for the network you want.
|
||||
|
||||
4. Restart the gateway if the setup changes channel configuration:
|
||||
|
||||
```bash
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
5. Send a test message through the external network and confirm the session is
|
||||
routed to the expected workspace and model.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Network features, identity, and moderation rules are controlled by the
|
||||
external network.
|
||||
- Availability depends on the remote setup instructions remaining reachable.
|
||||
- nanobot does not automatically audit remote skills for you.
|
||||
- Some networks may require public callbacks, tokens, or channel-specific
|
||||
account setup.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Chat Apps](./chat-apps.md)
|
||||
- [Security configuration](./configuration.md#security)
|
||||
- [Pairing](./configuration.md#pairing)
|
||||
- [Runtime self-inspection](./my-tool.md)
|
||||
|
||||
+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:
|
||||
|
||||
|
||||
@@ -13,6 +13,21 @@ For setup and runtime failures, follow the diagnosis order in [`troubleshooting.
|
||||
> [!NOTE]
|
||||
> If your config file is older than the current schema, you can refresh it without overwriting your existing values: run `nanobot onboard`, then answer `N` when asked whether to overwrite the config. nanobot will merge in missing default fields and keep your current settings.
|
||||
|
||||
## Configuration Guides
|
||||
|
||||
This page is the complete configuration reference. For task-oriented setup, use
|
||||
the focused guides first and come back here for exact fields and defaults.
|
||||
|
||||
| Task | Guide |
|
||||
|---|---|
|
||||
| Add MCP tools | [`guides/configure-mcp-tools.md`](./guides/configure-mcp-tools.md) |
|
||||
| Enable web search and web fetch | [`guides/configure-web-search.md`](./guides/configure-web-search.md) |
|
||||
| Configure model fallback | [`guides/configure-model-fallback.md`](./guides/configure-model-fallback.md) |
|
||||
| Add an OpenAI-compatible provider | [`guides/configure-openai-compatible-provider.md`](./guides/configure-openai-compatible-provider.md) |
|
||||
| Add Langfuse observability | [`guides/configure-langfuse-observability.md`](./guides/configure-langfuse-observability.md) |
|
||||
| Secure a local AI agent | [`guides/secure-local-ai-agent.md`](./guides/secure-local-ai-agent.md) |
|
||||
| Deploy the gateway | [`guides/deploy-nanobot-gateway.md`](./guides/deploy-nanobot-gateway.md) |
|
||||
|
||||
## Quick Jump
|
||||
|
||||
| Need | Section |
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+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:
|
||||
|
||||
|
||||
+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
|
||||
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
|
||||
agent activity, workspace controls, Apps, Skills, settings, and Automations in
|
||||
|
||||
Reference in New Issue
Block a user