Conductor

Orchestrate your entire dev environment with a single command.

Conductor is a lightweight, powerful process orchestrator designed for modern development workflows. Start your entire stack—backend, frontend, database, cache, workers—with one command. Manage everything from a beautiful native UI or the terminal.

No Docker. No complexity. Just pure simplicity and power.

Features • Installation • Quick Start • Documentation • Contributing

✨ Features

Core Capabilities

⚡ Instant Setup — Define services in a single YAML file
🚀 Lightning Fast — Start services respecting dependency order; built in pure Go
🎨 Dual Interface — Beautiful CLI dashboard or native desktop GUI
💚 Health Monitoring — HTTP or command-based health verification with visual indicators
📊 Unified Logs — Color-coded, aggregated logs from all services with real-time streaming
🔄 Live Reload — Restart services on-the-fly without stopping others
♻️ Auto-Restart — Configurable restart policies (always, on-failure, never) with exponential backoff
🔍 Auto-Discovery — Scan projects and detect services from package.json, go.mod, Cargo.toml, docker-compose.yml, pyproject.toml
🖥️ UI Management — Add, remove, configure services directly from the desktop app
🌍 Cross-Platform — Linux, macOS, Windows support
📦 Zero Dependencies — Single binary, no external runtime required

Desktop App (v1.1.0)

Scan & Setup — Browse any directory; auto-detect services and dependencies
Visual Dashboard — Real-time status dots, uptime, PID, port monitoring, restart counts
Service Forms — Intuitive UI for creating and managing services with color picker, env vars, depends_on
Smart Logs — Filterable, auto-scrolling, color-coded log viewer with Ctrl+F search and file export
Config Editor — Edit conductor.yaml directly in the app with live validation
Config Hot-Reload — Desktop app detects changes to conductor.yaml and reloads automatically
Port Conflict Detection — Warns before starting if a configured port is already in use
Safe Operations — Confirmation dialogs prevent accidental config changes
Demo Mode — One-click demo project to explore features

📋 Quick Start

1. Try It Immediately

# Generate demo services
conductor demo
conductor up

# Or start with your existing project
conductor init       # creates conductor.yaml
conductor up         # starts everything

2. Using the Desktop App

conductor-desktop

On Linux, Conductor integrates with your desktop environment—search for it in rofi, dmenu, or your app launcher.

3. Basic Config Example

name: my-fullstack-app

services:
  frontend:
    cmd: npm run dev
    dir: ./frontend
    port: 3000
    color: cyan
    env:
      NODE_ENV: development
    depends_on:
      - api
    health:
      url: http://localhost:3000
      interval: 5s

  api:
    cmd: go run ./cmd/server
    dir: ./backend
    port: 8080
    color: green
    depends_on:
      - db
    health:
      cmd: curl -f http://localhost:8080/health

  db:
    cmd: postgres -D /usr/local/var/postgres
    port: 5432
    color: yellow
    health:
      cmd: pg_isready -h localhost

🛠️ Installation

From Pre-built Binaries

Download the latest release for your platform from Releases.

# Extract and place in your PATH
tar xzf conductor-linux-x64.tar.gz
sudo mv conductor /usr/local/bin/
sudo mv conductor-desktop /usr/local/bin/

From Source

git clone https://github.com/VendavalSC/conductor
cd conductor

# CLI only
make build
sudo cp bin/conductor /usr/local/bin/

# Full installation (CLI + Desktop + Linux desktop entry)
make install-all

Requirements

CLI: Go 1.22+ or pre-built binary
Desktop App: Requires GTK3 on Linux; macOS and Windows bundles everything

Linux Dependencies (GTK3)

# Fedora / RHEL / CentOS
sudo dnf install webkit2gtk3-devel

# Debian / Ubuntu
sudo apt-get install libwebkit2gtk-4.0-dev

# Arch
sudo pacman -S webkit2gtk

📖 Complete Configuration Reference

Top-Level Config

name: my-app          # Project name (required)

Service Configuration

Key	Type	Description
`cmd`	string	Command to run (supports shell features like pipes)
`dir`	string	Working directory (relative to conductor.yaml location)
`port`	integer	Exposed port (appears in dashboard)
`color`	string	Terminal color: `cyan`, `green`, `yellow`, `red`, `magenta`, `blue`, `orange`, `purple`
`env`	object	Environment variables (inherited by child process)
`depends_on`	array	Service dependencies (startup order)
`health`	object	Health check configuration
`restart`	string	Restart policy: `never` (default), `on-failure`, `always`
`max_restarts`	integer	Maximum restart attempts (`0` = unlimited, default: `0`)

Restart Policies

services:
  web:
    cmd: npm run dev
    restart: on-failure   # restart only if process exits non-zero
    max_restarts: 5       # give up after 5 attempts (exponential backoff: 1s, 2s, 4s…)

  worker:
    cmd: ./worker
    restart: always       # restart even on clean exit
    max_restarts: 0       # unlimited restarts

  db:
    cmd: postgres
    restart: never        # default — don't restart

Health Check Configuration

HTTP Health Check

