Getting started

Flowbun runs on Bun. Clone the repository and install:

git clone https://github.com/aquarat/flowbun
cd flowbun
bun install

Point it at your Home Assistant instance with a .env file in the repo root:

HASS_BASE_URL=http://homeassistant.local:8123
HASS_TOKEN=<a long-lived access token>

Run the runtime

bun run coordinator

This typechecks every flow in data/wiring/, then spawns one flow-host child process per flow. Each flow-host runs one Worker per block and holds that flow’s single Home Assistant connection.

Saving a file under data/blocks/ or data/wiring/ triggers a debounced, typecheck-gated reload. If the typecheck fails, the running flow is left completely alone.

Run the editor

In a second terminal:

bun run editor

Open http://localhost:4200. The editor is a pure websocket client of the coordinator — drag nodes, draw wires, edit block source in Monaco with live tsc errors, and watch structured logs per node.

Dry-run by default

@hass/action defaults to dry-run: it logs the exact service call it would have made instead of making it. Set FLOWBUN_DRY_RUN=false when you’re ready for real writes, or override per node with "dryRun": false in that node’s wiring config while everything else stays safe.

Next steps

• Blocks — write your first typed block.
• Wiring — connect blocks into a flow.
• Deploying with Docker — run it as a container.