feat: multi-instance support with --config parameter

[shenchengtsi]

🎯 Problem & Motivation

When deploying AI assistants at scale, you often need to run multiple instances with different configurations:

• Multiple teams need separate assistants with isolated knowledge bases
• Multi-tenant scenarios require different LLM models and API credentials per client
• Testing & production environments should run side-by-side without interference
• Multiple messaging platforms (e.g., different Feishu/Slack organizations) need separate connections

Currently, this requires either:

• ❌ Messy if-else logic in a single instance
• ❌ Maintaining multiple code copies (maintenance nightmare)
• ❌ Complex orchestration with Docker/K8s

✨ Solution

This PR adds native multi-instance support with complete isolation through a simple --config parameter.

Key Features

• Complete Isolation: Each instance has independent workspace, memory, sessions, cron jobs, logs, and media
• Zero Code Duplication: Single codebase serves all instances
• Minimal Changes: Only 3 core files modified (backward compatible)
• Production Ready: Simple deployment with clear data directory structure

Usage

# Main instance (default)
nanobot gateway

# Additional instances
nanobot gateway --config ~/.nanobot-team2/config.json --port 18791
nanobot gateway --config ~/.nanobot-testing/config.json --port 18792

Each instance can use:

• Different LLM models (Claude Opus vs Sonnet)
• Different API keys and providers
• Different messaging platform credentials
• Different ports and configurations

📦 Changes

Core Implementation (3 files)

1. Config Path Management (nanobot/config/loader.py)

• Added set_config_path(path: Path) function to set custom config file location
• Modified get_config_path() to return custom path if set, otherwise default ~/.nanobot/config.json
• Modified get_data_dir() to derive data directory from config file location
  • Example: ~/.nanobot-instance2/config.json → data dir is ~/.nanobot-instance2/

2. Data Path Resolution (nanobot/utils/helpers.py)

• Updated get_data_path() to use unified data directory from config loader
• Ensures all data (workspace, cron, logs, media) uses the same root directory

3. Gateway Command (nanobot/cli/commands.py)

• Added --config parameter to gateway() command
• Config path is set before any imports that use get_data_dir()
• Validates config file exists before proceeding
• Updated cron store path to use get_data_dir() instead of config.workspace_path

🏗️ Architecture

Config: ~/.nanobot-instance2/config.json
Data Dir: ~/.nanobot-instance2/
├── workspace/     # Skills, memory, sessions
├── cron/          # Scheduled tasks
├── logs/          # Log files
└── media/         # Uploaded files

Data directory is automatically derived from config file location - no manual path configuration needed.

Isolation Table

Component	Location	Isolation
Config file	<data_dir>/config.json	✅ Complete
Workspace	<data_dir>/workspace/	✅ Complete
Memory	<data_dir>/workspace/memory/	✅ Complete
Sessions	<data_dir>/workspace/sessions/	✅ Complete
Skills	<data_dir>/workspace/skills/	✅ Complete
Cron jobs	<data_dir>/cron/jobs.json	✅ Complete
Logs	<data_dir>/logs/	✅ Complete
Media	<data_dir>/media/	✅ Complete

✅ Backward Compatibility

Existing single-instance setups work without any changes. Default config path remains ~/.nanobot/config.json.

Zero Breaking Changes - Default behavior unchanged, fully backward compatible.

🎬 Real-World Use Cases

1. Multiple Teams

# Product team with Claude Opus
nanobot gateway --config ~/.nanobot-product/config.json --port 18790

# Engineering team with Claude Sonnet
nanobot gateway --config ~/.nanobot-engineering/config.json --port 18791

2. Multi-Tenant SaaS

# Client A (Feishu App 1)
nanobot gateway --config ~/.nanobot-clientA/config.json --port 18790

# Client B (Feishu App 2)
nanobot gateway --config ~/.nanobot-clientB/config.json --port 18791

3. Testing & Production

