Per-user agent isolation: give every Feishu DM sender their own workspace, bootstrap files, and conversation history.

Per-user agent isolation (Dynamic Agent Creation)

Enable dynamicAgentCreation to automatically create isolated agent instances for each DM user. Each user gets their own:

This is essential for public bots where you want each user to have their own private AI assistant experience.

Dynamic bindings include the normalized Feishu accountId, so default and named accounts route each sender to the correct dynamic agent.

If a named account created an unscoped dynamic agent on an older release, that legacy agent still counts toward maxAgents. Confirm that it is not used by the default account before removing it, or temporarily increase maxAgents; Apus cannot safely infer which account owns ambiguous legacy state.

Quick setup

{
  channels: {
    feishu: {
      dmPolicy: "open",
      allowFrom: ["*"],
      dynamicAgentCreation: {
        enabled: true,
        workspaceTemplate: "~/.apus/workspace-{agentId}",
        agentDirTemplate: "~/.apus/agents/{agentId}/agent",
      },
    },
  },
  session: {
    // Critical: makes each user's DM their "main session"
    // Automatically loads USER.md / SOUL.md / MEMORY.md
    // For stronger isolation, use "per-channel-peer" instead
    dmScope: "main",
  },
}

How it works

When a new user sends their first DM:

  1. The channel generates a unique agentId: feishu-{user_open_id} for the default account, or a bounded account-prefixed identity digest for a named account
  2. Creates a new workspace at workspaceTemplate path
  3. Registers the agent and creates a binding for this user
  4. The workspace helper ensures bootstrap files (AGENTS.md, SOUL.md, USER.md, etc.) on first access
  5. Routes all future messages from this user to their dedicated agent

Configuration options

Setting Description Default
channels.feishu.dynamicAgentCreation.enabled Enable automatic per-user agent creation false
channels.feishu.dynamicAgentCreation.workspaceTemplate Path template for dynamic agent workspaces ~/.apus/workspace-{agentId}
channels.feishu.dynamicAgentCreation.agentDirTemplate Agent directory name template ~/.apus/agents/{agentId}/agent
channels.feishu.dynamicAgentCreation.maxAgents Maximum number of dynamic agents to create unlimited

Template variables:

Session scope

session.dmScope controls how direct messages are mapped to agent sessions. This is a global setting that affects all channels.

Value Behavior Best for
"main" Each user's DM maps to their agent's main session Single-user bots where you want USER.md / SOUL.md to auto-load
"per-peer" Each peer gets a separate session (regardless of channel) Isolation keyed by sender identity only
"per-channel-peer" Each (channel + user) combination gets a separate session Public multi-user bots needing stronger isolation
"per-account-channel-peer" Each (account + channel + user) combination gets a separate session Multi-account bots needing account-level session isolation

Tradeoff: Using "main" enables automatic bootstrap file loading (USER.md, SOUL.md, MEMORY.md), but means all DMs across all channels share the same session key pattern. For public multi-user bots where isolation matters more than bootstrap auto-loading, consider "per-channel-peer" and manage bootstrap files manually.

Use "per-account-channel-peer" when named Feishu accounts should keep separate sessions for the same sender. Dynamic bindings preserve the account scope.

Typical multi-user deployment

{
  channels: {
    feishu: {
      appId: "cli_xxx",
      appSecret: "xxx",
      dmPolicy: "open",
      allowFrom: ["*"],
      groupPolicy: "open",
      requireMention: true,
      dynamicAgentCreation: {
        enabled: true,
        workspaceTemplate: "~/.apus/workspace-{agentId}",
        agentDirTemplate: "~/.apus/agents/{agentId}/agent",
      },
    },
  },
  session: {
    // Choose dmScope based on your isolation needs:
    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation
    dmScope: "main",
  },
  bindings: [], // Empty - dynamic agents auto-bind
}

Verification

Check gateway logs to confirm dynamic creation is working:

feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxx
  workspace: /home/user/.apus/workspace-feishu-ou_xxxxxx
  agentDir: /home/user/.apus/agents/feishu-ou_xxxxxx/agent

List all created workspaces:

ls -la ~/.apus/workspace-*

Notes