watchddocker compose for local processes

Run every app of your projects from one Lua config. watchd restarts them when files change or when they crash, starts them in the right order, and lets you control everything from one CLI.

Get started

Install

View on GitHub

🔁

Restarts on file changes

Watches your files with gitignore-style patterns and debouncing, so saving 20 files means one restart.

🛟

Supervises processes

Restart policies with exponential backoff and a retry limit. Stops take down the whole process tree, so go run and npm leave no orphans.

🧭

Dependencies and health checks

The web app waits until the API actually answers on its port, at its URL, or passes a check command.

🗂️

Many projects, one daemon

List everything that's running and control any project or app from anywhere, for example watchd stop shop/worker.

🌙

The config is Lua

Variables, loops, conditionals, env lookups, and hooks that decide whether a change should restart an app.

📺

A live dashboard

watchd ui shows every project and app, with keys to restart, stop, start and follow logs.

watchd is in beta

Every feature works and is covered by tests, but watchd is young and hasn't been used widely yet. Expect rough edges, and the config format or commands may change before version 1.0. What this means · Report a problem

Thirty seconds to running

console

$ cd ~/work/shop
$ watchd up
No watchd.lua found in ~/work/shop or its parents. Let's create one.
  ✓ api  go run .      ./api
  ✓ web  pnpm run dev  ./web
✓ Created ~/work/shop/watchd.lua for project shop with 2 app(s)
shop: started api, web

$ watchd ps
PROJECT  APP  STATE              PID    UPTIME  RESTARTS
shop     api  running (healthy)  41233  8s      0
shop     web  running            41260  7s      0

A typical config:

lua

return {
  name = "shop",
  apps = {
    {
      name = "api",
      cmd = "go run ./cmd/api",
      watch = { "**/*.go" },
      healthcheck = { http = "http://127.0.0.1:8080/health" },
    },
    {
      name = "web",
      cmd = "npm run dev",
      cwd = "./web",
      depends_on = { "api" },
      env = { PORT = 3000 },
    },
  },
}

Any language works, because an app is just a shell command. watchd is a single static binary for Linux and macOS, with no Node.js, Python, Docker or tmux required.