bot0 System Architecture
Overview
bot0 is a personal AI agent that lives on your machines. It can control your computer, execute tasks, and connect to a network of other bot0 daemons for distributed work.
Key principle: The daemon is the brain. Everything else is UI or routing.
High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ USER'S MACHINE │
│ │
│ ┌─────────────────────┐ IPC (local) ┌─────────────────────┐ │
│ │ │◄────────────────────────►│ │ │
│ │ bot0 Desktop │ │ bot0 Daemon │ │
│ │ (Electron) │ │ (Node.js) │ │
│ │ │ │ │ │
│ │ • Chat UI │ │ • Agent loop │ │
│ │ • Settings │ │ • Computer use │ │
│ │ • Onboarding │ │ • Bytespace client│ │
│ │ │ │ • Hub connection │ │
│ │ JUST UI │ │ THE BRAIN │ │
│ └─────────────────────┘ └──────────┬──────────┘ │
│ │ │
└───────────────────────────────────────────────────────────────┼─────────────────────┘
│
│ WebSocket
│ (only for remote tasks)
│
┌───────────────────────────────────────────────────────────────┼─────────────────────┐
│ BYTESPACE CLOUD │ │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ │ │
│ │ Telegram │ │ WhatsApp │ │ │
│ │ Webhook │ │ Webhook │ │ │
│ └───────┬──────┘ └───────┬──────┘ │ │
│ │ │ │ │
│ └────────────┬────────────┘ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ HUB │ │
│ │ (Fly.io) │ │
│ │ │ │
│ │ • WebSocket relay │ │
│ │ • Daemon registry & presence │ │
│ │ • Task routing │ │
│ │ • Task queue (when daemons offline) │ │
│ │ │ │
│ │ DUMB RELAY — NO AI LOGIC │ │
│ └───────────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │daemon-2 │ │daemon-3 │ │daemon-4 │ │
│ │"server" │ │"office" │ │"cloud" │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ BYTESPACE API │ │
│ │ (Vercel) │ │
│ │ │ │
│ │ • Auth & user management │ │
│ │ • Skills registry │ │
│ │ • Memory store │ │
│ │ • Billing │ │
│ │ • Channel webhooks (Telegram, WhatsApp, etc.) │ │
│ │ │ │
│ │ STATELESS REST API │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
Core Components
1. bot0 Daemon (The Brain)
The daemon is a Node.js process that runs on any machine. It IS the agent.
Responsibilities:
- Agent loop (receive input → plan → execute → respond)
- Computer use (screenshots, mouse, keyboard)
- Calls Anthropic API for LLM inference
- Calls Bytespace API for skills, memory, user data
- Connects to Hub for remote task dispatch
- Executes tasks from any source (Desktop, Telegram, other daemons)
Runs as:
- Background process via launchd (macOS) or systemd (Linux)
- Started by Desktop app or
bot0 nodecommand
Identity:
typescript
{ id: "d_abc123", // Unique ID name: "macbook-pro", // Human-readable name user_id: "u_xyz", // Owner capabilities: ["computer_use", "browser", "code"], status: "online" | "offline" }
2. bot0 Desktop (The UI)
Electron app that provides a GUI for interacting with your daemon.
Responsibilities:
- Chat interface
- Settings and configuration
- Onboarding flow
- Daemon management (start/stop/status)
Does NOT contain:
- AI logic
- Agent loop
- Direct Anthropic API calls
Connection:
- Talks to local daemon via IPC (Unix socket or local WebSocket)
- P2P, no cloud hop for local tasks
3. bot0 CLI
Command-line interface for developers.
Commands:
bash
$ bot0 # Opens Desktop app $ bot0 node # Runs daemon headless (for servers) $ bot0 status # Shows daemon status $ bot0 run "task" # Quick one-off task $ bot0 login # Authenticate with Bytespace
4. Hub (The Relay)
WebSocket server deployed on Fly.io. Handles real-time communication between daemons.
Responsibilities:
- Daemon registry (who's online, their capabilities)
- WebSocket relay between daemons
- Task routing (find the right daemon for a task)
- Task queue (store tasks when target daemon is offline)
- Presence tracking
Does NOT contain:
- AI logic
- LLM calls
- Business logic
Why Fly.io:
- Persistent WebSocket connections (Vercel can't do this)
- Global edge deployment
- Simple Node.js deployment
5. Bytespace API (The Backend)
Your existing Next.js API on Vercel. Stateless REST API.
Responsibilities:
- Authentication & user management
- Skills registry (CRUD, sync)
- Memory store (user context, preferences)
- Billing & subscriptions
- Channel webhooks (receives Telegram, WhatsApp, Slack messages)
- Task classification (does this need a daemon?)
Data Flows
Flow 1: Local Chat (P2P, no cloud)
User chats in Desktop app, daemon is on same machine.
User types: "Hello bot!"
│
▼
Desktop App
│
│ IPC (local socket)
▼
Local Daemon
│
│ Calls Anthropic API
│ Streams response
│
▼
Desktop App displays response
Latency: ~500ms (just LLM time) Cloud involved: Only Anthropic API
Flow 2: Local Computer Use
User asks daemon to do something on this machine.
User: "Open Figma and export the icons"
│
▼
Desktop App
│
│ IPC
▼
Local Daemon
│
│ Agent plans: need computer use
│ Screenshot → Analyze → Click → Type → etc.
│ (1 second per action with MLX grounding)
│
▼
Task complete, streams result to Desktop
Flow 3: Remote Task (via Hub)
User wants to run task on a different machine.
User: "Run the scraper on server-1"
│
▼
Desktop App
│
│ IPC
▼
Local Daemon
│
│ "I need server-1 for this"
│ WebSocket
▼
Hub
│
│ Looks up server-1, finds WebSocket connection
│ WebSocket
▼
daemon on server-1
│
│ Executes task
│ Streams result back
│
▼
Hub
│
▼
Local Daemon
│
▼
Desktop App displays result
Flow 4: Telegram Message
User sends command via Telegram.
User sends: "summarize my emails" to @bot0_bot
│
▼
Telegram Webhook → Bytespace API
│
│ Classify: does this need computer use?
│
├─ NO (just API calls) ──────────────────┐
│ │
│ ▼
│ Bytespace handles directly
│ (calls Gmail API, responds)
│
└─ YES (needs daemon) ───────────────────┐
│
▼
Hub
│
│ Route to primary daemon
▼
┌──────────────┐
│ Daemon online?│
└───────┬──────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
YES NO
│ │
▼ ▼
Execute task Queue task
Stream to Telegram Notify user:
"bot0 is offline,
task queued"
Flow 5: Daemon Offline Handling
┌─────────────────────────────────────────────────────────────┐
│ TASK ROUTING LOGIC │
│ │
│ 1. Does this task require computer use / local access? │
│ │ │
│ ├─ NO → Bytespace API handles directly │
│ │ (API calls, chat, simple queries) │
│ │ Works even with no daemon online │
│ │ │
│ └─ YES → Route to daemon │
│ │ │
│ ├─ Primary daemon online? → Send to primary │
│ │ │
│ ├─ Fallback daemon online? → Send to fallback │
│ │ │
│ └─ All offline? → Queue task + notify user │
│ Task executes when daemon │
│ comes back online │
│ │
└─────────────────────────────────────────────────────────────┘
Monorepo Structure
bot0/
├── packages/
│ ├── core/ # Shared logic
│ │ ├── src/
│ │ │ ├── agent/ # Agent loop, planner, executor
│ │ │ ├── bytespace/ # Bytespace API client
│ │ │ ├── hub/ # Hub WebSocket client
│ │ │ ├── computer/ # Computer use interface
│ │ │ └── types/ # Shared types
│ │ └── package.json
│ │
│ ├── daemon/ # The brain (npm package)
│ │ ├── src/
│ │ │ ├── index.ts # Entry point
│ │ │ ├── server.ts # Local IPC server
│ │ │ ├── computer/ # Computer use implementation
│ │ │ └── service/ # launchd/systemd integration
│ │ └── package.json
│ │
│ ├── desktop/ # Electron app
│ │ ├── electron/
│ │ │ ├── main.ts # Main process
│ │ │ ├── preload.ts # IPC bridge
│ │ │ └── daemon.ts # Daemon manager (start/stop)
│ │ ├── renderer/ # Next.js UI
│ │ │ ├── app/
│ │ │ └── components/
│ │ └── package.json
│ │
│ └── cli/ # CLI tool (npm package)
│ ├── src/
│ │ ├── commands/
│ │ │ ├── index.ts # Default: open desktop
│ │ │ ├── node.ts # Headless daemon
│ │ │ ├── status.ts
│ │ │ └── run.ts
│ │ └── index.ts
│ ├── bin/
│ │ └── bot0.js
│ └── package.json
│
├── apps/
│ └── hub/ # WebSocket server (Fly.io)
│ ├── src/
│ │ ├── index.ts
│ │ ├── connections.ts
│ │ ├── daemons.ts # Registry & presence
│ │ ├── tasks.ts # Routing & queue
│ │ └── auth.ts # Validate daemon tokens
│ ├── Dockerfile
│ └── fly.toml
│
├── package.json
├── pnpm-workspace.yaml
└── turbo.json
Tech Stack
| Component | Technology | Why |
|---|---|---|
| Monorepo | pnpm + Turborepo | Fast, efficient |
| Language | TypeScript (strict) | Type safety across packages |
| Daemon | Node.js | Same as your existing code |
| Desktop | Electron + Next.js | Cross-platform, React-based |
| CLI | Node.js + Commander | Simple, npm distributable |
| Hub | Node.js + ws | Simple WebSocket server |
| Computer Use | Your existing MLX + nut-tree | 1s per action |
| IPC | Unix socket or local WebSocket | P2P, fast |
| Hub hosting | Fly.io | Persistent connections, global |
| API hosting | Vercel | Your existing setup |
Installation & Distribution
For Users (Desktop)
1. Download from bot0.dev
└─→ bot0-1.0.0.dmg (Mac)
└─→ bot0-1.0.0.exe (Windows)
2. Install and open
└─→ Desktop app starts
└─→ Daemon auto-starts in background (launchd/systemd)
└─→ Onboarding flow
3. Done
└─→ Daemon running in background
└─→ Desktop for UI
└─→ Available via Telegram, Slack, etc.
For Developers (CLI)
bash
# Install CLI $ curl -fsSL https://bot0.dev/install.sh | bash # OR $ npm install -g @bot0/cli # Authenticate $ bot0 login # Run headless daemon (for servers) $ bot0 node # Open desktop app $ bot0
For Servers (Headless)
bash
# On any server/VM you want to add: $ npm install -g @bot0/cli $ bot0 login $ bot0 node --name "cloud-worker-1" ✓ Registered as "cloud-worker-1" ✓ Connected to Hub ✓ Waiting for tasks...
Security Considerations
- Daemon ↔ Desktop: Local IPC only, no network exposure
- Daemon ↔ Hub: Authenticated WebSocket (JWT from Bytespace)
- Hub ↔ Bytespace: API key authentication
- Webhooks: Signature verification (Telegram, Slack, etc.)
- Computer use: Permission requests via macOS/Windows system prompts
Open Questions
- Task queue storage: Redis? PostgreSQL? In-memory with persistence?
- Daemon auto-update: How do headless daemons update themselves?
- Multi-user machines: One daemon per user? Shared daemon?
- Rate limiting: How to prevent abuse via Telegram/Slack?
Next Steps
Phase 1: Foundation
- Monorepo setup
- @bot0/core with Bytespace client
- @bot0/daemon basic agent loop - See Agent Loop
- @bot0/desktop Electron shell + chat UI
- Local IPC between desktop ↔ daemon
Phase 2: Computer Use
- Integrate MLX grounding model
- Screenshot/mouse/keyboard in daemon
- Permission flow in desktop
Phase 3: Hub + Network
- Deploy Hub to Fly.io
- Daemon ↔ Hub WebSocket
- Remote task dispatch
-
bot0 nodeheadless mode
Phase 4: Channels
- Telegram webhook integration
- WhatsApp webhook integration
- Task classification (needs daemon or not?)
Phase 5: Polish
- Onboarding flow
- Auto-updates
- Code signing
- Landing page downloads