Open source, MIT

Home automation flows that try again, then take the error branch

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.

Turn the gold key on my back and I will run the flow below. The hall light is a little unreliable today.
Karakuri mascot

Hall light when the door opens

Deployed
  1. Front door opensTrigger · Zigbee2MQTT contact sensor Idle
  2. Turn on hall lightHome Assistant · 3 attempts, 1 s delay, ×2 backoff Idle
  3. ok DoneLight is on
    error Notify my phoneNotification service

If all three attempts fail, the message leaves by the error branch and a notification goes out.

Features

A tour of what Karakuri does

Every node has its own form, and the editor checks the graph while you build it.

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.

I wait 1 s, then 2 s, then 4 s. If the light still does not answer, I take the error branch.

Retries and failure routing

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.

  • Max attempts4
  • Delay1 s
  • Backoff×2
  • Delay cap30 s

Example values. Each node gets its own.

Your edits wait in the draft. Deploy makes a numbered version that never changes.

Drafts and deployed versions

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.

Test runs

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.

Subflows

Group nodes into a local subgraph, or promote it to a shared library subflow with declared interface ports.

Export and import

Any flow exports as a self-contained JSON document with its shared subflows embedded.

Sandboxed scripts

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

Talks to the devices you already have

Credentials are encrypted at rest, and every connection shows its live status.

Zigbee2MQTT devices show up after one discovery step.

Dashboards

Panels for the wall tablet, images for everything else

Grid editor and widgets

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

  • Catppuccin
  • Dracula
  • Nord
  • Gruvbox
  • Rosé Pine
  • Tokyo Night
  • Everforest
  • Sonokai
  • Edge

Some screens only take an image. The built-in renderer makes one from any dashboard.

Dashboard renders

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.

  • PNG
  • JPG
  • PDF
  • GIF
  • BMP
  • TIFF

Remote machine agents

Your other computers become nodes

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.

Commands and scripts

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.

Files and logs

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.

Services and processes

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.

From that machine's network

Probe a host or a URL and send HTTP requests from where the agent sits, for devices and services only that network can reach.

The desktop

Keyboard, mouse, screenshots, windows, the clipboard, notifications, dialogs, media players, and the screen lock, in the session the agent runs in.

Apps without an API

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.

Ask a person

Open a page in the machine's browser with instructions and answer buttons, and carry on with the flow once someone picks one.

Enrollment and access

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.

Enroll a machine

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

For the person who runs the server

MCP server

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.

Operations

Prometheus /metrics, /health, structured logging, backups, role-based permissions, API keys, a WebSocket event stream, and an interactive API reference at /api/docs.

Updates itself

A service installs newer releases once a day and rolls back if the new version will not start.

Runs where you are

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

Install it in a few minutes

Docker Compose is the easy way. Every option ends with the editor at http://localhost:8080.

Docker Compose

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.

Compose with PostgreSQL

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.

Linux archive

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.