NanoClaw Architecture Analysis / Real-World Scenario Q&A

╔══════════════════════════════════════════════════════════════════════════╗
║                          NanoClaw System                                 ║
║                                                                          ║
║  ┌─────────────────────────────────────────────────────────────────┐    ║
║  │              Channels (Self-Registering Skills)                  │    ║
║  │  WhatsApp │ Telegram │ Slack │ Discord │ Gmail │ (custom)        │    ║
║  │           └─────────────────┬───────────────────                 │    ║
║  │                  registerChannel() at startup                    │    ║
║  └───────────────────────────┬─────────────────────────────────────┘    ║
║                               │ onMessage(jid, NewMessage)               ║
║                               ▼                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐ ║
║  │                     SQLite Database                                │ ║
║  │  chats │ messages │ scheduled_tasks │ sessions │ registered_groups │ ║
║  └───────────────────────────┬────────────────────────────────────────┘ ║
║                               │ poll every 2s                            ║
║                               ▼                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐ ║
║  │              Orchestrator (src/index.ts)                           │ ║
║  │                                                                    │ ║
║  │  Message Loop ──┬── Trigger Check (@Andy)                         │ ║
║  │                 ├── Group Queue (per-group concurrency)            │ ║
║  │                 └── runAgent()                                     │ ║
║  │                                                                    │ ║
║  │  IPC Watcher ───── File-based IPC (poll every 1s)                 │ ║
║  │  Scheduler ─────── Cron/Interval/Once tasks (poll every 60s)      │ ║
║  │  Credential Proxy ─ HTTP proxy on port 3001                       │ ║
║  └───────────────────────────┬────────────────────────────────────────┘ ║
║                               │ spawn container                          ║
║                               ▼                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐ ║
║  │              Container Agent (Docker / Apple Container)            │ ║
║  │                                                                    │ ║
║  │  entrypoint.sh → agent-runner/index.ts                            │ ║
║  │       ├── Claude Agent SDK (streaming)                            │ ║
║  │       ├── Tools: Bash, File I/O, Web, Browser                     │ ║
║  │       └── MCP: ipc-mcp-stdio.ts (scheduler tools)                 │ ║
║  └───────────────────────────┬────────────────────────────────────────┘ ║
║                               │ stdout (JSON markers)                    ║
║                               ▼                                          ║
║  ┌──────────────────────────────────────────────────────────────────┐   ║
║  │              Response Routing (src/router.ts)                    │   ║
║  │  Strip <internal> tags → findChannel() → sendMessage()          │   ║
║  └──────────────────────────────────────────────────────────────────┘   ║
╚══════════════════════════════════════════════════════════════════════════╝

[Incoming WhatsApp message from user]
        │
        ▼
WhatsApp Channel (Baileys)
  └── onMessage(jid, NewMessage) callback fired
        │
        ▼
src/db.ts → storeMessage()
  └── Persisted to SQLite messages table
        │
        ▼
src/index.ts → startMessageLoop() [2-second poll]
  └── getNewMessages() — fetch unprocessed messages
        │
        ├── [Non-Main group] Check trigger pattern (@Andy)
        │     ├── No trigger → hold in DB
        │     └── Trigger found → continue
        │
        ▼
processGroupMessages()
  └── Collect pending messages for the group & format as XML
        │
        ▼
src/group-queue.ts → enqueueMessageCheck()
  └── Check concurrent container count (MAX_CONCURRENT_CONTAINERS: 5)
        │
        ▼
src/container-runner.ts → runContainerAgent()
  └── Build volume mount config (group folder, session directory, etc.)
      └── docker run / container run
            │
            ▼
  container/agent-runner/src/index.ts
    └── Claude Agent SDK (streaming execution)
          │
          ├── Tool execution (Bash, file, web, browser)
          └── MCP tools (schedule_task, send_message, etc.)
                │ stdout JSON (sentinel markers)
                ▼
src/index.ts → receive result
  └── Strip <internal> tags → router.ts → channel response
        │
        ▼
WhatsApp Channel → sendMessage() → reply delivered to user

1. initDatabase() — SQLite init & migrations
2. startCredentialProxy() — Start credential proxy (port 3001)
3. Load channel factories — Initialize channels self-registered via registerChannel()
4. getRegisteredGroups() — Load registered group list from DB
5. startIpcWatcher() — Start file IPC watcher
6. startSchedulerLoop() — Start scheduled task loop
7. Check for unprocessed messages (crash recovery)
8. startMessageLoop() — Start main message polling loop

