--- 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//sessions`. Auth profiles are **per-koi**. Each koi reads from its own: ``` ~/.SKYKOI/koi//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-`) - Koi dir: `~/.SKYKOI/koi//koi` (or `kois.list[].koiDir`) - Sessions: `~/.SKYKOI/koi//sessions` ### Single-koi mode (default) If you do nothing, SKYKOI runs a single koi: - `koiId` defaults to **`main`**. - Sessions are keyed as `koi:main:`. - Workspace defaults to `~/.SKYKOI/workspace` (or `~/.SKYKOI/workspace-` 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::` (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.