Architecture

NanoClaw is one Node.js host process plus one Docker container per active session. The host owns the channels, the routing, and the container lifecycle; the agent runs inside the container and never touches the messaging platforms — that traffic is all host. (The agent’s own network egress is a separate matter: open by default, lockable.) Between them sits the core idea: every message is a row in SQLite. The shipped mailbox uses a SQLite pair: the host writes rows the container reads, and the container writes rows the host reads. Mailbox storage, the central database, and the session runtime each sit behind a separate implementation seam. Host-side message writes and runtime exit events also enqueue reconciliation; periodic polling and resync recover when those hints are lost. Each session owns a pair of database files in its session folder:

• inbound.db — host writes, container reads. Inbound messages, scheduled tasks, routing defaults.
• outbound.db — container writes, host reads. Agent replies, processing acknowledgements, session state.

One writer per file, opposite directions — so a crashed container can never corrupt the host’s queue. (Two narrow host-side writes to outbound.db bend the rule deliberately; the invariants section below explains why they’re safe.)

​

A message, end to end

Step by step on the inbound side (src/router.ts):

1. The adapter normalizes a platform event and hands it to the router (see Channels overview for the adapter side).
2. Non-threaded adapters collapse threadId to null; the router looks up the messaging group for (channel_type, platform_id, instance), auto-creating one on a mention or DM. Unwired channels escalate to the owner for approval instead of routing.
3. The sender is resolved to a namespaced user ID, then the message fans out to every wired agent independently: engage mode (pattern, mention, mention-sticky), access gate, and sender scope decide per agent. Agents that decline but have ignored_message_policy='accumulate' still get the row stored as silent context (trigger=0).
4. For each engaging agent, the router resolves a session (shared, per-thread, or agent-shared — see Entity model), writes the row to that session’s inbound.db, and wakes the container.

On the outbound side, src/delivery.ts drains messages_out: an in-flight set prevents the two polls from double-delivering, rows are filtered against the delivered table in inbound.db, then routed by kind — system actions are handled by the host itself, channel_type='agent' rows go to the agent-to-agent module, and everything else passes a destination permission check before adapter.deliver(). Three failed attempts marks a message permanently failed.

​

The host process

src/index.ts is a thin orchestrator. What it starts, in order:

1. Circuit breaker — backs off on rapid restart loops, then an upgrade tripwire refuses to start if the install was updated outside /update-nanoclaw.
2. Central DB — opens data/v2.db, runs migrations, and backfills container configs.
3. Session driver: proves the container runtime is reachable, then adopts sessions that are still running from a previous host run instead of killing them; only true orphans are stopped. The runtime sits behind a driver seam (src/drivers/: Docker ships built-in and is the default; NANOCLAW_RUNTIME_DRIVER selects, and an unknown value aborts startup). Containers spawned by a pre-seam release cannot be adopted and are removed at first upgraded startup.
4. Channel adapters — every adapter registered via the channel barrel is initialized; adapters with missing credentials are skipped with a warning.
5. Delivery adapter bridge — connects the delivery system to the adapter registry for deliver() and setTyping().
6. Host modules — runs the start callbacks that modules registered through the host lifecycle registry (onHostStart/onHostShutdown); a failed module start aborts host startup.
7. Host lease and delivery polls — registers this host process in durable coordination state and keeps its lease fresh, then starts the active poll (1s, sessions with a running container) and the sweep poll (60s, all active sessions).
8. Host sweep — the 60-second maintenance loop described below.
9. ncl CLI socket server — admin commands over a Unix socket at data/ncl.sock (see ncl CLI).

Modules (permissions, scheduling, approvals, agent-to-agent, typing, and so on) self-register through barrel imports before main() runs — registration is inert until step 6 starts them — and they hook into the router and delivery pipeline rather than being called by name from core.

​

Inside the container

The container runs the agent-runner (container/agent-runner/src/) directly with Bun — no compile step, since the source is a read-only bind mount at /app/src. All IO goes through the session DB pair mounted at /workspace; there is no stdin, no stdout markers. The poll loop (poll-loop.ts) drives everything:

• Every second it reads pending messages_in rows. Batches containing only trigger=0 (accumulated context) rows don’t wake the agent — they ride along with the next real trigger.
• A batch is marked processing, formatted into XML (<message>, <task>, <webhook> blocks with a timezone header — formatter.ts), and sent to the provider as one prompt.
• While the query streams, a 500ms follow-up poll pushes newly arrived messages into the open stream instead of restarting the provider subprocess. The push only fires when at least one new message is a trigger; accumulated context alone never engages a warm query.
• Outbound content must be wrapped in <message to="name"> blocks; each complete block becomes a messages_out row addressed to a named destination, and bare text is treated as scratchpad and never sent. For providers that declare emitsMidTurnText (Claude does), the mid-turn stream is the only content door on chat turns: closed blocks are delivered as they are emitted (with cross-segment assembly of blocks split across streaming segments), and the final result never delivers content (error notices excepted). A chat turn that delivered nothing but whose result still carries content gets a wrap nudge, and the retry streams through the same door. Providers without the flag keep the final result as their single delivery door, and task runs stay one-door on every provider: a scheduled task’s only outbound path is the send_message tool.
• The provider’s session ID (continuation) is persisted to outbound.db so the next container resumes the conversation, and a PreCompact hook injects instructions that preserve routing context through context compaction.
• On every provider event the runner touches /workspace/.heartbeat, recording provider progress. Runtime status and exit events separately tell the host whether the container is alive.