// Main group: no trigger required, all messages are processed
// Non-Main groups: processed only when the @Andy pattern is present
const TRIGGER_PATTERN = new RegExp(`@${ASSISTANT_NAME}`, 'i')

if (!group.isMain && !messages.some((m) => TRIGGER_PATTERN.test(m.content))) {
  // Hold message in DB, wait for trigger
  return
}

// Last-processed timestamp (per group)
lastAgentTimestamp: Record<groupFolder, timestamp>

// Group session IDs (container continuity)
sessions: Map<groupFolder, sessionId>

// Registered group metadata
registeredGroups: Map<jid, RegisteredGroup>

Host process
  └── docker run / container run
        ├── stdin  ← ContainerInput JSON
        │           { messages, group, sessionId, isScheduledTask, ... }
        └── stdout → ContainerOutput JSON (sentinel markers)
                     { result, sessionId, ... }

FROM node:22-slim

# Install Chromium and browser automation libraries
RUN apt-get install -y chromium ...

# Global packages
RUN npm install -g agent-browser @anthropic-ai/claude-code

# Compile agent runner
COPY container/agent-runner/ /app/agent-runner/
RUN tsc ...

# Run as non-root user
USER node
ENTRYPOINT ["/app/entrypoint.sh"]

// stdin (host → container)
interface ContainerInput {
  messages: string // XML-formatted messages
  group: RegisteredGroup // group metadata
  sessionId?: string // session continuity
  isScheduledTask?: boolean // whether this is a scheduled task
  taskPrompt?: string // task prompt
}

// stdout (container → host, wrapped in sentinel markers)
interface ContainerOutput {
  result: string // agent response
  sessionId: string // new session ID
  error?: string
}

// Markers
const START = '---NANOCLAW_OUTPUT_START---'
const END = '---NANOCLAW_OUTPUT_END---'

When a new message arrives while a container is actively running:

Host → writes /workspace/ipc/input/{timestamp}.json
Container (500ms poll) → detects file → appends to MessageStream
Agent → processes follow-up message → sends response
(Container stays alive; idle timeout 30 minutes)

// src/channels/registry.ts
registerChannel('whatsapp', async (config) => {
  if (!process.env.WHATSAPP_ENABLED) return null
  return new WhatsAppChannel(config)
})

// Looked up by the orchestrator
const factory = getChannelFactory('whatsapp')
const channel = await factory?.(config)

interface Channel {
  name: string
  connect(): Promise<void>
  disconnect(): Promise<void>
  sendMessage(jid: string, text: string): Promise<void>
  isConnected(): boolean
  ownsJid(jid: string): boolean
  setTyping?(jid: string, typing: boolean): Promise<void>
  syncGroups?(): Promise<void>
}

// Returns null if credentials are missing → orchestrator skips it
const factory = getChannelFactory(name)
if (!factory) return // channel not installed
const channel = await factory(config)
if (!channel) return // no credentials

// Route response back to the originating channel
function findChannel(jid: string): Channel | undefined {
  return channels.find((ch) => ch.ownsJid(jid))
}

startSchedulerLoop() [60-second poll]
  └── getDueTasks() — next_run <= now AND status='active'
        │
        ├── [cron] Calculate next run time with cron-parser
        ├── [interval] Last run + interval (drift-safe)
        └── [once] Single execution, then mark as completed
              │
              ▼
        group-queue.ts → enqueueTask()
              │
              ▼
        runContainerAgent() (isolated or group context)
              │
              ▼
        Result → send_message IPC tool → channel response
        Logs  → task_run_logs table

Container side (MCP tools)
  ipc-mcp-stdio.ts
    └── Creates /workspace/ipc/{group}/messages/{id}.json
          { type: 'schedule_task', payload: {...} }

Host side (1-second poll)
  src/ipc.ts → startIpcWatcher()
    └── Detects file → parses content → executes command → deletes file

┌─────────────────────────────────────────────────────┐
│                   Host System                        │
│                                                     │
│  Credential Proxy ────────── Real API keys (inaccessible to container) │
│  Mount Allowlist ──────────── .ssh, .aws, etc. blocked                  │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │           Container (isolation boundary)     │   │
│  │                                             │   │
│  │  Non-root user (node, uid 1000)             │   │
│  │  Read/write only to /workspace/group        │   │
│  │  Only placeholder credentials injected      │   │
│  │                                             │   │
│  │  ┌─────────────────────────────────────┐   │   │
│  │  │         Agent execution space        │   │   │
│  │  │  Group memory, session isolation     │   │   │
│  │  └─────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

