Multi-Boo

A multi-agent dashboard built on top of nanobot. Multiboo adds clearer namespace layout, a shared runtime registry, a read-only control view, and a layer of safety guardrails to keep the whole ghost office tidy. Built for personal use, shared with everyone, and open to stars and improvements.

_{English | 中文}

Demo

Note

This demo video includes audio. Please turn on sound for the best experience.

multiboo-demo.mp4

Getting Started

1. Install from source

Multiboo is a standard Python project that supports editable installation.

python -m venv .venv
source .venv/bin/activate
pip install -e .

2. Create the default agent

multiboo onboard

This creates the default agent config and workspace at:

• ~/.multiboo/.multiboo/config.json
• ~/.multiboo/.multiboo/workspace/

3. Create a named agent

multiboo onboard --name jarvis

This creates a second isolated agent at:

• ~/.multiboo/.multiboo_agents/jarvis/config.json
• ~/.multiboo/.multiboo_agents/jarvis/workspace/

If you only need one personal default assistant, use the default agent. If you want separate roles, separate workspaces, separate channel configs, or different long-running runtimes on the same machine, use named agents.

4. Configure the model and provider

Edit the config file for the agent you want to run.

For the default agent:

vim ~/.multiboo/.multiboo/config.json

For a named agent:

vim ~/.multiboo/.multiboo_agents/jarvis/config.json

A direct and deterministic example is to configure MiniMax explicitly:

{
  "agents": {
    "defaults": {
      "model": "MiniMax-M2.5",
      "provider": "minimax"
    }
  },
  "providers": {
    "minimax": {
      "apiKey": "sk-cp-xxxxxxxxxx",
      "apiBase": "https://api.minimaxi.com/v1",
      "extraHeaders": null
    }
  }
}

After that, you can keep extending the same config file with channel, MCP, web search, or execution-related settings. An MCP configuration example is shown below:

{
  "tools": {
    "mcpServers": {
      "MiniMax": {
        "command": "uvx",
        "args": ["minimax-coding-plan-mcp", "-y"],
        "env": {
          "MINIMAX_API_KEY": "sk-cp-xxxxxxxxxx",
          "MINIMAX_API_HOST": "https://api.minimaxi.com"
        }
      }
    }
  }
}

5. Launch the CLI agent

For the default agent:

multiboo agent

For a named agent:

multiboo agent --name jarvis

Single-message mode:

multiboo agent --name jarvis -m "Summarize the workspace."

6. Launch the long-running gateway

For the default agent:

multiboo gateway

For a named agent:

multiboo gateway --name jarvis

If you need channels, heartbeat, cron-triggered tasks, and stable runtime visibility, you will usually want to run the gateway.

7. Launch the Dashboard backend

multiboo server

By default, the Dashboard listens on:

• http://127.0.0.1:28991

The backend remains read-only and exposes a status API at:

• http://127.0.0.1:28991/multiboo/api/status

8. Check status from the CLI

For the default agent:

multiboo status

For a named agent:

multiboo status --name jarvis

To list all running instances:

multiboo list

Alias:

multiboo ps

Command Map

Command	Purpose
multiboo onboard	Initialize the default agent namespace.
multiboo onboard --name <name>	Initialize a named agent namespace.
multiboo agent	Open the interactive CLI for the default agent.
multiboo agent --name <name>	Open the interactive CLI for a named agent.
multiboo agent -m "..."	Run one direct prompt and exit.
multiboo gateway	Start the default long-lived runtime.
multiboo gateway --name <name>	Start the long-lived runtime for a named agent.
multiboo server	Start the global Dashboard backend.
multiboo status	Show config, workspace, and runtime status for an agent namespace.
multiboo list	List all running runtime instances.
multiboo ps	Alias of multiboo list.

Workflow

The diagram below summarizes the core Multiboo workflow: initialize a default or named agent, publish runtime state to the shared registry, and observe everything from the read-only Dashboard.

Core Concepts

default agent and named agents

• Without --name, you are operating on the default agent.
• With --name jarvis, you are operating on the named agent called jarvis.
• Named agent names are validated with ^[a-z0-9_]+$.
• default is reserved and cannot be used as a named agent name.

Canonical path model

All state managed by Multiboo now lives under one outer container directory:

Purpose	Path
Default agent root	~/.multiboo/.multiboo/
Named agents root	~/.multiboo/.multiboo_agents/<name>/
Shared system root	~/.multiboo/.multiboo_system/
Registry file	~/.multiboo/.multiboo_system/registry.json

agent, gateway, and server

Command	Purpose
multiboo agent	Talk to an agent directly through the CLI, which is useful for local chat and debugging.
multiboo gateway	Run a long-lived runtime that handles channels, heartbeat, cron delivery, and runtime status exposure.
multiboo server	Run the global Dashboard backend. It is not agent-scoped, so it does not accept --name.

Workspace bootstrap files

multiboo onboard creates a starter workspace set that you can use immediately:

• AGENTS.md
• SOUL.md
• TOOLS.md
• USER.md
• HEARTBEAT.md
• memory/MEMORY.md
• memory/HISTORY.md

IDENTITY.md is optional. The current code will load it if it exists, but it is not created by default and is not required.

Practical notes on --name

• If you want the default agent, do not pass --name.
• If you need workspace isolation or role separation, use --name <name>.
• Keep the same --name across onboard, agent, gateway, and status so the namespace stays consistent.
• multiboo server is a global service, so it does not have --name.

A very common pattern looks like this:

multiboo onboard --name researcher
multiboo onboard --name operator
multiboo gateway --name researcher
multiboo gateway --name operator
multiboo server

License

This project is released under the MIT License. See LICENSE for details.