sparky-bonzai-bridge

An MCP server that lets the small model in the BonzAI app on an iPhone or iPad hand work to Sparky, an OpenClaw agent on a home PC.

The phone model (Bonsai 8B, fully on-device) handles quick, private work. When a request needs your own data, tools, or a long run, it calls sparky_ask, and Sparky does the work on the PC with his memory, files and GPU.

flowchart LR
  subgraph Phone["iPhone / iPad — BonzAI"]
    K["Bonsai 8B<br/>(on-device)"]
  end
  subgraph PC["Home PC — WSL Ubuntu"]
    B["sparky-bonzai-bridge<br/>127.0.0.1:8795"]
    G["OpenClaw gateway"]
    S["Sparky agent<br/>local LLM + tools + memory"]
    W[("workspace/<br/>inbox · outbox")]
  end
  K -- "MCP over HTTPS<br/>(Tailscale, bearer token)" --> B
  B -- "openclaw agent" --> G --> S
  B -- "notes / messages" --> W
  S -- "reads / writes" --> W

What it gives the phone

Why six small tools: the model calling them is a 1-bit 8B running on a phone, and fewer, plainer tools make it more reliable. See docs/on-device-models.md for what the phone model is actually good at and where the split between phone and PC should fall.

Related MCP server: Machina

Quick start

Requirements: WSL2 with systemd, Node 24+, a working OpenClaw install, and Tailscale on the Windows host.

git clone https://github.com/Applied-AI-Solutions-hub/sparky-bonzai-bridge.git ~/projects/sparky-bonzai-bridge
cd ~/projects/sparky-bonzai-bridge
npm ci
cp .env.example .env                                  # optional; defaults are sensible
npm run device -- add iphone --label Kit              # prints this device's token once
./deploy/install.sh                                   # systemd user service

Then, in Windows PowerShell:

tailscale serve --bg --https 8795 http://127.0.0.1:8795

In BonzAI, add an MCP server with URL https://<machine>.<tailnet>.ts.net:8795/mcp and header Authorization: Bearer <token>. Paste the system prompt from bonzai/system-prompt.md.

Full walkthrough, including the restricted OpenClaw agent and migrating from the old sparky-mcp: docs/setup.md.

Documentation

• docs/setup.md: install, OpenClaw agent, Tailscale, BonzAI, migration

• docs/architecture.md: components, request flows, design decisions

• docs/on-device-models.md: what the phone model does and what Sparky does

• SECURITY.md: trust boundaries and threat model

• openclaw/skills/bonzai-mailbox: the skill that teaches Sparky the mailbox

Development

npm run check      # typecheck + tests
npm start          # run in the foreground

Node 24 runs the TypeScript sources directly (type stripping), so there is no build step. Tests use a fake openclaw binary (tests/fixtures/fake-openclaw.mjs) and a real MCP client, so they do not touch a live agent.

License

MIT