The agent itself talks to NanoClaw through a built-in MCP server (send_message, ask_user_question, create_agent, and friends — see MCP tools; scheduling is not an MCP tool anymore, it moved to the ncl tasks CLI). The provider behind provider.query() is pluggable: Claude Code is the default, and others self-register the same way channels do (see Providers).

​

Composed at spawn

The container runner (src/container-runner.ts) rebuilds the agent’s world on every spawn. Concurrent wakes for the same session are deduplicated through an in-flight promise map. A durable session claim also prevents two live host processes from owning the same run. The runner:

1. Refreshes the session’s destination map and default reply routing in inbound.db.
2. Materializes container.json from the database and syncs skill symlinks to match its selection.
3. Composes groups/<folder>/CLAUDE.md (src/project-doc-compose.ts) and builds the mount list. The composed document is one flat file, beginning with <!-- Composed at spawn - do not edit. Standing instructions: instructions.prepend.md. Memory: memory/. -->. Every instruction source is read on the host and inlined as a section: the group’s instructions.prepend.md first, then the shared base (container/CLAUDE.md), the provider’s own blocks, one section per enabled module manual, resident skill prose honoring the group’s skill selection, and instructions from user-added MCP servers. Nothing is an @-import anymore: Claude Code gates imports that resolve outside the project directory behind an approval a headless container can never grant, so pointer-based composition silently lost eight of nine sections; a test now pins that the composer emits no import lines. For Claude a 4 MiB cap guards the file-size cliff, with droppable sections evicted first. The files you (or the agent) edit are still instructions.prepend.md for standing instructions and the memory/ tree for durable memory; the composed CLAUDE.md is regenerated every spawn.
4. Wires the credential gateway (the OneCLI Agent Vault by default): the gateway provider’s per-session contribution (HTTPS_PROXY, trust certificates, credential-stub mounts) is merged into the session spec before validation, so admission sees the whole session. If the vault is unreachable, the spawn fails rather than running without credentials, and the message stays pending for the next sweep.
5. Composes a session spec and hands it to the driver: mounts, env, limits, labels, and the gateway contribution are assembled into a spec (composeSessionSpec), which the session driver validates and admission-checks on receipt, then realizes: the Docker driver runs docker create + start --attach under a key-derived ncl-… name, with the old human-readable nanoclaw-v2-<folder>-<timestamp> name preserved as the nanoclaw-container-name label. Egress-lockdown network topology is the driver’s own concern (see Security model).

The mounts define what the agent can touch: the session folder at /workspace (read-write), the group folder at /workspace/agent (read-write, with container.json and the composed CLAUDE.md re-mounted read-only on top), and shared read-only code at /app/src and /app/skills. Container lifecycle covers spawn-to-exit in detail.

​

What runs when

The host sweep (src/host-sweep.ts) feeds a keyed workqueue: message writes and runtime exit hints enqueue sessions promptly, and a periodic resync catches lost hints. The resync also re-heals the egress network. The per-session work lives in src/reconcile-session.ts:

1. Syncs processing_ack from outbound.db into messages_in status, so completed work is recorded on the host side.
2. Wakes containers for due work — rows whose process_after has elapsed (scheduled tasks, retries) with no container running.
3. Enforces the running-container SLA — kills a container whose heartbeat is older than max(30 minutes, its declared Bash timeout), or one that claimed a message and showed no heartbeat for over max(60 seconds, its declared Bash timeout) since the claim. If no heartbeat file exists yet, the ceiling uses the tracked spawn or adoption time.
4. Cleans up after crashes — processing rows left by a dead container are reset to pending with exponential backoff (5s × 2^tries); after 5 tries a message is marked failed.
5. Advances recurring tasks — completed recurring rows are cloned into their next occurrence (see Scheduled tasks).

There is deliberately no wall-clock idle timeout: liveness is judged from the heartbeat file and claim age, so long-running legitimate work is never killed on a timer.

​

The two database layers

The shipped storage implementations use SQLite, split across two layers — the database schema reference documents every table.

• Central database (data/v2.db) — the entity model: agent groups, messaging groups, users, wirings, sessions, approvals. Host-only, opened once, WAL mode.
• Session pairs (data/v2-sessions/<agent_group_id>/<session_id>/) — inbound.db and outbound.db, shared with exactly one container via bind mount.

The shipped SQLite mailbox uses the session pair for host-container message transport. Files in inbox/ and outbox/ carry attachments alongside their message rows, and .heartbeat carries liveness. Three invariants govern the shipped SQLite mailbox across a Docker mount (implemented in src/mailbox/sqlite/session-db.ts):

1. journal_mode=DELETE, not WAL — WAL’s memory-mapped -shm file doesn’t refresh across the host-to-container mount, so a WAL-mode container would silently miss every new message.
2. The host opens, writes, and closes per operation — a long-lived host connection would freeze the container’s view of the file at first read.
3. One writer per file — DELETE-mode journal unlinking isn’t atomic across the mount, so concurrent writers would corrupt the database. Hence the split into two files with opposite ownership. The host itself writes rows into outbound.db in just two deliberate cases — command-gate denials, answered without waking the container, and clearing a killed container’s orphaned processing claims after the container is already gone — both opened with the same DELETE journal and busy_timeout discipline.

​

Related pages

• Entity model — agent groups, messaging groups, wirings, sessions
• Container lifecycle — spawn, heartbeat, kill, and respawn in detail
• Security model — isolation boundaries and egress lockdown
• Database schema — every table in v2.db and the session pairs
• Channels overview — the adapter side of the inbound path