---
title: bbuilder host
emoji: 🧩
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
short_description: Hosting for Nerimity bots built in bbuilder
---

# bbuilder host

Runs and supervises Nerimity bots created in the [bbuilder](https://github.com/) desktop app —
a Scratch-style block editor that generates `@nerimity/nerimity.js` bots.

## What it does

- Accepts a generated bot bundle from the desktop app and runs it as a Node process
- Keeps several bots alive at once, restarting them with backoff when they crash
- Streams logs and block-level error events back to the editor
- Persists bots to a **private** dataset so they survive Space restarts
- Self-pings `/health` every 5 minutes so the Space doesn't go to sleep

## API

Everything under `/api/` requires the `X-BB-Key` header to match the `APP_KEY` secret.
`/health` is open and reports node version, store status and per-bot status.

| Method | Route | Purpose |
|---|---|---|
| GET | `/health` | liveness + bot summary (open) |
| GET | `/api/bots` | list bots |
| POST | `/api/bots/{id}/deploy` | upload bundle (multipart) |
| POST | `/api/bots/{id}/start\|stop\|restart` | lifecycle |
| GET | `/api/bots/{id}/logs?since=N` | log history |
| WS | `/api/bots/{id}/stream?key=…` | live logs + block events |
| DELETE | `/api/bots/{id}` | remove |

## Configuration

Secrets: `APP_KEY` (control-API key), `HF_TOKEN` (write, for the private store).
Variables: `BB_DATASET`, `BB_SELF_URL`.

Bot subprocesses are spawned with `HF_TOKEN` and `APP_KEY` stripped from their environment —
a bot only ever sees its own `NERIMITY_TOKEN`.