<!-- source: https://deepwiki.com/qhkm/zeptoclaw/12.5-multi-tenant-configuration -->

# Multi-tenant Configuration

- docker-compose.multi-tenant.yml
- docs/MULTI-TENANT.md
- docs/MULTI_TENANT_SECURITY.md
- scripts/add-tenant.sh

## Purpose and Scope

This page describes strategies for deploying ZeptoClaw in multi-user environments. ZeptoClaw supports two primary multi-tenancy models: **Container-Per-Tenant** (High Isolation) and **SaaS Mode** (High Density). These strategies provide access control, workspace isolation, and resource management for safely serving multiple users or organizations from a single infrastructure.

For standard installation, see [Installation](/qhkm/zeptoclaw/2.1-installation). For security architecture, see [Security Architecture](/qhkm/zeptoclaw/6.1-security-architecture).

## Multi-Tenant Isolation Models

ZeptoClaw provides two distinct architectural approaches to multi-tenancy depending on the required security boundary and resource density.

### 1. Container-Per-Tenant (Recommended)

In this model, each tenant runs a completely isolated ZeptoClaw process within a Docker container. This is the most secure method as it leverages OS-level primitives (namespaces, cgroups) for isolation. ZeptoClaw's small footprint (~4MB binary, ~6MB RSS idle) allows for high density even with process isolation [docs/MULTI-TENANT.md7-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L7-L14)

### 2. SaaS Mode (Proposed Capability-Based)

This model uses a single application instance to serve multiple tenants by restricting high-risk capabilities (Shell, Filesystem) and enforcing Tenant ID scoping at the database level.

