⚡ Architecture Overview

Always on.
Always secure.

How Klåd stays responsive while working, scales to multiple users, and keeps every tenant completely isolated.

See how it works →Setup guide
Instant responses
even mid-build
🔒
Full isolation
per tenant
♾️
Unlimited scale
add any user
The Problem

One container = one bottleneck

When Klåd is building or deploying, the group queue blocks. New messages wait up to 15 minutes. You can't get a status update or change direction mid-task.

👤
David
Hey, status?
🔴 BLOCKED
~10 min wait
📦
Klåd's Container
🔨 Building app...
Messages blocked up to 10–15 minutes
Build continues uninterruptibly
Always Responsive

Coordinator + Workers.

A long-lived Coordinator per group handles all messages instantly, classifies them, and spawns parallel Worker containers for heavy tasks. Workers run in isolation. Only the Coordinator writes to memory.

👤
David
Hey, status?
Build the app
🎛️ Coordinator
Always-on · classifies
routes · collects
single writer ✓
Worker A
🔨 Build app
Worker B
🚀 Deploy
Worker C
🔍 Research
🎛️
Coordinator (always-on)
Long-lived container per group. Responds to messages instantly, classifies tasks, manages the worker registry, collects results.
📦
Workers (parallel)
Ephemeral, isolated containers. Each gets its own scratch folder and a read-only task brief. Run in parallel for independent tasks.
✍️
Single writer principle
Only the Coordinator writes to group memory. Workers write to their scratch folder only. No conflicts, no corrupted state.
Quick fix — no code change. Add to .env and restart:
MAX_CONCURRENT_CONTAINERS=10
IDLE_TIMEOUT=300000
Multi-Tenant

One machine, many users.

Each user gets their own fully isolated Klåd instance — separate bot, database, and memory. Neither instance knows the other exists.

🖥️ Host Mac — two isolated stacks
🤖David's Klåd
Bot@klad_bot
DB/nanoclaw/store/…db
Port3000 · 10254
🤖Coworker's Klåd
Bot@cw_klad_bot
DB/nanoclaw-cw/store/…db
Port3001 · 10255
Shared (read-only):Docker EngineContainer Imageskills/knowledge/config/models.yml
Separate bot tokens
Separate databases
Separate memory
Separate ports
Security

Six layers of isolation.

Every boundary is enforced at the container level — not just by convention.

🔑
Separate credentials
Each instance has its own bot token and API key. No sharing.
💾
Isolated databases
Two separate SQLite files on different paths. No cross-reads.
📁
Separate file mounts
Each container only sees its own /workspace/group folder.
📦
Container sandboxing
Every agent run is a fresh Docker container with --rm.
🔒
Read-only source
Project source is mounted read-only. No code modification.
🚧
Mount allowlist
Extra mounts validated against an external host-side allowlist.
Setup

Add a user in 4 steps.

Full scripts are in the repo. Here's the outline:

01
Clone the project
cp -r ~/nanoclaw ~/nanoclaw-coworker
02
Register a new Telegram bot
Message @BotFather → /newbot
03
Fill in .env
TELEGRAM_BOT_TOKEN=… ASSISTANT_NAME=Klåd
04
Start the instance
docker compose -f docker-compose.coworker.yml up -d
Repo
📁 1-always-responsive/
DESIGN.md · patches/ · quick-fix.env
📁 2-multi-tenant/
DESIGN.md · docker-compose.yml · setup.sh
View on GitHub →