Getting Started

Prerequisites

The fastest way to set up your environment is with the built-in health check:

devx doctor            # audit tools, credentials, and feature readiness
devx doctor install    # install any missing tools via your package manager
devx doctor auth       # walk through authenticating required services

devx doctor checks for all 9 CLI tools and 7 credentials that devx uses, and tells you exactly what's ready and what needs attention.

Manual Setup

If you prefer to install manually:

Tool	Install	Purpose	Required?
Podman	brew install podman	VM and container runtime	Yes
cloudflared	brew install cloudflare/cloudflare/cloudflared	Cloudflare tunnel daemon	Yes
butane	brew install butane	Ignition config compiler	Yes
gh	brew install gh	GitHub CLI (for devx sites)	Yes
docker	brew install docker	Alternative VM backend	Optional
orbstack	brew install orbstack	Alternative VM backend	Optional
1Password CLI	brew install 1password-cli	Vault secret sync	Optional
Bitwarden CLI	brew install bitwarden-cli	Vault secret sync	Optional
gcloud	brew install google-cloud-sdk	GCP Secret Manager	Optional

Installation

From GitHub Releases (recommended)

# macOS (Apple Silicon)
curl -sL https://github.com/VitruvianSoftware/devx/releases/latest/download/devx_darwin_arm64.tar.gz | tar xz
sudo mv devx /usr/local/bin/

# macOS (Intel)
curl -sL https://github.com/VitruvianSoftware/devx/releases/latest/download/devx_darwin_amd64.tar.gz | tar xz
sudo mv devx /usr/local/bin/

# Linux (amd64)
curl -sL https://github.com/VitruvianSoftware/devx/releases/latest/download/devx_linux_amd64.tar.gz | tar xz
sudo mv devx /usr/local/bin/

From Source

go install github.com/VitruvianSoftware/devx@latest

Quick Start

0. Check your environment (one-time)

devx doctor

This audits all prerequisites — tools, credentials, and authentication sessions — and tells you exactly what's ready and what needs fixing. If anything is missing, follow the prompts or run devx doctor install.

1. Provision your dev environment

devx vm init

This creates a Fedora CoreOS VM via Podman Machine with Cloudflare Tunnel and Tailscale pre-configured. The process takes about 2-3 minutes on the first run.

2. Verify everything is running

devx vm status

You should see all three components — VM, Cloudflare Tunnel, and Tailscale — reporting as healthy.

3. Expose a port

# Start a web server inside the VM
devx exec podman run -d -p 8080:80 docker.io/nginx

# Expose it to the internet
devx tunnel expose 8080 --name demo
# → https://demo.your-name.ipv1337.dev

4. Spin up a database

devx db spawn postgres --name mydb
# → PostgreSQL running on localhost:5432

Configuration

devx uses a .env file in your project root for secrets:

# .env
CF_API_TOKEN=your-cloudflare-api-token
CF_TUNNEL_TOKEN=your-tunnel-token
DEV_HOSTNAME=your-machine-name

TIP

Run devx doctor auth to set up your .env interactively — it will prompt for tokens and save them automatically.

Global flags available on all commands:

Flag	Description
--dry-run	Preview destructive actions without executing
--json	Machine-readable output for AI agents
-y, --non-interactive	Skip confirmation prompts
--env-file	Path to secrets file (default: .env)