# DEV RIG
Local development orchestrator with built-in OpenTelemetry. Define your
services in a single TOML file — devrig starts them in dependency order,
multiplexes logs, manages ports, collects traces/metrics/logs, and tears
everything down cleanly on Ctrl+C.
## Dashboard
devrig includes a built-in observability dashboard that receives OpenTelemetry
data from your services in real time.
Drill into any trace to see the full span waterfall across services:
Browse and search application logs with severity filtering:
Explore metrics with sparkline cards and expandable time-series charts:
## Install
**Shell installer** (recommended — Linux/macOS):
```bash
**PowerShell installer** (Windows):
```powershell
These installers include a built-in updater — run `devrig update` to get the
latest version.
**cargo binstall** (prebuilt binary, no updater):
```bash
cargo binstall devrig
```
**From source:**
```bash
cargo install devrig
```
## Quickstart
```bash
devrig init && devrig start
```
## Minimal example
```toml
# devrig.toml
[project]
name = "myapp"
[dashboard]
[services.api]
command = "cargo watch -x run"
port = 3000
[services.web]
command = "npm run dev"
port = 5173
depends_on = ["api"]
```
Save as `devrig.toml` in your project root, then run `devrig start`.
The dashboard opens at `http://localhost:4000`.
## Commands
| `devrig start` | Start all services in dependency order |
| `devrig stop` | Stop all running services gracefully |
| `devrig delete` | Stop services and remove all `.devrig/` state |
| `devrig ps` | Show status of services in the current project |
| `devrig init` | Generate a starter `devrig.toml` for your project |
| `devrig doctor` | Check that external dependencies are installed |
| `devrig validate` | Validate the configuration file |
| `devrig logs` | Show and filter service logs |
| `devrig env` | Show resolved environment variables for a service |
| `devrig exec` | Execute a command in a docker container |
| `devrig query` | Query traces, logs, and metrics from the OTel collector |
| `devrig cluster` | Manage the k3d cluster (create/delete/kubeconfig) |
| `devrig kubectl` | Proxy to kubectl with devrig's isolated kubeconfig |
| `devrig update` | Update devrig to the latest version |
| `devrig completions` | Generate shell completions |
### Global flags
| `-f <path>` | Use a specific config file |
## How it works
1. **Parse** — reads `devrig.toml` (or walks up to find one), validates in two
phases: TOML deserialization, then semantic checks (missing deps, duplicate
ports, cycles).
2. **Resolve** — builds a dependency graph with `petgraph` and topologically
sorts it. Docker containers, k3d cluster deployments, and services can all
depend on each other. Auto-ports are assigned by binding ephemeral OS ports.
3. **Docker** — pulls and starts Docker containers for databases, caches, and
other infrastructure. Supports health checks, init commands, and volume
mounts.
4. **Cluster** — optionally creates a k3d cluster, deploys manifests, and
installs Helm chart addons with port forwarding.
5. **Supervise** — each service runs under a supervisor that captures
stdout/stderr, restarts on failure with exponential backoff, and responds to
cancellation.
6. **Observe** — a built-in OTel collector receives traces, metrics, and logs
over OTLP (HTTP :4318 / gRPC :4317) and serves them to the dashboard and
CLI query commands.
7. **Dashboard** — an embedded SolidJS app on :4000 provides real-time views
of service status, traces, logs, and metrics.
8. **Shutdown** — Ctrl+C triggers graceful shutdown: SIGTERM to process groups,
grace period, then SIGKILL. Containers and state are cleaned up.
## Tech stack
- **Rust** with Tokio async runtime
- **clap** for CLI parsing
- **petgraph** for dependency resolution
- **serde** + **toml** for configuration
- **bollard** for Docker container management
- **tonic** + **opentelemetry-proto** for OTLP ingest
- **axum** for the dashboard API and WebSocket server
- **rust-embed** for compiled-in frontend assets
- **miette** / **thiserror** / **anyhow** for error reporting
- **SolidJS** + **Vite** + **Tailwind v4** for the dashboard
- **Kobalte** for accessible UI primitives
## Documentation
- [Configuration reference](docs/guides/configuration.md)
- [Architecture overview](docs/architecture/overview.md)
- [Architectural decision records](docs/adr/)
- [Contributing](docs/guides/contributing.md)
## License
MIT — see [LICENSE](LICENSE) for details.