🎼 Conductor

Universal task runner & real-time dashboard for developers

Run your entire dev stack — databases, servers, workers — with one command.

Why Conductor?

Starting a dev environment usually means juggling five terminal tabs, a half-remembered shell script, and hoping nobody forgot to start the database first. Conductor replaces that with one declarative YAML file and one command:

conductor run dev

• Dependency-aware — start services in the right order, waits for health checks to pass
• Smart process management — distinguishes between running and healthy; graceful stop with SIGKILL fallback
• Secret-safe — sensitive env vars are masked in logs and UI by default
• Cross-platform — Linux, macOS, and Windows, all first-class
• Shareable — commit .conductor.yml and your whole team gets the same setup

Quick Start

# 1. Clone & install
git clone https://github.com/PhantomDave/conductor.git
cd conductor
bun install

# 2. Link the CLI globally
bun run link:cli

# 3. Create a .conductor.yml in your project
cp .conductor.example.yml .conductor.yml
# — or write one from scratch (see below) —

# 4. Run it
conductor run dev

bun run link:cli symlinks the conductor binary into ~/.bun/bin. If conductor: command not found persists, restart your shell after installing Bun. Prefer not to link globally? Run directly: bun run --cwd packages/cli bin/conductor.ts run dev.

Example .conductor.yml

Root-level commands + profiles that reference them by command_ids:

version: "1"
name: "MyApp Full-Stack"
description: "Local development environment"

base_path: "."
global_env:
  LOG_LEVEL: info

commands:
  - id: postgres
    name: "PostgreSQL"
    run: docker compose up postgres
    healthcheck:
      type: port
      port: 5432
      interval_ms: 1000
      timeout_ms: 30000
      retries: 30

  - id: api
    name: "API Server"
    run: npm run dev
    cwd: ./api
    deps: [postgres]
    healthcheck:
      type: http
      url: "http://localhost:3001/health"
      interval_ms: 500
      timeout_ms: 30000
      retries: 30

  - id: web
    name: "Frontend"
    run: npm run dev
    cwd: ./web
    deps: [api]
    healthcheck:
      type: http
      url: "http://localhost:3000"
      interval_ms: 500
      timeout_ms: 30000
      retries: 30

profiles:
  dev:
    description: "Local development"
    env:
      NODE_ENV: development
      API_URL: "http://localhost:3001"
    command_ids: [postgres, api, web]

Then:

conductor run dev          # starts postgres → api → web, in order
conductor ps               # see what's running (requires API server on :4000)

Configuration Reference

Conductor configs are YAML files starting at the root with two top-level sections:

• commands (array of root-level command definitions) — id is required, name/description/run are required for execution. See CONFIG.md for the full schema.
• profiles (object keyed by profile name) — each has env, description, and command_ids (references to root commands).

CLI Commands

Command	Description
conductor run <profile> [command]	Start a profile's commands in dependency order
conductor configure [profile] [-f]	Auto-compile .env / appsettings.json from .example templates
conductor list [profile]	List profiles or commands within a profile
conductor config validate [file]	Validate a YAML config against the schema
conductor env get <profile> <key>	Show the resolved value a profile's commands will see
conductor env set <profile> <key> <val>	Set a profile env var (same store as the UI's Environment tab)
conductor ps	List all running processes (hits API at :4000)
conductor logs [--follow]	Query or stream logs from the core API (supports filters)
conductor stop <profile>	Gracefully stop all processes in a profile via core API
conductor mcp	Bridge a stdio MCP client to the running core (see below)

Full reference: CLI.md

Health Checks & Status

Conductor tracks process status and health:

Status	Meaning
starting	Process spawned, awaiting health check
running	No explicit healthcheck yet, or polling in progress
stopping	Graceful shutdown in progress
stopped	Exited gracefully (code 0)
failed	Exited with error (code ≠ 0)

Health check types:

Type	Checks
port	TCP connection succeeds (2 s socket timeout)
http	HTTP endpoint responds with status < 500 (2 s fetch timeout)
command	Shell command exits with code 0
none	Just wait for process to spawn (default)

Web Dashboard

Conductor ships a React + Vite + Mantine dashboard:

# Backend API (port 4000)
bun run --cwd packages/core dev

# Dashboard (port 3000)
bun run --cwd packages/ui dev

The dashboard shows live process status, env var management, command library, notifications, and logs. UI LogViewer wiring to SSE is a work-in-progress (server-side SSE stream exists).

Desktop App

Tauri 2 shell with a compiled Bun sidecar binary:

bun run dev:desktop-tauri     # builds sidecar + UI, launches Tauri dev mode
bun run build:desktop-tauri   # produces installers via `tauri build`

The desktop app checks for updates automatically on launch via GitHub Releases. No separate daemon — it runs the engine in-process.

Use with AI agents (MCP)

The core exposes nearly the whole API (not health or the SSE log stream) as 47 MCP tools at /mcp, so an agent can list workspaces, start profiles, read logs and edit config. Requests are accepted from the local machine only. Add it to Claude Code with the HTTP transport, for a core running on port 4000:

claude mcp add --transport http conductor http://localhost:4000/mcp

Or with the stdio bridge, which works for any core, including the desktop app (it finds the app's random port through endpoint.json):

claude mcp add conductor -- conductor mcp

See API.md for the tool list and CLI.md for how the bridge finds the core.

Roadmap

• ✅ Config engine + YAML validation (Zod)
• ✅ Command executor with dependency resolution
• ✅ Health checks (port / http / command) with retries & timeouts
• ✅ Continuous health monitoring — services that crash or go unhealthy are flagged, and recovery is detected on restart
• ✅ CLI (run, configure, list, config validate, env get/set)
• ✅ SQLite persistence (execution history, logs, env vars, audit log)
• ✅ Fastify HTTP API + SSE log stream
• ✅ React + Mantine dashboard (single page, all panels)
• ✅ Desktop app (Tauri 2 + tauri-action, auto-update)
• ✅ Docker Compose import (POST /api/docker%20compose/parse)
• ✅ configure command — compiles .env and appsettings.json from .example templates
• ✅ Process CPU/memory metrics collection (sampled + persisted; API returns real history)
• 🔲 Live dashboard charts for those metrics — collector is wired, nothing in the UI reads it yet
• 🔄 Live log wiring in UI LogViewer via SSE (server-side ready)
• 🔲 Community template registry
• 🔲 Standalone CLI binary distribution (npm, Homebrew)

Project Structure

conductor/
├── packages/
│   ├── core/    Backend engine: config loader, executor, SQLite, Fastify API
│   ├── cli/     `conductor` CLI (Commander v15)
│   ├── ui/      React 19 + Vite + Mantine 9 dashboard
│   └── desktop-tauri/ Tauri shell (sidecar + dashboard, auto-update)
├── docs/        Documentation
├── examples/    Example configs (empty — use .conductor.example.yml or guides)
└── .conductor.example.yml

Contributing

Conductor is fully open source (MIT) and welcomes contributions of all kinds — bug fixes, docs, new examples, or entirely new features. Check the issues tab for good first issue labels, or open a discussion to propose something bigger.

License

MIT — free to use, modify, and distribute.