Flow editor
Flows live on a node graph canvas built on Svelte Flow. Each node opens a config form, validation runs live, and the run panel lights up node states while a run executes.
Open source, MIT
Karakuri is a flow engine and dashboard for your home. Wire triggers, logic, and actions on a canvas, give any node a retry policy, and send a node that still fails down an error branch so the run keeps going.
Works with Home Assistant, openHAB, ESPHome, MQTT, Zigbee2MQTT, and Frigate, and with your other computers: enroll a NAS, a PC, a Mac, or a Raspberry Pi and use it in flows.
If all three attempts fail, the message leaves by the error branch and a notification goes out.
Features
Every node has its own form, and the editor checks the graph while you build it.
Flows live on a node graph canvas built on Svelte Flow. Each node opens a config form, validation runs live, and the run panel lights up node states while a run executes.
I wait 1 s, then 2 s, then 4 s. If the light still does not answer, I take the error branch.
Every node can carry a retry policy. A node that runs out of attempts sends its message out a failure branch, so the run continues. For anything unhandled, a flow can name an error-handler flow.
Example values. Each node gets its own.
Your edits wait in the draft. Deploy makes a numbered version that never changes.
Edits go to a draft. Deploy freezes an immutable numbered version, and triggers arm against it. Restore any earlier version into the draft in one click.
A few more things I keep in my sleeves.
Run the draft from the editor, replay from any node using the last run's outputs, cancel live runs, and re-run the last trigger payload against the deployed graph.
Group nodes into a local subgraph, or promote it to a shared library subflow with declared interface ports.
Any flow exports as a self-contained JSON document with its shared subflows embedded.
JavaScript, Python, or Bash with no filesystem, process, or environment access. HTTP goes through the host under a three-level network policy, and scripts call other nodes through generated functions with completion and hover in the editor.
Integrations
Credentials are encrypted at rest, and every connection shows its live status.
Zigbee2MQTT devices show up after one discovery step.
Dashboards
Lay out panels from web-component widgets: clocks, media players, cameras, charts, buttons, and entity cards with live state and tap-to-toggle. Share a dashboard with users, groups, or the public.
31 bundled CSS themes, including
Some screens only take an image. The built-in renderer makes one from any dashboard.
For devices that only accept images, the built-in renderer turns any dashboard into a picture at the size a URL names: e-ink panels, photo frames, wiki pages, and chat messages. Scheduled renders serve the latest image at a fixed address.
Remote machine agents
Install the Karakuri agent on a laptop, a NAS, a Windows PC, or a Raspberry Pi and enroll it. That machine's commands, files, services, and desktop show up in the flow editor as nodes that run on it, next to your lights and sensors.
When the front door opens late at night, one flow can turn on the hall light, pause the music on the office PC, and lock its screen.
Run a program or a script with whatever interpreter the machine has: Bash, Python, Node, PowerShell, or cmd. Output comes back to the run, and cancelling the run stops the whole process tree.
Read, write, and list files. Watch a directory, or tail a log that keeps its place through rotation and restarts, as triggers that start flows.
Check and control systemd, launchd, and Windows services, and wait to confirm the state they reach. List processes, or start a flow when one starts or stops.
Probe a host or a URL and send HTTP requests from where the agent sits, for devices and services only that network can reach.
Keyboard, mouse, screenshots, windows, the clipboard, notifications, dialogs, media players, and the screen lock, in the session the agent runs in.
Click buttons and menus through the accessibility tree, find a reference image on screen, and wait for a window or control to appear before acting.
Open a page in the machine's browser with instructions and answer buttons, and carry on with the flow once someone picks one.
A one-time join token enrolls the agent, mutual TLS carries every call, and revoking an agent cuts it off. Each agent belongs to whoever enrolled it until they share it, and any node type can be turned off per agent.
Mint a join token under Settings, Agents, then run the command it shows on the machine, as the user the agent should act as. The agent installs itself as that user's service and updates itself after that.
Linux, macOS, Windows, and FreeBSD on amd64 and ARM, including 32-bit Raspberry Pi, or as a container. An agent can do what its account can do; it is not sandboxed, so install it for the account whose access you mean to hand over.
karakuri-agent enroll --server karakuri.example:9443 \
--token <join token> --service
Operations
AI assistants connect over the Model Context Protocol at /mcp to author and deploy flows, read per-node run failures, and manage controls, connections, devices, and dashboards, under the same permissions as the API.
Prometheus /metrics, /health, structured logging, backups, role-based permissions, API keys, a WebSocket event stream, and an interactive API reference at /api/docs.
A service installs newer releases once a day and rolls back if the new version will not start.
Linux and macOS on amd64 and arm64, Windows on amd64, and a Docker image for amd64 and arm64. Written in Go with a Svelte frontend.
Get started
Docker Compose is the easy way. Every option ends with the editor at http://localhost:8080.
1Save this as compose.yaml in an empty directory.
services:
karakuri:
image: grmrgecko/karakuri:latest
container_name: karakuri
restart: unless-stopped
ports:
- "8080:8080" # Web interface and API.
- "9443:9443" # Remote agents dial this port.
volumes:
- karakuri-data:/var/lib/karakuri
- karakuri-config:/etc/karakuri
volumes:
karakuri-data:
karakuri-config:
2Start it, then create your admin account.
docker compose up -d
docker compose exec karakuri \
karakuri user create admin [email protected] <password> --admin
The first start writes a configuration with fresh secrets into the config volume. To update, run docker compose pull and then docker compose up -d.
1Save this as compose.yaml in an empty directory. It runs PostgreSQL beside Karakuri.
services:
karakuri:
image: grmrgecko/karakuri:latest
container_name: karakuri
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
environment:
KARAKURI_DATABASE_TYPE: postgres
KARAKURI_DATABASE_DSN: "host=postgres port=5432 user=karakuri password=${KARAKURI_DB_PASSWORD:?set KARAKURI_DB_PASSWORD in .env} dbname=karakuri sslmode=disable"
ports:
- "8080:8080" # Web interface and API.
- "9443:9443" # Remote agents dial this port.
volumes:
- karakuri-data:/var/lib/karakuri
- karakuri-config:/etc/karakuri
postgres:
image: postgres:17-alpine
container_name: karakuri-postgres
restart: unless-stopped
environment:
POSTGRES_USER: karakuri
POSTGRES_PASSWORD: ${KARAKURI_DB_PASSWORD:?set KARAKURI_DB_PASSWORD in .env}
POSTGRES_DB: karakuri
healthcheck:
test: ["CMD-SHELL", "pg_isready -U karakuri -d karakuri"]
interval: 10s
timeout: 5s
retries: 5
volumes:
- karakuri-postgres:/var/lib/postgresql/data
volumes:
karakuri-data:
karakuri-config:
karakuri-postgres:
2Write a database password to .env, start it, then create your admin account.
echo "KARAKURI_DB_PASSWORD=$(openssl rand -hex 24)" > .env
docker compose up -d
docker compose exec karakuri \
karakuri user create admin [email protected] <password> --admin
Keep .env with the volumes: PostgreSQL keeps the password it first started with.
tar xzf karakuri-<version>.linux-amd64.tar.gz
cd karakuri-<version>.linux-amd64
sudo ./install.sh
sudo karakuri service install
sudo karakuri service start
Archives for every platform are on the releases page.
Then open http://localhost:8080. The documentation covers every install method, MySQL, and configuring the server, and the same guides open in the app under Help.