devx

devx is a single-binary, cross-platform dev orchestrator for any repo. Define your services and dependencies once in devx.yaml, then spin up identical environments with one command — locally, in CI, or on Kubernetes.

devx up          # start everything
devx status      # see running services + browser links
devx logs api    # tail logs
devx down        # tear down

Installation

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/dever-labs/dever/main/scripts/install.sh | sh

Windows (PowerShell)

iwr https://raw.githubusercontent.com/dever-labs/dever/main/scripts/install.ps1 | iex

npm

npm install -g @dever-labs/devx

Homebrew

brew tap dever-labs/tap https://github.com/dever-labs/homebrew-tap
brew install devx

Chocolatey / WinGet

choco install devx
winget install dever-labs.devx

Pre-built binaries for all platforms are also available on the Releases page — download, make executable, and place on your PATH. See docs/install.md for all methods including step-by-step manual setup.

Quickstart

devx init               # scaffold a starter devx.yaml
# edit devx.yaml to match your repo
devx up                 # start services + telemetry stack

After startup, devx prints the URLs of every published service:

Environment is up

Available services:
  Api      http://localhost:8080
  Grafana  http://localhost:54231

Commands

Command	Description
devx init	Scaffold a starter devx.yaml in the current directory
devx setup	Install required tools and run host-side setup steps
devx up	Start all services for the active profile
devx down	Stop and remove containers
devx status	Show running containers, state, and published ports
devx logs [service]	Stream logs from one or all services
devx exec <service> -- <cmd>	Run a command inside a running service
devx doctor	Check runtime and tool prerequisites
devx validate	Validate devx.yaml schema and configuration
devx render compose	Print the generated Docker Compose file
devx render k8s	Render Kubernetes manifests from a profile
devx lock update	Resolve and pin image digests to devx.lock

Flags

devx setup

• --fix — install missing tools and re-run runOnce steps
• --json — emit results as JSON (AI/CI friendly)

devx doctor

• --fix — install missing tools declared in the tools block
• --json — emit report as JSON

devx validate

• --file <path> — path to devx.yaml (default: ./devx.yaml)

devx up

• --profile <name> — select a profile (default: defaultProfile in devx.yaml)
• --build — rebuild images before starting
• --pull — always pull latest images
• --no-telemetry — skip the built-in observability stack

devx down

• --volumes — also remove named volumes

devx logs

• --follow — stream live
• --since <duration> — e.g. 10m, 1h
• --json — emit each line as a JSON object

devx render compose

• --write — write output to .devx/compose.yaml instead of stdout
• --no-telemetry — exclude telemetry services

devx render k8s

• --profile <name> — profile to render
• --namespace <ns> — Kubernetes namespace
• --write — write to .devx/k8s.yaml

devx doctor

• --fix — install missing tools and attempt to fix detected issues
• --json — emit report as JSON

Tools and setup

devx can install required SDKs and run host-side setup steps before you start containers.

Declaring required tools

Add a tools block to devx.yaml. devx checks each tool with its check command and installs it using the platform-appropriate install command when devx setup --fix or devx doctor --fix is run.

tools:
  - name: node
    version: "20"
    check: "node --version"
    install:
      windows: "winget install OpenJS.NodeJS.LTS"
      macos: "brew install node@20"
      linux: "curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - && apt-get install -y nodejs"

  - name: dotnet
    version: "8"
    check: "dotnet --version"
    install:
      windows: "winget install Microsoft.DotNet.SDK.8"
      macos: "brew install dotnet@8"
      linux: "wget https://dot.net/v1/dotnet-install.sh -O install.sh && bash install.sh --version 8.0"

Declaring setup steps

Add a setup block to devx.yaml for host-side commands that run after tools are installed. Steps with runOnce: true are skipped on subsequent runs if their command hasn't changed (tracked in .devx/setup-state.json).

setup:
  - name: restore-frontend
    run: "npm install"
    workdir: ./frontend
    runOnce: true         # skip if already run and command unchanged

  - name: restore-backend
    run: "dotnet restore"
    workdir: ./src
    runOnce: true

  - name: db-migrate
    run: "dotnet ef database update --project src/Api"
    platform: all         # all | windows | linux | macos (default: all)

Running setup

devx setup          # check tools + run pending steps
devx setup --fix    # also install missing tools + re-run runOnce steps
devx setup --json   # machine-readable output (for AI/CI)

Doctor workflow

devx doctor         # check container runtime + declared tools
devx doctor --fix   # attempt to install any missing tools
devx doctor --json  # structured JSON report for AI agents

devx.yaml reference

See docs/manifest.md for the full schema and all supported fields.

Built-in telemetry stack

devx starts a full observability stack alongside your services:

Component	Role
Grafana	Dashboard UI (published on a random port)
Loki	Log aggregation
Prometheus	Metrics collection
Grafana Alloy	Log shipping from Docker containers
cAdvisor	Container CPU and memory metrics
docker-meta exporter	Per-container network metrics + label enrichment

Four pre-built dashboards are provisioned automatically:

• Container Logs — full-text search across all services with service filter
• Container Resources — CPU %, memory, and per-container network Rx/Tx
• Log Analytics — error/warn trends, log volume, error rate over time
• Service Health — active services, error counts, top consumers

See docs/telemetry.md for details.

Disable with devx up --no-telemetry.

Profiles

Profiles let you define different environments in the same file:

profiles:
  local:    # devx up --profile local
  ci:       # devx up --profile ci
  k8s:      # devx up --profile k8s  (rendered to Kubernetes manifests)
    runtime: k8s

The defaultProfile in project is used when --profile is omitted.

Kubernetes

Render a profile to Kubernetes manifests:

devx render k8s --profile k8s --write   # writes .devx/k8s.yaml
devx up --profile k8s                   # kubectl apply
devx down --profile k8s                 # kubectl delete

See docs/manifest.md#kubernetes for constraints.

Offline / airgapped

1. Set registry.prefix in devx.yaml (e.g. myregistry.azurecr.io).
2. Run devx lock update while you have registry access — this writes devx.lock with image digests.
3. Commit devx.lock. On airgapped machines devx up uses digest-pinned images automatically.

Generated files

All runtime artifacts are written to .devx/ (gitignored):

Path	Contents
.devx/compose.yaml	Generated Docker Compose file
.devx/state.json	Active profile, runtime, and telemetry state
.devx/telemetry/	Grafana dashboards, Prometheus config, Alloy config

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on development setup, testing, and submitting pull requests.

License

MIT © dever-labs