> ## Documentation Index
> Fetch the complete documentation index at: https://aiwithapex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent Routing

# Multi-Agent Routing

Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts in one running Gateway. Inbound is routed to an agent via bindings.

## What is "one agent"?

An **agent** is a fully scoped brain with its own:

* **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules).
* **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.
* **Session store** (chat history + routing state) under `~/.crocbot/agents/<agentId>/sessions`.

Auth profiles are **per-agent**. Each agent reads from its own:

```
~/.crocbot/agents/<agentId>/agent/auth-profiles.json
```

Main agent credentials are **not** shared automatically. Never reuse `agentDir`
across agents (it causes auth/session collisions). If you want to share creds,
copy `auth-profiles.json` into the other agent's `agentDir`.

Skills are per-agent via each workspace's `skills/` folder, with shared skills
available from `~/.crocbot/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).

The Gateway can host **one agent** (default) or **many agents** side-by-side.

**Workspace note:** each agent's workspace is the **default cwd**, not a hard
sandbox. Relative paths resolve inside the workspace, but absolute paths can
reach other host locations unless sandboxing is enabled. See
[Sandboxing](/gateway/sandboxing).

## Paths (quick map)

* Config: `~/.crocbot/crocbot.json` (or `CROCBOT_CONFIG_PATH`)
* State dir: `~/.crocbot` (or `CROCBOT_STATE_DIR`)
* Workspace: `~/croc` (or `~/croc-<agentId>`)
* Agent dir: `~/.crocbot/agents/<agentId>/agent` (or `agents.list[].agentDir`)
* Sessions: `~/.crocbot/agents/<agentId>/sessions`

### Single-agent mode (default)

If you do nothing, crocbot runs a single agent:

* `agentId` defaults to **`main`**.
* Sessions are keyed as `agent:main:<mainKey>`.
* Workspace defaults to `~/croc` (or `~/croc-<profile>` when `CROCBOT_PROFILE` is set).
* State defaults to `~/.crocbot/agents/main/agent`.

## Agent helper

Use the agent wizard to add a new isolated agent:

```bash theme={null}
crocbot agents add work
```

Then add `bindings` (or let the wizard do it) to route inbound messages.

Verify with:

```bash theme={null}
crocbot agents list --bindings
```

## Multiple agents = multiple people, multiple personalities

With **multiple agents**, each `agentId` becomes a **fully isolated persona**:

* **Different bot tokens/accounts** (per channel `accountId`).
* **Different personalities** (per-agent workspace files like `AGENTS.md` and `SOUL.md`).
* **Separate auth + sessions** (no cross-talk unless explicitly enabled).

This lets **multiple people** share one Gateway server while keeping their AI "brains" and data isolated.

## One Telegram bot, multiple people (DM split)

You can route **different Telegram DMs** to different agents while staying on **one Telegram bot**. Match on sender user ID with `peer.kind: "dm"`. Replies still come from the same bot (no per-agent sender identity).

Important detail: direct chats collapse to the agent's **main session key**, so true isolation requires **one agent per person**.

Example:

```json5 theme={null}
{
  agents: {
    list: [
      { id: "alex", workspace: "~/croc-alex" },
      { id: "mia", workspace: "~/croc-mia" }
    ]
  },
  bindings: [
    { agentId: "alex", match: { channel: "telegram", peer: { kind: "dm", id: "123456789" } } },
    { agentId: "mia",  match: { channel: "telegram", peer: { kind: "dm", id: "987654321" } } }
  ],
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: ["123456789", "987654321"]
    }
  }
}
```

Notes:

* DM access control is **global per Telegram bot** (allowlist), not per agent.
* For shared groups, bind the group to one agent or use [Broadcast groups](/channels/broadcast-groups).

## Routing rules (how messages pick an agent)

Bindings are **deterministic** and **most-specific wins**:

1. `peer` match (exact DM/group/channel id)
2. `accountId` match for a channel
3. channel-level match (`accountId: "*"`)
4. fallback to default agent (`agents.list[].default`, else first list entry, default: `main`)

## Multiple accounts / bot tokens

Channels that support **multiple accounts** (e.g. multiple Telegram bots) use `accountId` to identify
each login. Each `accountId` can be routed to a different agent, so one server can host
multiple bots without mixing sessions.

## Concepts

* `agentId`: one "brain" (workspace, per-agent auth, per-agent session store).
* `accountId`: one channel account instance (e.g. Telegram bot `"personal"` vs `"work"`).
* `binding`: routes inbound messages to an `agentId` by `(channel, accountId, peer)`.
* Direct chats collapse to `agent:<agentId>:<mainKey>` (per-agent "main"; `session.mainKey`).

## Example: two Telegram bots -> two agents

`~/.crocbot/crocbot.json` (JSON5):

```js theme={null}
{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/croc-home",
        agentDir: "~/.crocbot/agents/home/agent",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/croc-work",
        agentDir: "~/.crocbot/agents/work/agent",
      },
    ],
  },

  // Deterministic routing: first match wins (most-specific first).
  bindings: [
    { agentId: "home", match: { channel: "telegram", accountId: "personal" } },
    { agentId: "work", match: { channel: "telegram", accountId: "biz" } },

    // Optional per-peer override (example: send a specific group to work agent).
    {
      agentId: "work",
      match: {
        channel: "telegram",
        accountId: "personal",
        peer: { kind: "group", id: "-1001234567890" },
      },
    },
  ],

  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    telegram: {
      accounts: {
        personal: {
          // Bot token for personal bot
        },
        biz: {
          // Bot token for work bot
        },
      },
    },
  },
}
```

## Example: Telegram fast chat + Telegram deep work

Split by account: route one Telegram bot to a fast everyday agent and another to an Opus agent.

```json5 theme={null}
{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/croc-chat",
        model: "anthropic/claude-sonnet-4-5"
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/croc-opus",
        model: "anthropic/claude-opus-4-5"
      }
    ]
  },
  bindings: [
    { agentId: "chat", match: { channel: "telegram", accountId: "fast" } },
    { agentId: "opus", match: { channel: "telegram", accountId: "deep" } }
  ]
}
```

Notes:

* If you have multiple accounts for a channel, add `accountId` to the binding (for example `{ channel: "telegram", accountId: "personal" }`).
* To route a single DM/group to Opus while keeping the rest on chat, add a `match.peer` binding for that peer; peer matches always win over channel-wide rules.

## Example: same channel, one peer to Opus

Keep Telegram on the fast agent, but route one DM to Opus:

```json5 theme={null}
{
  agents: {
    list: [
      { id: "chat", name: "Everyday", workspace: "~/croc-chat", model: "anthropic/claude-sonnet-4-5" },
      { id: "opus", name: "Deep Work", workspace: "~/croc-opus", model: "anthropic/claude-opus-4-5" }
    ]
  },
  bindings: [
    { agentId: "opus", match: { channel: "telegram", peer: { kind: "dm", id: "123456789" } } },
    { agentId: "chat", match: { channel: "telegram" } }
  ]
}
```

Peer bindings always win, so keep them above the channel-wide rule.

## Family agent bound to a Telegram group

Bind a dedicated family agent to a single Telegram group, with mention gating
and a tighter tool policy:

```json5 theme={null}
{
  agents: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/croc-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot", "@Family Bot"]
        },
        sandbox: {
          mode: "all",
          scope: "agent"
        },
        tools: {
          allow: ["exec", "read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
          deny: ["write", "edit", "apply_patch", "browser", "nodes", "cron"]
        }
      }
    ]
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "telegram",
        peer: { kind: "group", id: "-1001234567890" }
      }
    }
  ]
}
```

Notes:

* Tool allow/deny lists are **tools**, not skills. If a skill needs to run a
  binary, ensure `exec` is allowed and the binary exists in the sandbox.
* For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep
  group allowlists enabled for the channel.

## Per-Agent Sandbox and Tool Configuration

Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:

```js theme={null}
{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/croc-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/croc-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "agent",  // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
        },
      },
    ],
  },
}
```

Note: `setupCommand` lives under `sandbox.docker` and runs once on container creation.
Per-agent `sandbox.docker.*` overrides are ignored when the resolved scope is `"shared"`.

**Benefits:**

* **Security isolation**: Restrict tools for untrusted agents
* **Resource control**: Sandbox specific agents while keeping others on host
* **Flexible policies**: Different permissions per agent

Note: `tools.elevated` is **global** and sender-based; it is not configurable per agent.
If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.

See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for detailed examples.