**Sources:** [docs/MULTI-TENANT.md1-17](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L1-L17) [docs/MULTI_TENANT_SECURITY.md1-36](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI_TENANT_SECURITY.md?plain=1#L1-L36)

## Architecture: Containerized Multi-Tenancy

The following diagram illustrates the "Container-Per-Tenant" architecture where a single VPS hosts multiple isolated agents.

```

```

**Container-Per-Tenant Architecture**

Each tenant instance is a standalone `zeptoclaw gateway` process [docker-compose.multi-tenant.yml60](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docker-compose.multi-tenant.yml#L60-L60) Configuration files are stored in `tenants/<name>/config.json` and mounted into the container [docker-compose.multi-tenant.yml45](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docker-compose.multi-tenant.yml#L45-L45)

**Sources:** [docs/MULTI-TENANT.md38-55](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L38-L55) [docker-compose.multi-tenant.yml18-60](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docker-compose.multi-tenant.yml#L18-L60)

## Tenant Onboarding and Management

Management of multiple tenants is handled via helper scripts that automate configuration generation and deployment.

### Automated Tenant Creation

The `add-tenant.sh` script initializes a new tenant directory with a baseline `config.json` containing default agent settings and specific credentials.

```

```

**Sources:** [scripts/add-tenant.sh1-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/scripts/add-tenant.sh#L1-L29)

### Implementation Detail: Config Generation

The script uses Python's `json.dumps` to ensure that API keys containing special characters (like `$`, ```, or `"`) are safely escaped for the JSON configuration [scripts/add-tenant.sh49-99](https://github.com/qhkm/zeptoclaw/blob/2c743d31/scripts/add-tenant.sh#L49-L99)

### Deployment Workflow

1. Initialize: Run add-tenant.sh to create tenants/<name>/config.json scripts/add-tenant.sh 101-102
2. Generate Compose: Run generate-compose.sh to build the docker-compose.multi-tenant.yml docs/MULTI-TENANT.md 168-169
3. Up: Execute docker compose -f docker-compose.multi-tenant.yml up -d docs/MULTI-TENANT.md 31

## Security and Isolation Policies

### Capability Boundaries (SaaS Mode)

For deployments where users are not fully trusted, the system distinguishes between `self_hosted` and `saas` deployment modes to prevent prompt-injection-based filesystem attacks.

**Sources:** [docs/MULTI_TENANT_SECURITY.md54-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI_TENANT_SECURITY.md?plain=1#L54-L67)

### Trust Boundary Map

In SaaS mode, the security boundary shifts from the LLM prompt to the **Tool Policy Gate**.

```

```

**SaaS Request Flow**

The `Tool Policy Gate` ensures that even if an LLM is "tricked" into requesting `rm -rf /`, the request is denied because the `shell` tool is not registered in the `saas` runtime [docs/MULTI_TENANT_SECURITY.md117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI_TENANT_SECURITY.md?plain=1#L117-L117)

**Sources:** [docs/MULTI_TENANT_SECURITY.md40-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI_TENANT_SECURITY.md?plain=1#L40-L48) [docs/MULTI_TENANT_SECURITY.md90-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI_TENANT_SECURITY.md?plain=1#L90-L101)

## Resource and Quota Management

To prevent "Noisy Neighbor" effects, multi-tenant deployments enforce strict resource limits per container.

### Docker Resource Constraints

Defaults defined in the `docker-compose.multi-tenant.yml` template using YAML anchors [docker-compose.multi-tenant.yml18-34](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docker-compose.multi-tenant.yml#L18-L34):

- Memory Limit: 128MB (Hard limit) docker-compose.multi-tenant.yml 29
- Memory Reservation: 32MB (Soft limit) docker-compose.multi-tenant.yml 32
- CPU Limit: 0.25 cores docker-compose.multi-tenant.yml 30

### Monitoring Commands

Administrators can monitor tenant resource consumption using standard Docker tools filtered by the ZeptoClaw prefix (`zc-`):

```

```

**Sources:** [docs/MULTI-TENANT.md88-115](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L88-L115)

## Swarm and Delegation in Multi-Tenancy

Each tenant can enable **Agent Swarm Delegation**, allowing a "Lead Agent" to spawn specialized sub-agents. In a multi-tenant context, this is used to further restrict sub-agents to specific tool subsets.

### Swarm Configuration Example

```

```

- max_depth : Limits delegation recursion (default: 1) docs/MULTI-TENANT.md 209
- roles : Pre-defined presets that restrict the sub-agent's available tools. If a role has an empty tools list, the sub-agent gets all tools except delegate and spawn docs/MULTI-TENANT.md 211-212

**Sources:** [docs/MULTI-TENANT.md185-212](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L185-L212) [scripts/add-tenant.sh88-93](https://github.com/qhkm/zeptoclaw/blob/2c743d31/scripts/add-tenant.sh#L88-L93)

## Backup and Recovery

Tenant data is stored in named Docker volumes. A standard backup strategy involves iterating through these volumes and archiving them.

### Backup Logic

The system identifies tenant volumes using the pattern `zeptoclaw_.*-data` [docs/MULTI-TENANT.md131](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L131-L131)

```

```

**Sources:** [docs/MULTI-TENANT.md121-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L121-L139)

## Summary of Multi-Tenant Invariants

For a secure multi-tenant deployment, the following invariants must be maintained:

1. Read-Only Configs: Agents cannot modify their own credentials via tool calls as configs are mounted with :ro docs/MULTI-TENANT.md 215
2. Network Isolation: Containers have no network access to each other by default docs/MULTI-TENANT.md 217
3. Identity Threading: In SaaS mode, every request context must include a tenant_id for RLS enforcement docs/MULTI_TENANT_SECURITY.md 137
4. Health Monitoring: Each tenant exposes a health endpoint (default port 9090) for liveness checks via wget to /healthz docker-compose.multi-tenant.yml 49-55

**Sources:** [docs/MULTI-TENANT.md213-221](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI-TENANT.md?plain=1#L213-L221) [docs/MULTI_TENANT_SECURITY.md115-124](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/MULTI_TENANT_SECURITY.md?plain=1#L115-L124)