Container
  └── ANTHROPIC_API_KEY=placeholder
      ANTHROPIC_BASE_URL=http://host:3001
        │
        ▼ HTTP request
Credential Proxy (port 3001)
  └── Injects real API key
        │ HTTP request (header replaced)
        ▼
Anthropic API (api.anthropic.com)

// ~/.config/nanoclaw/mount-allowlist.json (host-only; cannot be mounted into container)
{
  "allowedRoots": [{ "path": "~/Documents", "label": "Documents" }],
  "blockedPatterns": [
    ".ssh",
    ".gnupg",
    ".aws",
    ".env",
    "credentials",
    "id_rsa",
    "id_ed25519",
    "*.pem",
    "*.key"
  ],
  "nonMainReadOnly": true
}

Main group container
  ├── Can send messages to any JID
  ├── Can manage tasks for any group
  └── Can register new groups

Non-Main group container
  ├── Can send messages to its own JID only
  ├── Can manage its own group's tasks only
  └── Cannot register groups

-- Group/chat metadata
CREATE TABLE chats (
  jid TEXT PRIMARY KEY,
  name TEXT,
  last_message_time INTEGER,
  channel TEXT,        -- 'whatsapp', 'telegram', etc.
  is_group INTEGER
);

-- Message history
CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  chat_jid TEXT,
  sender TEXT,
  timestamp INTEGER,
  content TEXT,
  is_bot_message INTEGER DEFAULT 0
);

-- Scheduled tasks
CREATE TABLE scheduled_tasks (
  id INTEGER PRIMARY KEY,
  group_folder TEXT,
  chat_jid TEXT,
  prompt TEXT,
  schedule_type TEXT,   -- 'cron' | 'interval' | 'once'
  schedule_value TEXT,  -- cron expression, ms value, or ISO date
  context_mode TEXT,    -- 'group' | 'isolated'
  next_run INTEGER,
  status TEXT           -- 'active' | 'paused' | 'completed'
);

-- Task execution logs
CREATE TABLE task_run_logs (
  id INTEGER PRIMARY KEY,
  task_id INTEGER,
  started_at INTEGER,
  duration_ms INTEGER,
  status TEXT,
  result TEXT,
  error TEXT
);

-- Router state (JSON key-value)
CREATE TABLE router_state (
  key TEXT PRIMARY KEY,
  value TEXT
  -- last_timestamp: global last-processed timestamp
  -- last_agent_timestamp: { groupFolder: timestamp } JSON
);

-- Group session IDs
CREATE TABLE sessions (
  group_folder TEXT PRIMARY KEY,
  session_id TEXT
);

-- Registered groups
CREATE TABLE registered_groups (
  jid TEXT PRIMARY KEY,
  name TEXT,
  folder TEXT,
  trigger TEXT,
  is_main INTEGER,
  added_at INTEGER
);

// Message passed from channel to host
interface NewMessage {
  id: string
  chat_jid: string // "1234567890@s.whatsapp.net"
  sender: string
  sender_name: string
  content: string
  timestamp: number
  is_from_me?: boolean
  is_bot_message?: boolean
}

// Group metadata stored in DB
interface RegisteredGroup {
  name: string
  folder: string // "groups/family-chat"
  trigger: string // "@Andy"
  added_at: number
  isMain?: boolean
  requiresTrigger?: boolean
  containerConfig?: ContainerConfig
}

// Scheduled task
interface ScheduledTask {
  id: number
  group_folder: string
  chat_jid: string
  prompt: string
  schedule_type: 'cron' | 'interval' | 'once'
  schedule_value: string
  context_mode: 'group' | 'isolated'
  next_run: number
  status: 'active' | 'paused' | 'completed'
}

<messages timezone="Asia/Seoul">
  <message id="abc123" sender="+82101234567" sender_name="Alice" timestamp="2026-03-13T10:00:00+09:00">
    <content>@Andy 오늘 날씨 어때?</content>
  </message>
  <message id="def456" sender="+82109876543" sender_name="Bob" timestamp="2026-03-13T10:01:00+09:00">
    <content>나도 궁금해</content>
  </message>
