⚡ 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
📦
Andy's Container
🔨 Building app...
Messages blocked up to 10–15 minutes
Build continues uninterruptibly
Always Responsive

Two slots per group.

A lightweight chat container spins up instantly alongside the worker container. Instant response, uninterrupted build.

👤
David
Hey, status?
instant
running
⚡
Chat Container
💬 "~5 min left"
⚙️
Worker Container
🔨 Uninterrupted
⚡
Chat container
Spins up in seconds when you message during a task. Handles the reply, then exits.
⚙️
Worker container
Runs heavy tasks: builds, deploys, research. Never interrupted by incoming messages.
🎛️
Smart routing
New messages route to the chat slot. No waiting for the worker to finish.
⚡
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 Image
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 →