health:
  url: http://localhost:3000
  interval: 5s        # check frequency
  timeout: 3s         # request timeout
  retries: 3          # consecutive failures before marking unhealthy

Command Health Check

health:
  cmd: pg_isready -h localhost
  interval: 5s
  retries: 3

🎮 CLI Commands

Command	Description	Example
`conductor init`	Create template config	`conductor init`
`conductor demo`	Create demo config	`conductor demo`
`conductor up`	Start all services	`conductor up`
`conductor up -c custom.yaml`	Use custom config	`conductor up -c config/dev.yaml`
`conductor status`	Show service status	`conductor status`
`conductor logs`	Stream all logs	`conductor logs`
`conductor logs <service>`	Stream service logs	`conductor logs api`
`conductor restart <service>`	Restart a service	`conductor restart frontend`
`conductor down`	Stop all services	`conductor down`
`conductor version`	Show version	`conductor version`

TUI Keyboard Shortcuts

Key	Action
`↑` / `↓` or `k` / `j`	Navigate services
`Enter` or `s`	Start/stop service
`r`	Restart service
`l`	View service logs
`q`	Quit (stops all services)
`?`	Show help

🏗️ How It Works

Config Loading — Reads conductor.yaml from current directory or walks up the tree
Dependency Resolution — Topological sort determines startup order
Process Spawning — Executes commands via sh -c (supports pipes, redirects, complex syntax)
Log Aggregation — Combines stdout/stderr with per-service color coding
Health Monitoring — Periodically checks health endpoints (HTTP or command)
Graceful Shutdown — SIGTERM → 5s wait → SIGKILL if still running

📊 Comparison with Alternatives

Feature	Conductor	Docker Compose	Foreman	Overmind
Configuration	YAML	YAML	Procfile	Procfile
Desktop GUI	✅ Native	❌	❌	❌
Auto-detect Services	✅	❌	❌	❌
Health Checks	✅ HTTP + Cmd	✅	❌	❌
Service Dependencies	✅	✅	❌	❌
Docker Required	❌	✅	❌	❌
Single Binary	✅	❌	✅	✅
Real-time Logs	✅	✅	✅	✅

🗺️ Project Roadmap

🏢 Project Structure

conductor/
├── cmd/
│   ├── conductor/              # CLI entry point
│   └── conductor-desktop/      # Desktop app entry point
├── internal/
│   ├── cli/                    # CLI commands (Cobra)
│   ├── config/                 # YAML config parsing
│   ├── health/                 # Health check engine
│   ├── logmux/                 # Log aggregation & formatting
│   ├── process/                # Process lifecycle
│   ├── tui/                    # Terminal UI (Bubble Tea)
│   └── version/                # Version management
├── desktop/
│   ├── app.go                  # Wails backend
│   ├── config_ops.go           # Config operations
│   ├── scanner.go              # Project auto-detection
│   └── frontend/               # React + TypeScript
├── assets/                     # Icons, desktop entry
├── Makefile                    # Build automation
├── go.mod / go.sum             # Go dependencies
├── .goreleaser.yml             # Release configuration
└── conductor.example.yaml      # Example configuration

🤝 Contributing

We welcome contributions! Whether it's bug reports, feature suggestions, or code contributions, please read CONTRIBUTING.md first.

Quick Start for Contributors

git clone https://github.com/VendavalSC/conductor
cd conductor

# Run tests
make test

# Build and test locally
make build
./bin/conductor up

# Format code
make fmt

# Run linter
make lint

📜 License

Conductor is distributed under the MIT License. See LICENSE for details.

💡 Use Cases

Full-Stack Development

services:
  frontend: { cmd: npm run dev, dir: ./frontend, port: 3000 }
  api: { cmd: go run ./cmd/api, dir: ./backend, port: 8080 }
  db: { cmd: postgres ... }

Microservices

services:
  auth-service: { cmd: npm start, port: 3001 }
  user-service: { cmd: go run ./main.go, port: 3002 }
  order-service: { cmd: python app.py, port: 3003 }

Python/Django Stack

services:
  web: { cmd: python manage.py runserver, port: 8000 }
  celery: { cmd: celery -A config worker }
  redis: { cmd: redis-server, port: 6379 }
  postgres: { cmd: postgres ... }

🆘 Troubleshooting

Config Not Found

Conductor looks for conductor.yaml in the current directory and walks up the tree. Make sure the file exists or use -c path/to/config.yaml.

Health Check Failing

Check that your service is actually listening on the configured port/endpoint. Use conductor logs <service> to debug.

Desktop App Not Launching

On Linux, ensure GTK3 development libraries are installed. See Installation for platform-specific requirements.

Permission Denied (Linux Desktop)

chmod +x /usr/local/bin/conductor-desktop

📧 Support

Have questions? Found a bug? Open an issue or start a discussion.

Made with ❤️ by VendavalSC

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
assets		assets
desktop		desktop
internal		internal
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
conductor.example.yaml		conductor.example.yaml
go.mod		go.mod
go.sum		go.sum
test-conductor.yaml		test-conductor.yaml

Folders and files

Latest commit

History

Repository files navigation