</messages>

┌──────────────────────────────────────────────────────────────┐
│                     Channel Layer                             │
│  WhatsApp / Telegram / Slack / Discord / Gmail                │
│  (self-registering, implements Channel interface)             │
└──────────────────────────────┬───────────────────────────────┘
                               │ onMessage callback
┌──────────────────────────────▼───────────────────────────────┐
│                     Data Layer                                │
│  src/db.ts (SQLite, better-sqlite3, synchronous)             │
│  storeMessage / getNewMessages / getRegisteredGroups / ...    │
└──────────────────────────────┬───────────────────────────────┘
                               │ DB read/write
┌──────────────────────────────▼───────────────────────────────┐
│                   Orchestration Layer                         │
│  src/index.ts → src/group-queue.ts                           │
│  Message loop / trigger check / queue management / concurrency│
└──────────────────────────────┬───────────────────────────────┘
                               │ spawn + stdin/stdout
┌──────────────────────────────▼───────────────────────────────┐
│                   Container Layer                             │
│  src/container-runner.ts                                     │
│  Volume mounts / credential proxy injection / skill sync     │
└──────────────────────────────┬───────────────────────────────┘
                               │ Claude Agent SDK
┌──────────────────────────────▼───────────────────────────────┐
│                   Agent Layer                                 │
│  container/agent-runner/src/index.ts                         │
│  Claude Agent SDK / MCP server / IPC polling                 │
└──────────────────────────────┬───────────────────────────────┘
                               │ HTTP (proxy)
┌──────────────────────────────▼───────────────────────────────┐
│                   External Layer                              │
│  Anthropic API (api.anthropic.com)                           │
└──────────────────────────────────────────────────────────────┘

Parallel systems:
  src/ipc.ts             ─── File IPC watcher (1-second poll)
  src/task-scheduler.ts  ─── Scheduled tasks (60-second poll)
  src/credential-proxy.ts ── HTTP proxy (port 3001)

nanoclaw/
├── src/                          # Host process source
│   ├── index.ts                  # Orchestrator (main entry)
│   ├── channels/
│   │   └── registry.ts           # Channel self-registration
│   ├── router.ts                 # Message formatting & routing
│   ├── config.ts                 # Environment-variable config
│   ├── container-runner.ts       # Container spawning & mounts
│   ├── group-queue.ts            # Per-group queue & concurrency
│   ├── ipc.ts                    # File IPC watcher
│   ├── task-scheduler.ts         # Scheduled tasks
│   ├── db.ts                     # SQLite CRUD
│   ├── credential-proxy.ts       # Credential isolation proxy
│   ├── mount-security.ts         # Mount path validation
│   └── types.ts                  # Shared type definitions
│
├── container/                    # Container-related files
│   ├── Dockerfile                # Agent container image
│   ├── entrypoint.sh             # Container entrypoint
│   ├── build.sh                  # Image build script
│   ├── agent-runner/             # In-container agent
│   │   └── src/
│   │       ├── index.ts          # Claude SDK execution
│   │       └── ipc-mcp-stdio.ts  # MCP tools (scheduler, etc.)
│   └── skills/                   # Skills injected into the agent
│       └── agent-browser.md      # Browser automation guide
│
├── groups/                       # Per-group memory (isolated)
│   ├── main/
│   │   └── CLAUDE.md             # Main group memory
│   └── global/
│       └── CLAUDE.md             # Globally shared memory (read-only)
│
├── data/                         # Runtime data
│   ├── messages.db               # SQLite database
│   ├── sessions/                 # Per-group .claude/ sessions
│   └── ipc/                      # File IPC directories
│       └── {group}/
│           ├── messages/         # Container → host commands
│           └── input/            # Host → container follow-up messages
│
├── store/                        # Channel authentication state
├── logs/                         # Log files
├── launchd/                      # macOS service config
│   └── com.nanoclaw.plist
├── docs/
│   ├── SPEC.md                   # Full specification (31.7k)
│   ├── SECURITY.md               # Security model
│   └── REQUIREMENTS.md           # Design decisions
└── CLAUDE.md                     # Claude Code context

# Example: installing the WhatsApp channel skill
git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
git fetch whatsapp main
git merge whatsapp/main
npm run build

First run:  sessionId = undefined → Claude creates a new session → returned sessionId is stored
Second run: sessionId = "abc123"  → Claude resumes the existing session