How nanocoai/nanoclaw works
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: router.ts Message router · container-runner.ts Container runner · index.ts Host entrypoint · adapter.ts Channel adapters
Components 21
Messaging and routing
- Channel adapters
src/channels/adapter.ts - Local CLI
src/cli/client.ts - Message router
src/router.ts - Reply delivery
src/delivery.ts
Host orchestration
- Host entrypoint
src/index.ts - Session manager
src/session-manager.ts - Setup and pairing
setup/index.ts
Isolated agent runtime
- Container runner
src/container-runner.ts - Runtime drivers
src/drivers/index.ts - Agent providers
src/providers/claude.ts - Credential gateway
src/gateway-providers/index.ts
State and governance
- Central database
src/db/connection.ts - Agent and channel state
src/db/agent-groups.ts - Session state
src/db/sessions.ts - Permissions and approvals
src/modules/permissions/index.ts
Agent capabilities
- Scheduled tasks
src/modules/scheduling/create.ts - Agent messaging
src/modules/agent-to-agent/index.ts - Cross-session context
src/modules/cross-session-context/index.ts - Agent templates
src/templates/manifest.ts - Agent mailbox
src/mailbox/index.ts
Other components
- User
Connections 27
- User → Channel adapters: messages
- User → Local CLI: messages
- Channel adapters → Message router: routes inbound
src/router.ts - Local CLI → Message router: admin transport
- Host entrypoint → Message router: starts
src/index.ts - Message router → Session manager: resolves sessions
src/router.ts - Message router → Reply delivery: requests delivery
src/router.ts - Reply delivery → Channel adapters: delivers replies
src/delivery.ts - Host entrypoint → Container runner: starts runtime
src/index.ts - Container runner → Runtime drivers: selects driver
src/container-runner.ts - Container runner → Agent providers: runs agent
src/container-runner.ts - Container runner → Credential gateway: orchestrates credentials
src/container-runner.ts - Session manager → Session state: reads and writes
src/session-manager.ts - Session state → Central database: queries
src/db/sessions.ts - Agent and channel state → Central database: queries
src/db/agent-groups.ts - Host entrypoint → Central database: initializes
src/index.ts - Message router → Agent and channel state: resolves agent groups
src/router.ts - Message router → Permissions and approvals: checks access
- Message router → Cross-session context: uses shared context
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
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