# Bubbaloop

> Open-source Hardware AI agent. Single Rust binary for cameras, sensors, robots, and IoT fleets — orchestrated by AI agents with memory and real-time telemetry. Runs on Jetson, Raspberry Pi, any Linux.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kornia-bubbaloop`
- **Verified:** Pending review
- **Seller:** [kornia](https://agentstack.voostack.com/s/kornia)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [kornia](https://github.com/kornia)
- **Source:** https://github.com/kornia/bubbaloop
- **Website:** https://www.kornia.org/bubbaloop/

## Install

```sh
agentstack add mcp-kornia-bubbaloop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🦐 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

```bash
# 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).

```bash
# 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

```bash
# 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

```bash
# 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.

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

```bash
# 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.

```bash
# 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:

```bash
# 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](https://github.com/kornia/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

```bash
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

```bash
# 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

```bash
# 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 ` for errors
- **Auth failed**: Run `bubbaloop login --status` to check credentials

## Documentation

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

## License

Apache-2.0

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kornia](https://github.com/kornia)
- **Source:** [kornia/bubbaloop](https://github.com/kornia/bubbaloop)
- **License:** Apache-2.0
- **Homepage:** https://www.kornia.org/bubbaloop/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kornia-bubbaloop
- Seller: https://agentstack.voostack.com/s/kornia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.