Bubbaloop

"Shrimp-fried cameras, shrimp-grilled sensors, shrimp-sauteed robots..." — Bubba, on all the ways to talk to your hardware 🦐

The open-source Hardware AI agent. Talk to your cameras, sensors, and robots in natural language. Manage federated IoT/robotics fleets and automate physical systems — all from a single 13 MB Rust binary.

Why Bubbaloop?

AI agents revolutionized software engineering. Bubbaloop brings that same power to hardware.

	General AI Agents	Bubbaloop
Focus	Software tasks, coding, browsing	Cameras, sensors, robots, IoT
Runtime	TypeScript / ~200 MB	Rust / ~13 MB
Data plane	None	Zenoh (zero-copy pub/sub)
Hardware	None	Self-describing sensor nodes
Runs on	Desktop / cloud	Jetson, RPi, any Linux ARM64/x86
MCP role	Client (consumes tools)	Server (47 tools, 3-tier RBAC)
Scheduling	Always-on LLM (~$5-10/day)	Offline Tier 1 + LLM Tier 2 (~$0.05/day)

Quick Install

# One-line install (Linux x86_64/ARM64)
curl -sSL https://github.com/kornia/bubbaloop/releases/latest/download/install.sh | bash
source ~/.bashrc

# Verify
bubbaloop status

What Gets Installed

Component	Description
zenohd	Pub/sub router on port 7447
zenoh-bridge-remote-api	WebSocket bridge on port 10001
bubbaloop	Single ~13 MB binary: CLI + daemon + MCP server
Dashboard	Web UI at http://localhost:8080

All run as systemd user services with autostart enabled.

Login & Authentication

Bubbaloop supports three providers — Gemini (recommended for new users), Claude, and Ollama (local).

# Option 1 (Recommended): Gemini — free tier, strong vision support
export GEMINI_API_KEY=...           # from https://aistudio.google.com/apikey
# or write the key to ~/.bubbaloop/gemini-key

# Option 2: Claude API Key (pay-as-you-go)
bubbaloop login
# → Choose [1], paste your key from console.anthropic.com

# Option 3: Claude Subscription (Pro/Max/Team)
claude setup-token    # Run in Claude Code CLI first
bubbaloop login
# → Choose [2], paste the sk-ant-oat01-* token

# Option 4: Ollama — fully local, no cloud bill
ollama serve          # in a separate terminal

# Check auth status (shows all configured providers)
bubbaloop login --status

# Remove Claude credentials (Gemini/Ollama have no stored secret)
bubbaloop logout

Basic Usage

# Check system status
bubbaloop status

# Start daemon (runs agent runtime + MCP server + node manager)
bubbaloop up

# Talk to your hardware (Gemini by default; agents run daemon-side)
bubbaloop agent chat "What sensors do I have?"
bubbaloop agent chat                   # Interactive REPL (Ctrl-C cancels the in-flight turn)
bubbaloop agent chat -a camera-expert "describe what the terrace camera sees"
bubbaloop agent list                   # Show running agents + models

# Or open the dashboard's Chat tab in a browser — same agent runtime,
# rich tool-call traces, and image-in-chat when the agent calls grab_frame.

# System diagnostics with auto-fix
bubbaloop doctor --fix

# Node management
bubbaloop node list
bubbaloop node add user/repo          # Add from GitHub
bubbaloop node build my-node          # Build
bubbaloop node start my-node          # Start service
bubbaloop node logs my-node -f        # Follow logs

Node Lifecycle

# 1. Create a new node (generates SDK-based scaffold)
bubbaloop node init my-sensor --node-type rust
# Edit src/main.rs — implement Node trait (init + run)
# The SDK handles Zenoh session, health, schema, config, shutdown

# 2. Register with daemon
bubbaloop node add ./my-sensor

# 3. Build
bubbaloop node build my-sensor

# 4. Install as systemd service
bubbaloop node install my-sensor

# 5. Start
bubbaloop node start my-sensor

# 6. View logs
bubbaloop node logs my-sensor

YAML Skills (Zero-Code Sensors)

Skills are declarative YAML configs that map to nodes. Drop a YAML file in ~/.bubbaloop/skills/ and bubbaloop up auto-installs the driver node and starts it.

# ~/.bubbaloop/skills/front-camera.yaml
name: front-door
driver: rtsp
config:
  url: rtsp://192.168.1.100/stream

# Load all skills, auto-install drivers, start nodes
bubbaloop up

AI Agent Integration (MCP)

Bubbaloop includes an MCP (Model Context Protocol) server — the sole control interface for AI agents. The daemon starts it automatically on port 8088.

# MCP over HTTP (daemon mode, auto-started on port 8088)
bubbaloop daemon

# MCP over stdio (no auth needed, spawns own Zenoh session)
bubbaloop mcp --stdio

Claude Code setup (one-time): The project .mcp.json uses ${BUBBALOOP_MCP_TOKEN} for auth. Export the token before starting Claude Code:

# Add to ~/.bashrc or ~/.zshrc
export BUBBALOOP_MCP_TOKEN=$(bubbaloop mcp --token)

Available MCP tools:

Tool	Description
node_list	List all nodes with status
get_node_manifest	Get a node's capabilities and topics
send_command	Send a command to a node
install_node / uninstall_node	Install or remove nodes
node_start / node_stop	Control node lifecycle
node_logs	Read node service logs
discover_nodes	Fleet-wide manifest discovery
query_zenoh	Query any Zenoh key expression

