⚡ devx

Supercharged local dev environment — Podman + Cloudflare Tunnels + Tailscale in one CLI

Mission Statement

devx exists to bring absolute joy back to local development. We relentlessly eliminate the daily friction that pulls developers out of their flow state. From wrestling with inconsistent OS kernels to manually managing .env files, mocking webhooks, or resetting scrambled testing databases—we believe your tooling should work natively, instantly, and invisibly so you can just write code.

Why devx? (More than just Compose or Skaffold)

While tools like Docker Compose excel at booting containers and Skaffold focuses on bridging local code to Kubernetes clusters, devx serves as a comprehensive, end-to-end Local Development Environment Orchestrator.

We go far beyond basic container networking by natively integrating the premium capabilities developers usually pay for or duct-tape together into a single, unified CLI:

• 🌐 Instant Public Ingress: Stop paying for ngrok. We securely wire your local containers to the internet instantly via Cloudflare Tunnels (*.ipv1337.dev), right out of the box.
• 🔒 Zero-Trust Corporate Access: Stop fighting with heavy VPN clients. The devx VM natively joins your Tailscale mesh silently, giving your local apps direct access to staging and production databases.
• 🧪 Ephemeral E2E Testing: Unlike Compose which corrupts your local databases during UI tests, devx test ui dynamically clones isolated, randomized copies of your database topology to run Cypress/Playwright tests safely.
• 🔑 Vault-Native Config Sync: Stop DMing .env files. devx connects to 1Password, Bitwarden, or GCP Secret Manager to automatically inject secrets natively directly into process environments.
• 🤖 AI-Native from Day 1: Fully compliant with AI Agents (Cursor, Claude Code, Gemina) via deterministic --json outputs, --dry-run safety mechanisms, and native Agent Skill discovery.
• 🚦 Intelligent Service Orchestration: Seamless DAG-based depends_on startup sequences rivaling Docker Compose and Skaffold, completely eliminating local "Connection Refused" loops.
• ⏪ Time-Travel Debugging: Snapshot and restore complete macro-topology states (RAM, volumes, networks) using CRIU, plus redact-safe diagnostic dumps for frictionless support (devx state).
• 🔬 Local CI Emulation: Debug your GitHub Actions locally with devx ci run — matrix expansion, job DAGs, and parallel execution without the "fix ci" commit loop.
• 🛠️ Frictionless Resilience: Built-in automatic Port-Shifting transparently overrides EADDRINUSE conflicts, and native devx crash-tailing instantly pinpoints startup failures precisely inline.
• 🖥️ Integrated Developer Tools: We ship with native Bubble Tea TUIs for multiplexed log streaming, webhook HTTP request caching/replay, instant DB state snapshotting, and more.

devx provisions a customized Fedora CoreOS VM via Podman Machine or Docker and seamlessly drives this entire supercharged ecosystem.

The Solution

devx vm init    # One command. Done.

You get a fully-configured Fedora CoreOS VM with:

• 🌐 Instant public HTTPS — Your machine gets your-name.ipv1337.dev automatically
• 🔒 Zero-trust corporate access — The VM joins your Tailnet transparently
• 🚀 ngrok-like port exposure — devx tunnel expose 3000 gives you a public URL in seconds
• 🏗️ Host-level isolation — Pre-tuned inotify limits, rootful containers, dedicated kernel

Installation

From Releases (recommended)

Download the latest binary from GitHub Releases:

# 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

Prerequisites

Run the built-in health check to audit and install prerequisites automatically:

devx doctor            # check what's installed
devx doctor install    # install missing tools
devx doctor auth       # authenticate required services

Or install them manually:

Quick Start

Before running any infrastructure, you should always check your host environment:

devx doctor

Path A: The Golden Path (Starting a Project)

# 1. Provision your dev environment
devx vm init

# 2. Generate a pre-wired API (e.g. go-api, node-api)
devx scaffold go-api

# 3. Boot required databases and tunnel mappings
cd new-project
devx up

# 4. Enter the isolated dev container (with AI and secrets injected!)
devx shell

Path B: The 'ngrok' Alternative

If you just want to punch a secure hole through to an app running on your Macbook right now:

# 1. Start your local application natively
npm run dev # (running on localhost:3000)

# 2. Expose it via Cloudflare Tunnels instantly
devx tunnel expose 3000 --name myapp
# → https://myapp.your-name.ipv1337.dev

Architecture

flowchart TB
    subgraph devlaptop["Developer's Mac"]
        direction TB
        Code[VS Code / Terminal] --> |podman run| UserContainers

        subgraph podmanvm["Podman Machine (Fedora CoreOS)"]
            subgraph daemons["Systemd Controlled"]
                TS[Tailscale Daemon]
                CF[Cloudflared Tunnel]
            end

            subgraph UserContainers["Developer's Apps"]
                App["API / Web App<br/>Port 8080"]
                DB[(Local DB)]
            end

            CF -->|Forwards Ingress| App
            TS -->|Exposes Subnets| App
        end
    end

    subgraph internet["Public Web"]
        CFEdge((Cloudflare Edge))
        PublicURL["https://developer.ipv1337.dev"]
        ExternalUser((External User / Webhook))

        ExternalUser --> PublicURL
        PublicURL --> CFEdge
    end

    subgraph tailnet["Internal Network (Corporate Tailnet)"]
        StagingDB[(Staging Database)]
        InternalAPI[Internal Microservices]
    end

    CFEdge <-->|Secure Encrypted Tunnel| CF
    TS <-->|Zero-Trust VPN Overlay| tailnet

    classDef vm fill:#f0f4f8,stroke:#0288d1,stroke-width:2px;
    classDef daemon fill:#e1f5fe,stroke:#0277bd,stroke-width:1px;
    classDef container fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px;

    class podmanvm vm;
    class TS,CF daemon;
    class App,DB container;

Design Principles

• One CLI, everything — VM, tunnels, databases, agent skills, and site hosting are all subcommands of devx.
• Convention over configuration — Sensible defaults, but everything is overridable.
• Transparency & Idempotency — Destructive operations show an impact summary. Commands are designed to be run repeatedly safely.
• AI-native — Agent skill files and --json output make devx controllable by AI coding assistants.
• CLI + YAML parity — Every configurable behavior is available both as a CLI flag and as a devx.yaml property.
• Optimized Inner Loop — Developer flow state is sacred. Every feature is optimized to radically reduce cycle time.
• Client-Side First Architecture — No bloated centralized SaaS proxy servers required. devx runs completely locally.
• Absolute Portability — "It works on my machine" is solved permanently. Because devx standardizes a VM locally, execution topology is indistinguishable regardless of your host OS.

📚 Documentation

The full documentation for devx, including all CLI commands, advanced networking, and AI Agent workflows, is available at devx.vitruviansoftware.dev.

Contributing

We welcome contributions! Please read our Contributing Guide for details on:

• Development setup
• Code style and conventions
• Pull request process
• Commit message format

License

MIT © VitruvianSoftware