Hosting The Claude Agent SDK With Multi-Tenant Isolation

TL;DR

Official Agent SDK hosting documentation describes multi-tenant isolation when one container serves multiple tenants: disable filesystem settings with settingSources: [], set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, point CLAUDE_CONFIG_DIR at a tenant-only directory, pass a dedicated cwd on every query() call, and apply per-tenant egress rules at your proxy.

Prerequisites & Requirements

• {"task": "Tenant paths", "description": "Separate cwd and configDir per tenant with filesystem permissions"}
• {"task": "Proxy policy", "description": "Per-tenant outbound credentials or allowlists documented"}
• {"task": "Capacity plan", "description": "RAM sized for one subprocess per concurrent session"}
• {"task": "Storage strategy", "description": "SessionStore configured if tenants resume across restarts"}

Core Concepts Explained

Why defaults are unsafe for multi-tenant hosts

Hosting docs state that default SDK behavior reads settings and CLAUDE.md memory files from the filesystem. Shared containers without isolation can leak one tenant's context into another tenant's session.

Four SDK-level isolation options

Documentation lists: settingSources: [] (or setting_sources=[] in Python), CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, per-tenant CLAUDE_CONFIG_DIR, and explicit cwd on every query() call.

Network isolation is separate

Per-tenant egress rules (distinct outbound IPs, credentials, or domain allowlists) are applied at your proxy, not inside the SDK call alone.

Step-by-Step Implementation Guide

1. Provision per-tenant directories. Create tenantDir and configDir paths with permissions so tenants cannot read each other's files.

2. Apply SDK options on every query. TypeScript example from official docs:

for await (const message of query({
  prompt,
  options: {
    cwd: tenantDir,
    settingSources: [],
    env: {
      ...process.env,
      CLAUDE_CONFIG_DIR: configDir,
      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
    },
  },
})) {
  // handle messages
}

1. Configure outbound proxy. Route each tenant through distinct credentials or domain allowlists per hosting documentation.

2. Mirror transcripts if sessions resume. Use a SessionStore adapter when tenants expect hybrid or long-running patterns across container restarts.

3. Size concurrency. Hosting docs recommend measuring peak RSS per session; default starting point is 1 GiB RAM per agent subprocess.

4. Validate isolation. Run two tenants concurrently and confirm neither reads the other's cwd artifacts or config files.

Troubleshooting

Tenant still sees another project's CLAUDE.md

Confirm settingSources: [] and dedicated cwd; verify auto memory disabled with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Sessions lost after restart

Configure SessionStore; local transcripts under ~/.claude/projects/ do not survive container restarts by default.

Rate limits on wide subagent fanouts

Hosting docs advise breaking work into smaller batches rather than one large parallel dispatch.

Source Verification Notes

Verified against https://code.claude.com/docs/en/agent-sdk/hosting on 2026-06-16:

• Multi-tenant isolation section documents settingSources, CLAUDE_CODE_DISABLE_AUTO_MEMORY, CLAUDE_CONFIG_DIR, per-tenant cwd, and per-tenant egress at the proxy.
• Each session maps to one CLI subprocess with local transcript state by default.
• Hybrid and long-running patterns require SessionStore for transcript durability.
• Secure Deployment doc covers additional network and credential hardening.

Duplicate Check

Complements secure-deployment-for-claude-agent-sdk-applications (network and credential hardening) and external-session-storage-for-claude-agent-sdk-hosts (SessionStore). This guide focuses on the documented multi-tenant isolation options inside shared Agent SDK hosts.

References

• Hosting the Agent SDK - https://code.claude.com/docs/en/agent-sdk/hosting