---
summary: "Multi-koi routing: isolated kois, channel accounts, and bindings"
title: Multi-Koi Routing
read_when: "You want multiple isolated kois (workspaces + auth) in one gateway process."
status: active
---

# Multi-Koi Routing

Goal: multiple _isolated_ kois (separate workspace + `koiDir` + sessions), plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an koi via bindings.

## What is “one koi”?

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

- **Workspace** (files, KOIS.md/SOUL.md/USER.md, local notes, persona rules).
- **State directory** (`koiDir`) for auth profiles, model registry, and per-koi config.
- **Session store** (chat history + routing state) under `~/.SKYKOI/koi/<koiId>/sessions`.

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

```
~/.SKYKOI/koi/<koiId>/koi/auth-profiles.json
```

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

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

The Gateway can host **one koi** (default) or **many kois** side-by-side.

**Workspace note:** each koi’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: `~/.SKYKOI/SKYKOI.json` (or `SKYKOI_CONFIG_PATH`)
- State dir: `~/.SKYKOI` (or `SKYKOI_STATE_DIR`)
- Workspace: `~/.SKYKOI/workspace` (or `~/.SKYKOI/workspace-<koiId>`)
- Koi dir: `~/.SKYKOI/koi/<koiId>/koi` (or `kois.list[].koiDir`)
- Sessions: `~/.SKYKOI/koi/<koiId>/sessions`

### Single-koi mode (default)

If you do nothing, SKYKOI runs a single koi:

- `koiId` defaults to **`main`**.
- Sessions are keyed as `koi:main:<mainKey>`.
- Workspace defaults to `~/.SKYKOI/workspace` (or `~/.SKYKOI/workspace-<profile>` when `SKYKOI_PROFILE` is set).
- State defaults to `~/.SKYKOI/koi/main/koi`.

## Koi helper

Use the koi wizard to add a new isolated koi:

```bash
SKYKOI kois add work
```

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

Verify with:

```bash
SKYKOI kois list --bindings
```

## Multiple kois = multiple people, multiple personalities

With **multiple kois**, each `koiId` becomes a **fully isolated persona**:

- **Different phone numbers/accounts** (per channel `accountId`).
- **Different personalities** (per-koi workspace files like `KOIS.md` and `SOUL.md`).
- **Separate auth + sessions** (no cross-talk unless explicitly enabled).

This lets **multiple people** share one Gateway server while keeping their Koi “brains” and data isolated.

## One WhatsApp number, multiple people (DM split)

You can route **different WhatsApp DMs** to different kois while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: "dm"`. Replies still come from the same WhatsApp number (no per‑koi sender identity).

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

Example:

```json5
{
  kois: {
    list: [
      { id: "alex", workspace: "~/.SKYKOI/workspace-alex" },
      { id: "mia", workspace: "~/.SKYKOI/workspace-mia" },
    ],
  },
  bindings: [
    { koiId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
    { koiId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}
```

Notes:

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

## Routing rules (how messages pick an koi)

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

1. `peer` match (exact DM/group/channel id)
2. `guildId` (Discord)
3. `teamId` (Slack)
4. `accountId` match for a channel
5. channel-level match (`accountId: "*"`)
6. fallback to default koi (`kois.list[].default`, else first list entry, default: `main`)

## Multiple accounts / phone numbers

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

## Concepts

- `koiId`: one “brain” (workspace, per-koi auth, per-koi session store).
- `accountId`: one channel account instance (e.g. WhatsApp account `"personal"` vs `"biz"`).
- `binding`: routes inbound messages to an `koiId` by `(channel, accountId, peer)` and optionally guild/team ids.
- Direct chats collapse to `koi:<koiId>:<mainKey>` (per-koi “main”; `session.mainKey`).

## Example: two WhatsApps → two kois

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

```js
{
  kois: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/.SKYKOI/workspace-home",
        koiDir: "~/.SKYKOI/koi/home/koi",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/.SKYKOI/workspace-work",
        koiDir: "~/.SKYKOI/koi/work/koi",
      },
    ],
  },

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

    // Optional per-peer override (example: send a specific group to work koi).
    {
      koiId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

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

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // Optional override. Default: ~/.SKYKOI/credentials/whatsapp/personal
          // authDir: "~/.SKYKOI/credentials/whatsapp/personal",
        },
        biz: {
          // Optional override. Default: ~/.SKYKOI/credentials/whatsapp/biz
          // authDir: "~/.SKYKOI/credentials/whatsapp/biz",
        },
      },
    },
  },
}
```

## Example: WhatsApp daily chat + Telegram deep work

Split by channel: route WhatsApp to a fast everyday koi and Telegram to an Opus koi.

```json5
{
  kois: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.SKYKOI/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.SKYKOI/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { koiId: "chat", match: { channel: "whatsapp" } },
    { koiId: "opus", match: { channel: "telegram" } },
  ],
}
```

Notes:

- If you have multiple accounts for a channel, add `accountId` to the binding (for example `{ channel: "whatsapp", 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 WhatsApp on the fast koi, but route one DM to Opus:

```json5
{
  kois: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.SKYKOI/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.SKYKOI/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { koiId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
    { koiId: "chat", match: { channel: "whatsapp" } },
  ],
}
```

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

## Family koi bound to a WhatsApp group

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

```json5
{
  kois: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/.SKYKOI/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
        },
        sandbox: {
          mode: "all",
          scope: "koi",
        },
        tools: {
          allow: [
            "exec",
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
        },
      },
    ],
  },
  bindings: [
    {
      koiId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" },
      },
    },
  ],
}
```

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 `kois.list[].groupChat.mentionPatterns` and keep
  group allowlists enabled for the channel.

## Per-Koi Sandbox and Tool Configuration

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

```js
{
  kois: {
    list: [
      {
        id: "personal",
        workspace: "~/.SKYKOI/workspace-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal koi
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/.SKYKOI/workspace-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "koi",  // One container per koi
          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-koi `sandbox.docker.*` overrides are ignored when the resolved scope is `"shared"`.

**Benefits:**

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

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

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