# Stable production instance
nanobot gateway --config ~/.nanobot-prod/config.json --port 18790

# Experimental testing instance
nanobot gateway --config ~/.nanobot-test/config.json --port 18791

🔍 Testing

Tested on macOS with 3 concurrent instances:

• Main instance: ~/.nanobot/ (port 18790)
• Instance 2: ~/.nanobot-zhangjuzheng/ (port 18791)
• Instance 3: ~/.nanobot-lvfang/ (port 18792)

All instances running independently with:

• Separate Feishu app connections (different App IDs)
• Independent cron jobs (no duplicate execution)
• Isolated workspace and memory
• Different AI models (claude-sonnet-4-6, claude-opus-4)

🙏 Benefits to Community

• Enterprise Deployments: Enables production multi-tenant scenarios
• Development Workflow: Test new features without affecting production
• Team Collaboration: Each team gets isolated AI assistant
• Platform Integration: Connect to multiple organizations simultaneously

This addresses a common pain point in real-world deployments while keeping nanobot's lightweight philosophy intact.

---

Related Issues: N/A (new feature)
Breaking Changes: None
Documentation: Usage examples included in PR description

[Re-bin]

Good choice! Would you like to update the README.md?

[shenchengtsi]

Good choice! Would you like to update the README.md?

Of course!Let me do it right now.

[shenchengtsi]

Good choice! Would you like to update the README.md?

Done！

[Re-bin]

Good choice! Would you like to update the README.md?

Done！

Thanks! I will review it soon :)

[shenchengtsi]

Good choice! Would you like to update the README.md?

Done！

Thanks! I will review it soon :)

Hi there,

Thank you so much for reviewing and merging this PR! I'm really glad to be able to contribute to this awesome project.

I just wanted to leave a quick note: I noticed I didn't appear in the GitHub Contributors list. After checking my local environment, I realized I made a beginner's mistake and forgot to configure my local git user.email properly before making these commits, so GitHub couldn't link them to my account.

I completely understand that since the code is already merged into the main branch, the commit history shouldn't be rewritten to fix this. However, if it's convenient, would it be possible to give me a quick mention in the next Release Notes or the README?

If not, no worries at all! I'm just happy my code is helpful. Thanks again for your time and for maintaining this project!

Best,
shenchengtsi

[winter1215]

Hello, I have a question about the multi-user architecture.

Why is multi-user support implemented using a multi-instance approach? Would it be possible to extend a single instance to support multiple users by modifying the source code?

My understanding is that this might be achievable with a database and a web layer, where each user’s messages are handled in an independent agent loop, and each workspace is isolated as well. In that case, a single instance could potentially support many users.

Would this design be feasible? @shenchengtsi

[shenchengtsi]

Hello, I have a question about the multi-user architecture.

Why is multi-user support implemented using a multi-instance approach? Would it be possible to extend a single instance to support multiple users by modifying the source code?

My understanding is that this might be achievable with a database and a web layer, where each user’s messages are handled in an independent agent loop, and each workspace is isolated as well. In that case, a single instance could potentially support many users.

Would this design be feasible? @shenchengtsi

Hi, that's a really sharp observation — your proposed architecture is genuinely the right approach for multi-user scenarios.

A database + web layer + isolated agent loops per user is exactly how a proper multi-tenant system should be designed. It scales well, manages resources efficiently, and keeps things operationally clean.

The reason nanobot currently uses a multi-instance approach comes down to its design goals: it's a lightweight personal assistant, and the multi-instance model lets each user have a completely different configuration — different models, different skills, different system prompts — with zero shared state and no database dependency. For small-scale personal or team use, it's the simplest path to full isolation.

That said, if you're building toward a product that serves many users, your instinct is exactly right. The main effort would be refactoring the current file-based workspace, cron, and session layout into a per-user data model — doable, but a meaningful undertaking.

Would love to see that explored. Happy to discuss further if you want to dig into the design! @winter1215