# nanocoai/nanoclaw architecture

> Architecture diagram of the GitHub repository nanocoai/nanoclaw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nanocoai/nanoclaw
- Repository: https://github.com/nanocoai/nanoclaw

## Overview

NanoClaw is a self-hosted assistant host that routes messages to agents running in isolated containers. A user message enters through an installed channel or the local CLI, is routed to an agent session, and is handled by a provider-backed container; replies are delivered back through the channel. The product also includes scheduling, permissions and approvals, agent-to-agent messaging, shared context, templates, and gateway-mediated credential security. Edges use README statements or SOURCE INDEX references; unsampled subsystems are included where documented, but their internal calls are not inferred.

Main entry points: [`src/router.ts`](https://github.com/nanocoai/nanoclaw/blob/main/src/router.ts) (Message router), [`src/container-runner.ts`](https://github.com/nanocoai/nanoclaw/blob/main/src/container-runner.ts) (Container runner), [`src/index.ts`](https://github.com/nanocoai/nanoclaw/blob/main/src/index.ts) (Host entrypoint), [`src/channels/adapter.ts`](https://github.com/nanocoai/nanoclaw/blob/main/src/channels/adapter.ts) (Channel adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Messaging and routing"]
  node_channel["Channel adapters<br/>[adapter.ts]"]
  node_cli["Local CLI<br/>[client.ts]"]
  node_router["Message router<br/>[router.ts]"]
  node_delivery["Reply delivery<br/>[delivery.ts]"]
end

subgraph group_host["Host orchestration"]
  node_host["Host entrypoint<br/>[index.ts]"]
  node_sessions["Session manager<br/>[session-manager.ts]"]
  node_setup["Setup and pairing<br/>[index.ts]"]
end

subgraph group_agent["Isolated agent runtime"]
  node_container["Container runner"]
  node_drivers["Runtime drivers<br/>[index.ts]"]
  node_providers["Agent providers<br/>[claude.ts]"]
  node_gateway["Credential gateway<br/>[index.ts]"]
end

subgraph group_state["State and governance"]
  node_database[("Central database<br/>[connection.ts]")]
  node_groupdata["Agent and channel state<br/>[agent-groups.ts]"]
  node_sessiondata["Session state<br/>[sessions.ts]"]
  node_permissions["Permissions and approvals<br/>[index.ts]"]
end

subgraph group_extensions["Agent capabilities"]
  node_scheduling["Scheduled tasks<br/>[create.ts]"]
  node_agentlinks["Agent messaging<br/>[index.ts]"]
  node_context["Cross-session context<br/>[index.ts]"]
  node_templates["Agent templates<br/>[manifest.ts]"]
  node_mailbox[("Agent mailbox<br/>[index.ts]")]
end

node_user(("User"))

node_user -->|"messages"| node_channel
node_user -->|"messages"| node_cli
node_channel -->|"routes inbound"| node_router
node_cli -.->|"admin transport"| node_router
node_host -->|"starts"| node_router
node_router -->|"resolves sessions"| node_sessions
node_router -->|"requests delivery"| node_delivery
node_delivery -->|"delivers replies"| node_channel
node_host -->|"starts runtime"| node_container
node_container -->|"selects driver"| node_drivers
node_container -->|"runs agent"| node_providers
node_container -->|"orchestrates credentials"| node_gateway
node_sessions -->|"reads and writes"| node_sessiondata
node_sessiondata -->|"queries"| node_database
node_groupdata -->|"queries"| node_database
node_host -->|"initializes"| node_database
node_router -->|"resolves agent groups"| node_groupdata
node_router -.->|"checks access"| node_permissions
node_router -->|"uses shared context"| node_context
node_host -.->|"runs scheduled work"| node_scheduling
node_user -->|"sets recurring tasks"| node_scheduling
node_user -->|"spawns teammates"| node_agentlinks
node_container -->|"uses mailbox"| node_mailbox
node_user -->|"creates agents"| node_templates
node_setup -->|"pairs channels"| node_channel
node_setup -->|"builds agent container"| node_container
node_setup -->|"installs gateway"| node_gateway

click node_channel "https://github.com/nanocoai/nanoclaw/blob/main/src/channels/adapter.ts"
click node_cli "https://github.com/nanocoai/nanoclaw/blob/main/src/cli/client.ts"
click node_router "https://github.com/nanocoai/nanoclaw/blob/main/src/router.ts"
click node_delivery "https://github.com/nanocoai/nanoclaw/blob/main/src/delivery.ts"
click node_host "https://github.com/nanocoai/nanoclaw/blob/main/src/index.ts"
click node_sessions "https://github.com/nanocoai/nanoclaw/blob/main/src/session-manager.ts"
click node_container "https://github.com/nanocoai/nanoclaw/blob/main/src/container-runner.ts"
click node_drivers "https://github.com/nanocoai/nanoclaw/blob/main/src/drivers/index.ts"
click node_providers "https://github.com/nanocoai/nanoclaw/blob/main/src/providers/claude.ts"
click node_gateway "https://github.com/nanocoai/nanoclaw/blob/main/src/gateway-providers/index.ts"
click node_database "https://github.com/nanocoai/nanoclaw/blob/main/src/db/connection.ts"
click node_groupdata "https://github.com/nanocoai/nanoclaw/blob/main/src/db/agent-groups.ts"
click node_sessiondata "https://github.com/nanocoai/nanoclaw/blob/main/src/db/sessions.ts"
click node_permissions "https://github.com/nanocoai/nanoclaw/blob/main/src/modules/permissions/index.ts"
click node_scheduling "https://github.com/nanocoai/nanoclaw/blob/main/src/modules/scheduling/create.ts"
click node_agentlinks "https://github.com/nanocoai/nanoclaw/blob/main/src/modules/agent-to-agent/index.ts"
click node_context "https://github.com/nanocoai/nanoclaw/blob/main/src/modules/cross-session-context/index.ts"
click node_templates "https://github.com/nanocoai/nanoclaw/blob/main/src/templates/manifest.ts"
click node_mailbox "https://github.com/nanocoai/nanoclaw/blob/main/src/mailbox/index.ts"
click node_setup "https://github.com/nanocoai/nanoclaw/blob/main/setup/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_channel,node_cli,node_router,node_delivery,node_user toneBlue
class node_host,node_sessions,node_setup toneAmber
class node_container,node_drivers,node_providers,node_gateway toneMint
class node_database,node_groupdata,node_sessiondata,node_permissions toneRose
class node_scheduling,node_agentlinks,node_context,node_templates,node_mailbox toneIndigo
```

## Components

### Messaging and routing

- [Channel adapters](https://github.com/nanocoai/nanoclaw/blob/main/src/channels/adapter.ts): `src/channels/adapter.ts`
- [Local CLI](https://github.com/nanocoai/nanoclaw/blob/main/src/cli/client.ts): `src/cli/client.ts`
- [Message router](https://github.com/nanocoai/nanoclaw/blob/main/src/router.ts): `src/router.ts`
- [Reply delivery](https://github.com/nanocoai/nanoclaw/blob/main/src/delivery.ts): `src/delivery.ts`

### Host orchestration

- [Host entrypoint](https://github.com/nanocoai/nanoclaw/blob/main/src/index.ts): `src/index.ts`
- [Session manager](https://github.com/nanocoai/nanoclaw/blob/main/src/session-manager.ts): `src/session-manager.ts`
- [Setup and pairing](https://github.com/nanocoai/nanoclaw/blob/main/setup/index.ts): `setup/index.ts`

### Isolated agent runtime

- [Container runner](https://github.com/nanocoai/nanoclaw/blob/main/src/container-runner.ts): `src/container-runner.ts`
- [Runtime drivers](https://github.com/nanocoai/nanoclaw/blob/main/src/drivers/index.ts): `src/drivers/index.ts`
- [Agent providers](https://github.com/nanocoai/nanoclaw/blob/main/src/providers/claude.ts): `src/providers/claude.ts`
- [Credential gateway](https://github.com/nanocoai/nanoclaw/blob/main/src/gateway-providers/index.ts): `src/gateway-providers/index.ts`

### State and governance

- [Central database](https://github.com/nanocoai/nanoclaw/blob/main/src/db/connection.ts): `src/db/connection.ts`
- [Agent and channel state](https://github.com/nanocoai/nanoclaw/blob/main/src/db/agent-groups.ts): `src/db/agent-groups.ts`
- [Session state](https://github.com/nanocoai/nanoclaw/blob/main/src/db/sessions.ts): `src/db/sessions.ts`
- [Permissions and approvals](https://github.com/nanocoai/nanoclaw/blob/main/src/modules/permissions/index.ts): `src/modules/permissions/index.ts`

### Agent capabilities

- [Scheduled tasks](https://github.com/nanocoai/nanoclaw/blob/main/src/modules/scheduling/create.ts): `src/modules/scheduling/create.ts`
- [Agent messaging](https://github.com/nanocoai/nanoclaw/blob/main/src/modules/agent-to-agent/index.ts): `src/modules/agent-to-agent/index.ts`
- [Cross-session context](https://github.com/nanocoai/nanoclaw/blob/main/src/modules/cross-session-context/index.ts): `src/modules/cross-session-context/index.ts`
- [Agent templates](https://github.com/nanocoai/nanoclaw/blob/main/src/templates/manifest.ts): `src/templates/manifest.ts`
- [Agent mailbox](https://github.com/nanocoai/nanoclaw/blob/main/src/mailbox/index.ts): `src/mailbox/index.ts`

### Other components

- **User**

## Connections

- User → Channel adapters: messages
- User → Local CLI: messages
- Channel adapters → Message router: routes inbound (evidence: `src/router.ts`)
- Local CLI → Message router: admin transport
- Host entrypoint → Message router: starts (evidence: `src/index.ts`)
- Message router → Session manager: resolves sessions (evidence: `src/router.ts`)
- Message router → Reply delivery: requests delivery (evidence: `src/router.ts`)
- Reply delivery → Channel adapters: delivers replies (evidence: `src/delivery.ts`)
- Host entrypoint → Container runner: starts runtime (evidence: `src/index.ts`)
- Container runner → Runtime drivers: selects driver (evidence: `src/container-runner.ts`)
- Container runner → Agent providers: runs agent (evidence: `src/container-runner.ts`)
- Container runner → Credential gateway: orchestrates credentials (evidence: `src/container-runner.ts`)
- Session manager → Session state: reads and writes (evidence: `src/session-manager.ts`)
- Session state → Central database: queries (evidence: `src/db/sessions.ts`)
- Agent and channel state → Central database: queries (evidence: `src/db/agent-groups.ts`)
- Host entrypoint → Central database: initializes (evidence: `src/index.ts`)
- Message router → Agent and channel state: resolves agent groups (evidence: `src/router.ts`)
- Message router → Permissions and approvals: checks access
- Message router → Cross-session context: uses shared context (evidence: `src/router.ts`)
- Host entrypoint → Scheduled tasks: runs scheduled work
- User → Scheduled tasks: sets recurring tasks
- User → Agent messaging: spawns teammates
- Container runner → Agent mailbox: uses mailbox (evidence: `src/container-runner.ts`)
- User → Agent templates: creates agents
- Setup and pairing → Channel adapters: pairs channels
- Setup and pairing → Container runner: builds agent container
- Setup and pairing → Credential gateway: installs gateway
