How darkspacey/nan-itself works
NAN-itself is a local-first autonomous agent framework with a web interface. A user sends a message through the UI and local HTTP/WebSocket gateway; the application routes input to the inbox module, and the agent runs turn-based LLM reasoning, using tools, skills, and ambient module context before streaming events back to the UI. The framework also supports hot-reloaded builtin/workspace providers and reactive module channels. Main runtime links follow the README and sampled app, engine, module, and frontend code; unsampled internals are represented only where documented.
Main entry points: runtime.py Module facade · core.py Agent loop · app.py App composition · gateway.py HTTP gateway
Components 22
Application runtime
- App composition
backend/nan_itself/app.py - HTTP gateway
backend/nan_itself/gateway.py - Event bus
backend/nan_itself/events.py
Agent reasoning
- Agent loop
backend/nan_itself/agent/core.py - Step engine
backend/nan_itself/agent/engine.py - Prompt assembly
backend/nan_itself/agent/prompts.py - LLM provider
backend/nan_itself/utils/llm.py - Agent verbs
backend/nan_itself/agent/verbs.py
Agent extensions
- Tool runtime
backend/nan_itself/tools/runtime.py - Builtin and workspace tools
builtin/tools/local/search.py - Skill runtime
backend/nan_itself/skills/runtime.py - Module facade
backend/nan_itself/modules/runtime.py - Ambient modules
builtin/modules/vision.py - Inbox module
builtin/modules/inbox.py - Workspace module
workspace/modules/workspace.py - Module state
backend/nan_itself/modules/persistence.py
User interface
- Web UI
frontend/app/src/App.tsx - WebSocket stream
frontend/app/src/state/useAgentStream2.ts - Message composer
frontend/app/src/shell/Composer.tsx
Other components
- User
- LLM service
- MCP servers
Connections 31
- User → Message composer: enters message
- Message composer → WebSocket stream: sends input
- WebSocket stream → HTTP gateway: WebSocket input
- HTTP gateway → App composition: dispatches input
- App composition → Inbox module: queues text
- App composition → HTTP gateway: starts gateway
- App composition → Agent loop: starts loop
- App composition → Tool runtime: starts providers
- App composition → Module facade: starts modules
- Agent loop → Step engine: runs turn
- Step engine → Prompt assembly: builds messages
- Step engine → LLM provider: requests completion
- LLM provider → LLM service: calls model
- Step engine → Agent verbs: dispatches calls
- Agent verbs → Tool runtime: invokes tool
- Tool runtime → Builtin and workspace tools: loads providers
- Tool runtime → MCP servers: calls MCP tools
- Agent loop → Skill runtime: uses skills
- Agent loop → Module facade: gets turn context
- Module facade → Ambient modules: runs perception
- Module facade → Inbox module: manages module
- Module facade → Workspace module: loads module
- Module facade → Module state: persists state
- Agent loop → Module facade: invokes channels
- Module facade → Agent loop: returns context
- HTTP gateway → Event bus: publishes events
- Agent loop → Event bus: emits turn events
- Event bus → HTTP gateway: streams events
- HTTP gateway → WebSocket stream: sends events
- WebSocket stream → Web UI: updates snapshot
- Web UI → User: shows response