Skip to main content
Every time you wire a chat to an agent, you answer one question: should this conversation share anything with the others? NanoClaw gives you four levels, built from two dials in the entity model — which agent group the wiring points at, and the wiring’s session_mode. From most to least isolated they run: separate agent groups, then within one group per-thread, shared, and finally agent-shared. The walkthrough below starts at the group boundary — the strongest split — and then takes the three session modes.

​
Separate agent groups — nothing shared

Each agent group is its own world: a workspace folder under groups/<folder>/, its own per-group standing instructions (instructions.prepend.md) and durable memory (the memory/ tree), its own composed CLAUDE.md, its own container config (packages, mounts, model, skills), and its own Agent Vault credential scope — the OneCLI agent identifier is the agent group id, so secrets granted to one group never reach another. Sessions of different groups share only the host and the read-only pieces every container gets: the shared base instructions (container/CLAUDE.md, inlined by the host into each composed project document) plus the agent-runner source and skills. Choose this when:
  • Different people. A family chat and a client channel should not be one agent — a prompt-injected message in one must have nothing to exfiltrate from the other.
  • Different trust domains. An agent with a mounted code repo and deploy credentials versus an agent that talks to strangers in a public channel.
  • Different jobs. A research agent and a home-automation agent want different packages, models, and instructions anyway.

​
One agent group, a session per chat — shared

session_mode: 'shared' gives each wired chat its own session: its own conversation history, its own session folder and databases, its own container while running. The provider normally resumes only that session’s conversation, but the agent can explicitly retrieve other sessions’ transcripts within its own group through ncl sessions history. Use this for separate conversation flows; use separate agent groups when the audiences must not access each other’s context.
Separate sessions are not a confidentiality boundary within an agent group: both cross-session history retrieval and a shared filesystem are available. Every session of an agent group mounts the same group folder read-write at /workspace/agent — working files, instructions.prepend.md, and the memory/ tree included. A file the agent saves while talking in chat A is readable (and mentionable) while talking in chat B, and a memory note written in one conversation shapes all of them. If the people in one chat must never see artifacts from another, separate sessions are not enough — use separate agent groups.

​
A session per thread — per-thread

The same idea at finer grain: one session per (chat, thread), so each Discord or Slack thread is its own conversation. You rarely set this by hand — on thread-capable adapters the router forces per-thread in group chats regardless of a shared wiring (only agent-shared or a per-wiring threads = 0 overrides it), DM thread behavior follows the channel’s declared DM default and any threads override, and thread-less adapters like WhatsApp or Telegram collapse per-thread back to shared. The full requested-versus-effective table is in the entity model’s sessions section. The history-access and shared-filesystem caveats above apply here identically. When creating or changing a per-thread wiring, the CLI rejects explicit threads = 0 or an inherited threads-off policy on a declared adapter. Undeclared adapters retain legacy leniency when threads is unset. On a thread-capable channel whose context defaults to threads off, use --threads true alongside --session-mode per-thread.

​
One conversation everywhere — agent-shared

session_mode: 'agent-shared' is the deliberate opposite of isolation: every messaging group wired with this mode joins the agent group’s single session. Mention the agent on Slack, continue on Discord, and it’s the same conversation with the same context. Use it when the chats are really one stream — your own DMs across three platforms, or a GitHub webhook channel plus the Slack channel where you discuss it. Don’t use it across chats with different audiences: everyone in every wired chat is effectively in one room.

​
Choosing a level

Decision tree over three questions landing on four isolation levels, ordered most to least isolated: separate agent groups, per-thread, shared, agent-shared; the three session modes share the same agent workspace files Decision tree over three questions landing on four isolation levels, ordered most to least isolated: separate agent groups, per-thread, shared, agent-shared; the three session modes share the same agent workspace files When in doubt, start more isolated. Merging two agent groups later means hand-carrying files and memory; splitting one is just creating a new group.

​
Configuring each level

The conversational route is the /manage-channels skill — it asks exactly this isolation question when you wire a channel and picks the flags for you. With the ncl CLI:
--session-mode is updatable (ncl wirings update --id <id> --session-mode ...), but it only changes how future messages find a session — existing sessions keep their history where it is.

​
What no level isolates

Session and agent-group boundaries separate agents from each other, not from the world:
  • The container boundary is what stands between an agent and the host — see container lifecycle for what’s mounted where and why.
  • Network egress and additional mounts are per-group container config and open by default beyond the proxy — lock them down in hardening.
  • Shared base instructions — the host inlines the shared base into each provider’s composed project document; Claude uses container/CLAUDE.md, while Codex uses container/AGENTS.md. Changes to a base reach groups using that provider on their next spawn. Per-group instructions belong in that group’s instructions.prepend.md.
Last modified on September 4, 2026