mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-06-15 15:24:06 +00:00
4a58b83acc
* docs: make onboarding friendlier for beginners * docs: build clearer documentation paths Maintainer edit: turn the onboarding follow-up into a layered docs structure for first-time setup, provider selection, troubleshooting, CLI reference, and source-level architecture. This keeps quick start focused while giving advanced users precise reference paths. * docs: render architecture flow with mermaid Maintainer edit: replace the ASCII architecture sketch with a GitHub-rendered Mermaid flowchart so the core runtime path is easier to scan in the PR and README docs. * docs: recommend model presets for model config Maintainer edit: make named modelPresets the primary model configuration path and expand fallback preset examples so string fallbacks are clearly preset names, not raw model IDs. * docs: document api base urls and langfuse setup Maintainer edit: explain when users need apiBase/base URL in quick start and provider docs, and add Langfuse tracing setup with troubleshooting links. * docs: use python module pip consistently Maintainer edit: keep install commands tied to the active Python interpreter by using python -m pip in the Azure optional dependency notes too. * docs: add non-technical getting started path Maintainer edit: add a wizard-first guide for users without terminal or JSON background, including a text TUI menu example and links from the main docs entrypoints. * docs: avoid hard-wrapped prose in user docs Maintainer edit: unwrap ordinary prose across user-facing documentation while preserving markdown structure, code blocks, tables, lists, and prompt/template files. * docs: keep desktop list continuations nested Maintainer edit: preserve list nesting after unwrapping prose in the desktop WebUI sync guide. * docs: add one-command installer Maintainer edit: add auditable macOS/Linux and Windows install scripts that install nanobot-ai and start the onboarding wizard, then document the commands in the main onboarding entrypoints. * docs: add installer dry run mode Maintainer edit: add --dry-run to the one-command installer scripts so users can preview Python detection, install source, pip command, and wizard behavior without changing their environment. * docs: clean installer error output Maintainer edit: make PowerShell installer failures print a concise Error: message instead of Write-Error call-site details. * docs: add provider setup cookbook Maintainer edit: add pasteable provider recipes for common hosted, local, fallback, runtime switching, and Langfuse setups, then link the cookbook from onboarding and troubleshooting entrypoints. * docs: address review feedback * docs: clarify reader paths * docs: explain terminal basics for beginners * docs: clarify wizard navigation * docs: avoid duplicate onboarding steps * docs: add setup status check * docs: explain status output * docs: remove provider recommendation wording * docs: explain status diagnostics * docs: reduce hard-wrapped guidance * docs: migrate config examples to presets * docs: clarify python command fallbacks * docs: improve installer failure recovery * docs: expand install troubleshooting * docs: cover installer download failures * docs: put stable install paths first * docs: add bundled webui quick path * docs: clarify provider-neutral setup * docs: clarify gateway setup for chat surfaces * docs: improve docs navigation paths * docs: add configuration quick jump * docs: clarify provider secret variables * chore: request PR review acknowledgement Empty commit: please read the PR review comments and reply on the PR to confirm that you have received them. This commit intentionally changes no files; it exists only to notify the remote Codex run so it can end its active goal. * docs: add README start here guide * docs: avoid provider recommendation wording * docs: guide next steps after first reply * docs: explain merging JSON snippets * docs: add CLI command chooser * docs: add configuration task map * docs: add deployment readiness guide * docs: simplify WebUI entry paths * docs: add provider recipe chooser * docs: fix provider factual references Update OpenRouter and LongCat model examples, align Bedrock guidance, and make fallback snippets schema-valid. Also correct group policy wording and image-generation provider lists to match the current code. * fix: keep PowerShell installer from closing caller shell * docs: mention self-guided configuration
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# Multiple Instances
|
|
|
|
Run multiple nanobot instances simultaneously with separate configs and runtime data. Use `--config` as the main entrypoint. Optionally pass `--workspace` during `onboard` when you want to initialize or update the saved workspace for a specific instance.
|
|
|
|
## Quick Start
|
|
|
|
If you want each instance to have its own dedicated workspace from the start, pass both `--config` and `--workspace` during onboarding.
|
|
|
|
**Initialize instances:**
|
|
|
|
```bash
|
|
# Create separate instance configs and workspaces
|
|
nanobot onboard --config ~/.nanobot-telegram/config.json --workspace ~/.nanobot-telegram/workspace
|
|
nanobot onboard --config ~/.nanobot-discord/config.json --workspace ~/.nanobot-discord/workspace
|
|
nanobot onboard --config ~/.nanobot-feishu/config.json --workspace ~/.nanobot-feishu/workspace
|
|
```
|
|
|
|
**Configure each instance:**
|
|
|
|
Edit `~/.nanobot-telegram/config.json`, `~/.nanobot-discord/config.json`, etc. with different channel settings. The workspace you passed during `onboard` is saved into each config as that instance's default workspace.
|
|
|
|
**Run instances:**
|
|
|
|
```bash
|
|
# Instance A - Telegram bot
|
|
nanobot gateway --config ~/.nanobot-telegram/config.json
|
|
|
|
# Instance B - Discord bot
|
|
nanobot gateway --config ~/.nanobot-discord/config.json
|
|
|
|
# Instance C - Feishu bot with custom port
|
|
nanobot gateway --config ~/.nanobot-feishu/config.json --port 18792
|
|
```
|
|
|
|
## Path Resolution
|
|
|
|
When using `--config`, nanobot derives its runtime data directory from the config file location. The workspace still comes from `agents.defaults.workspace` unless you override it with `--workspace`.
|
|
|
|
To open a CLI session against one of these instances locally:
|
|
|
|
```bash
|
|
nanobot agent -c ~/.nanobot-telegram/config.json -m "Hello from Telegram instance"
|
|
nanobot agent -c ~/.nanobot-discord/config.json -m "Hello from Discord instance"
|
|
|
|
# Optional one-off workspace override
|
|
nanobot agent -c ~/.nanobot-telegram/config.json -w /tmp/nanobot-telegram-test
|
|
```
|
|
|
|
> `nanobot agent` starts a local CLI agent using the selected workspace/config. It does not attach to or proxy through an already running `nanobot gateway` process.
|
|
|
|
| Component | Resolved From | Example |
|
|
|-----------|---------------|---------|
|
|
| **Config** | `--config` path | `~/.nanobot-A/config.json` |
|
|
| **Workspace** | `--workspace` or config | `~/.nanobot-A/workspace/` |
|
|
| **Cron Jobs** | workspace directory | `~/.nanobot-A/workspace/cron/` |
|
|
| **Media / runtime state** | config directory | `~/.nanobot-A/media/` |
|
|
|
|
## How It Works
|
|
|
|
- `--config` selects which config file to load
|
|
- By default, the workspace comes from `agents.defaults.workspace` in that config
|
|
- If you pass `--workspace`, it overrides the workspace from the config file
|
|
|
|
## Minimal Setup
|
|
|
|
1. Copy your base config into a new instance directory.
|
|
2. Set a different `agents.defaults.workspace` for that instance.
|
|
3. Start the instance with `--config`.
|
|
|
|
Example config fragment:
|
|
|
|
```json
|
|
{
|
|
"agents": {
|
|
"defaults": {
|
|
"workspace": "~/.nanobot-telegram/workspace"
|
|
}
|
|
},
|
|
"channels": {
|
|
"telegram": {
|
|
"enabled": true,
|
|
"token": "YOUR_TELEGRAM_BOT_TOKEN"
|
|
}
|
|
},
|
|
"gateway": {
|
|
"host": "127.0.0.1",
|
|
"port": 18790
|
|
}
|
|
}
|
|
```
|
|
|
|
The copied base config can keep using the same `modelPresets` and `agents.defaults.modelPreset`. If this instance needs a different model, add another preset and set `agents.defaults.modelPreset` to that preset name.
|
|
|
|
Start separate instances:
|
|
|
|
```bash
|
|
nanobot gateway --config ~/.nanobot-telegram/config.json
|
|
nanobot gateway --config ~/.nanobot-discord/config.json
|
|
```
|
|
|
|
Each gateway instance also exposes a lightweight HTTP health endpoint on `gateway.host:gateway.port`. By default, the gateway binds to `127.0.0.1`, so the endpoint stays local unless you explicitly set `gateway.host` to a public or LAN-facing address.
|
|
|
|
- `GET /health` returns `{"status":"ok"}`
|
|
- Other paths return `404`
|
|
|
|
Override workspace for one-off runs when needed:
|
|
|
|
```bash
|
|
nanobot gateway --config ~/.nanobot-telegram/config.json --workspace /tmp/nanobot-telegram-test
|
|
```
|
|
|
|
## Common Use Cases
|
|
|
|
- Run separate bots for Telegram, Discord, Feishu, and other platforms
|
|
- Keep testing and production instances isolated
|
|
- Use different models or providers for different teams
|
|
- Serve multiple tenants with separate configs and runtime data
|
|
|
|
## Notes
|
|
|
|
- Each instance must use a different port if they run at the same time
|
|
- Use a different workspace per instance if you want isolated memory, sessions, and skills
|
|
- `--workspace` overrides the workspace defined in the config file
|
|
- Cron jobs are stored in the active workspace; runtime media/state is derived from the config directory
|