| 1 | # Multiple Instances |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ## Quick Start |
| 6 | |
| 7 | If you want each instance to have its own dedicated workspace from the start, pass both `--config` and `--workspace` during onboarding. |
| 8 | |
| 9 | **Initialize instances:** |
| 10 | |
| 11 | ```bash |
| 12 | # Create separate instance configs and workspaces |
| 13 | nanobot onboard --config ~/.nanobot-telegram/config.json --workspace ~/.nanobot-telegram/workspace |
| 14 | nanobot onboard --config ~/.nanobot-discord/config.json --workspace ~/.nanobot-discord/workspace |
| 15 | nanobot onboard --config ~/.nanobot-feishu/config.json --workspace ~/.nanobot-feishu/workspace |
| 16 | ``` |
| 17 | |
| 18 | **Configure each instance:** |
| 19 | |
| 20 | 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. |
| 21 | |
| 22 | **Run instances:** |
| 23 | |
| 24 | ```bash |
| 25 | # Instance A - Telegram bot |
| 26 | nanobot gateway --config ~/.nanobot-telegram/config.json |
| 27 | |
| 28 | # Instance B - Discord bot |
| 29 | nanobot gateway --config ~/.nanobot-discord/config.json |
| 30 | |
| 31 | # Instance C - Feishu bot with custom port |
| 32 | nanobot gateway --config ~/.nanobot-feishu/config.json --port 18792 |
| 33 | ``` |
| 34 | |
| 35 | ## Path Resolution |
| 36 | |
| 37 | 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`. |
| 38 | |
| 39 | To open a CLI session against one of these instances locally: |
| 40 | |
| 41 | ```bash |
| 42 | nanobot agent -c ~/.nanobot-telegram/config.json -m "Hello from Telegram instance" |
| 43 | nanobot agent -c ~/.nanobot-discord/config.json -m "Hello from Discord instance" |
| 44 | |
| 45 | # Optional one-off workspace override |
| 46 | nanobot agent -c ~/.nanobot-telegram/config.json -w /tmp/nanobot-telegram-test |
| 47 | ``` |
| 48 | |
| 49 | > `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. |
| 50 | |
| 51 | | Component | Resolved From | Example | |
| 52 | |-----------|---------------|---------| |
| 53 | | **Config** | `--config` path | `~/.nanobot-A/config.json` | |
| 54 | | **Workspace** | `--workspace` or config | `~/.nanobot-A/workspace/` | |
| 55 | | **Cron Jobs** | config directory | `~/.nanobot-A/cron/` | |
| 56 | | **Media / runtime state** | config directory | `~/.nanobot-A/media/` | |
| 57 | |
| 58 | ## How It Works |
| 59 | |
| 60 | - `--config` selects which config file to load |
| 61 | - By default, the workspace comes from `agents.defaults.workspace` in that config |
| 62 | - If you pass `--workspace`, it overrides the workspace from the config file |
| 63 | |
| 64 | ## Minimal Setup |
| 65 | |
| 66 | 1. Copy your base config into a new instance directory. |
| 67 | 2. Set a different `agents.defaults.workspace` for that instance. |
| 68 | 3. Start the instance with `--config`. |
| 69 | |
| 70 | Example config: |
| 71 | |
| 72 | ```json |
| 73 | { |
| 74 | "agents": { |
| 75 | "defaults": { |
| 76 | "workspace": "~/.nanobot-telegram/workspace", |
| 77 | "model": "anthropic/claude-sonnet-4-6" |
| 78 | } |
| 79 | }, |
| 80 | "channels": { |
| 81 | "telegram": { |
| 82 | "enabled": true, |
| 83 | "token": "YOUR_TELEGRAM_BOT_TOKEN" |
| 84 | } |
| 85 | }, |
| 86 | "gateway": { |
| 87 | "host": "127.0.0.1", |
| 88 | "port": 18790 |
| 89 | } |
| 90 | } |
| 91 | ``` |
| 92 | |
| 93 | Start separate instances: |
| 94 | |
| 95 | ```bash |
| 96 | nanobot gateway --config ~/.nanobot-telegram/config.json |
| 97 | nanobot gateway --config ~/.nanobot-discord/config.json |
| 98 | ``` |
| 99 | |
| 100 | Each gateway instance also exposes a lightweight HTTP health endpoint on |
| 101 | `gateway.host:gateway.port`. By default, the gateway binds to `127.0.0.1`, |
| 102 | so the endpoint stays local unless you explicitly set `gateway.host` to a |
| 103 | public or LAN-facing address. |
| 104 | |
| 105 | - `GET /health` returns `{"status":"ok"}` |
| 106 | - Other paths return `404` |
| 107 | |
| 108 | Override workspace for one-off runs when needed: |
| 109 | |
| 110 | ```bash |
| 111 | nanobot gateway --config ~/.nanobot-telegram/config.json --workspace /tmp/nanobot-telegram-test |
| 112 | ``` |
| 113 | |
| 114 | ## Common Use Cases |
| 115 | |
| 116 | - Run separate bots for Telegram, Discord, Feishu, and other platforms |
| 117 | - Keep testing and production instances isolated |
| 118 | - Use different models or providers for different teams |
| 119 | - Serve multiple tenants with separate configs and runtime data |
| 120 | |
| 121 | ## Notes |
| 122 | |
| 123 | - Each instance must use a different port if they run at the same time |
| 124 | - Use a different workspace per instance if you want isolated memory, sessions, and skills |
| 125 | - `--workspace` overrides the workspace defined in the config file |
| 126 | - Cron jobs and runtime media/state are derived from the config directory |
| 127 |