47 MCP tools + agent-internal tools. Configure Claude Code via .mcp.json (already in project root).

Agent-internal tools (daemon-side only, not exposed via MCP): grab_frame (Zenoh-query a camera node for one JPEG → fed to a vision-capable provider), memory_search, memory_forget, schedule_task, create_proposal, read_file, write_file, run_command, publish_to_topic.

Architecture

                    ┌──────────────────────────────────┐
                    │   AI Agent (Gemini/Claude via MCP)│
                    │   http://127.0.0.1:8088/mcp      │
                    └──────────────┬───────────────────┘
                                   │
Dashboard (React) ─┬─ WebSocket ───┤─── Zenoh pub/sub
CLI ───────────────┘               │
                                   │
Daemon ────────────────────────────┤
  ├─ Node Manager (lifecycle)      │
  ├─ MCP Server (47 tools)         │
  ├─ Telemetry Watchdog            │
  ├─ Agent Runtime (multi-agent)   │
  └─ Systemd D-Bus (zbus)         │
                                   │
Nodes (self-describing) ───────────┘
  ├─ rtsp-camera            Rust    [H264 video, SHM raw frames]
  ├─ camera-object-detector Python  [YOLO11 detection on SHM frames]
  ├─ camera-vlm             Python  [VLM scene description (planned)]
  ├─ system-telemetry       Python  [CPU, memory, disk, network]
  ├─ network-monitor        Python  [HTTP, DNS, ping health checks]
  ├─ openmeteo              Python  [weather: current, hourly, daily]
  └─ custom...              Rust/Py [your node here]

The daemon hosts the agent runtime (multi-agent Zenoh gateway) alongside the MCP server. Agents are configured via ~/.bubbaloop/agents.toml with per-agent identity and memory in ~/.bubbaloop/agents/{id}/. The CLI is a thin Zenoh client — all LLM processing runs daemon-side.

Per-agent features:

• Soul: identity.md (personality) + capabilities.toml (model, heartbeat). Hot-reload on file change.
• 4-Tier Memory: World State (live SQLite, sensor-derived) → RAM (current turn) → NDJSON (episodic, BM25 search) → SQLite (beliefs, jobs, proposals).
• Adaptive Heartbeat: Arousal-based decay — active agents check in frequently, idle agents stay quiet.
• Telemetry Watchdog: CPU/RAM/disk monitoring with circuit breakers and 5 severity levels.

Node Contract

Every node is self-describing with standard queryables:

{node}/schema      → Protobuf FileDescriptorSet (binary)
{node}/manifest    → Capabilities, topics, commands (JSON)
{node}/health      → Status and uptime (JSON)
{node}/config      → Current configuration (JSON)
{node}/command     → Imperative actions (JSON request/response)

AI agents discover nodes via bubbaloop/**/manifest wildcard query, then interact through commands and data subscriptions.

Available Nodes

Official nodes live in bubbaloop-nodes-official. Install any node with bubbaloop node add.

Sensors

Node	Type	Description	Topics
rtsp-camera	Rust	RTSP camera capture with hardware H264 decode via GStreamer	camera/{name}/compressed (global), camera/{name}/raw (SHM local)
system-telemetry	Python	CPU, memory, disk, network, and load metrics via psutil	system-telemetry/metrics
network-monitor	Python	HTTP, DNS, and ICMP ping health checks	network-monitor/status
openmeteo	Python	Open-Meteo weather data (current, 48h hourly, 7-day daily)	weather/current, weather/hourly, weather/daily

Processors

Node	Type	Description	Topics
camera-object-detector	Python	YOLO11 object detection on raw camera frames (SHM)	Subscribes {name}/raw (local), publishes {name}/detections
camera-vlm	Python	Vision language model scene description on camera frames (SHM)	Subscribes {name}/raw (local), publishes {name}/description

All topics are prefixed with bubbaloop/global/{machine_id}/ (network-visible) or bubbaloop/local/{machine_id}/ (SHM-only).

Development

git clone https://github.com/kornia/bubbaloop.git
cd bubbaloop
pixi install
pixi run build     # Build all
pixi run test      # Run tests
pixi run daemon    # Run daemon
pixi run dashboard # Run web dashboard

Development note: Linux + systemd is the supported production path. In Docker or other environments without D-Bus/systemd, the daemon falls back to a native process supervisor intended for development only. That fallback does not provide journalctl-backed logs or full systemd parity.

Service Management

# View all services
systemctl --user list-units 'bubbaloop-*'

# Restart daemon
systemctl --user restart bubbaloop-daemon

# View logs
journalctl --user -u bubbaloop-daemon -f

These service-management commands apply to the systemd backend on Linux. They do not apply to the development fallback used in Docker/non-systemd environments.

Troubleshooting

# Quick diagnostics
bubbaloop doctor

# Auto-fix common issues
bubbaloop doctor --fix

# JSON output for scripting
bubbaloop doctor --json

Common issues:

• Zenoh timeout: Check pgrep zenohd, restart if missing
• Build fails: Check bubbaloop node logs <name> for errors
• Auth failed: Run bubbaloop login --status to check credentials

Documentation

• Quickstart: See docs/getting-started/quickstart.md
• Agent guide: See docs/agent-guide.md for multi-agent setup and MCP tools
• Architecture: See ARCHITECTURE.md for design decisions
• Roadmap: See ROADMAP.md for what's next
• Coding standards: See CLAUDE.md for conventions
• CLI reference: bubbaloop --help or bubbaloop node --help

License

Apache-2.0