How Bees works under the hood

Description and use

Bees is an open‑source desktop app that runs a team of AI agents locally. The article explains its multi‑process architecture, tool security, recovery mechanisms, and local model integration, enabling developers to read, debug, and extend the codebase.

Problem

Understanding the internal architecture and workflow of the Bees desktop app to enable developers to read, modify, and contribute to the codebase.

Outcome

The article demystifies Bees’ architecture, revealing how it orchestrates multiple processes, secures tool execution, recovers from crashes, and integrates local models, thereby equipping developers to read, debug, and extend the codebase.

Workflow

• Launch Tauri app → show splash screen → call ensure_dsh_runtime
• Start Temporal dev server on random loopback port with SQLite persistence
• Start bundled Node 24 runtime (dsh-runtime/start.mjs) on second loopback port with fresh token
• Wait for /healthz, then point webview to runtime URL
• Rust side polls /healthz every 2s, restarts splash on timeout
• Node runtime serves UI and runs DSH plugins
• Temporal drives work items through stages, each stage runs as a fresh agent session in its own run folder
• Agent-runtime checks tool calls, enforces path restrictions and approvals
• RecoveryToolContext handles interrupted tool calls based on REPEATABLE_TOOLS list
• MCP servers managed per row in bees-stage1.db, with credential store in DSH
• Local models run via llama-server with context window sizing based on GGUF header
• Optional Bees Cloud sync uploads organization data but keeps files and credentials local

Evidence

Bees is an open source desktop app that runs a team of AI agents on your own computer.

Source

When the window opens, it shows a splash screen (src/entry.ts, under 40 lines) and calls one Tauri command, ensure_dsh_runtime.

Source

The Rust side keeps polling /healthz every two seconds. If the runtime stops answering for about 30 seconds, it sends the window back to the splash, which starts a new one.

Source

Agents that edit shared files go through a lock tool. docs/file-access.md covers it.

Source

recoveryToolContext in agent-runtime.js sorts the calls. A fixed list, REPEATABLE_TOOLS, holds the calls that are safe to repeat.

Source

Local models run on llama.cpp's llama-server, which ships in llama-runtime/.

Source