Architecture

System Overview

devx orchestrates three infrastructure layers from a single CLI:

Components

Virtual Machine Layer

The foundation is a VM managed by your chosen provider (Lima, Colima, Docker, OrbStack, or Podman). By default, we use Fedora CoreOS because:

• Immutable OS — The root filesystem is read-only, preventing drift
• Ignition provisioning — Configuration is applied atomically at first boot
• Auto-updates — CoreOS updates itself via OSTree without user intervention
• Container-optimized — Minimal footprint, purpose-built for running containers

devx vm init compiles a Butane config into Ignition format and injects it during VM creation. (Note: Some providers like Docker Desktop and OrbStack handle their own lightweight Linux kernel and do not run Fedora CoreOS).

Cloudflare Tunnel (Public Access)

Each VM gets a dedicated Cloudflare Tunnel that:

1. Creates an outbound-only connection to Cloudflare's edge network
2. Routes traffic from *.ipv1337.dev subdomains to local ports
3. Provides automatic TLS termination — no cert management needed
4. Runs as a systemd unit inside the VM

The devx tunnel expose command dynamically adds DNS routes without restarting the tunnel.

Tailscale (Private Access)

Tailscale provides zero-trust access to internal services:

• The VM joins your Tailnet using a pre-authenticated auth key
• Services on the Tailnet (databases, APIs, dashboards) are reachable from inside the VM
• No traditional VPN — traffic goes peer-to-peer via WireGuard

CLI Architecture

devx
├── Local Infrastructure
│   ├── vm, db, cloud, nuke
├── Kubernetes & Hybrid
│   ├── k8s, cluster, bridge
├── Networking & Edge
│   ├── tunnel, mail, webhook
├── Orchestration & State
│   ├── up, action, run, preview, scaffold, shell, logs, map, sync, state, config, exec
├── Testing & Telemetry
│   ├── test, mock, trace, stats, audit, doctor
└── Pipelines & CI/CD
    ├── agent, ci, sites

Each subcommand group is self-contained in cmd/ and communicates with backend services through packages in internal/:

• internal/cloudflare/ — Cloudflare API client (DNS, tunnels)
• internal/github/ — GitHub API client (Pages, repos)
• internal/ignition/ — Butane/Ignition config generation
• internal/bridge/ — Kubernetes port-forward orchestration, intercept lifecycle, Yamux tunnels, and session management
• internal/bridge/agent/ — Standalone Go module for the self-healing agent binary (deployed as a Kubernetes Job)

Bridge Layer (Remote Cluster Access)

The Hybrid Bridge

Bridge implements a "Client-Driven Architecture" allowing developers to merge local code with real staging infrastructure:

• Phase 1: Connect: Outbound connectivity via kubectl port-forward — purely client-side, no cluster modifications
• Phase 2: Intercept: Inbound traffic interception via self-healing agent pods. Deploys an ephemeral agent Job that mirrors the target Service's ports, swaps the selector, and tunnels inbound cluster traffic to the developer's local machine via Yamux multiplexing over kubectl port-forward
• Phase 3: Hybrid Topology: Full hybrid topology orchestrated by devx up — runtime: bridge services with connect/intercept modes participate in the DAG with correct dependency ordering, unified lifecycle, and bridge-native health checks

Bridge injects BRIDGE_*_URL environment variables into devx shell, enabling local code to reach remote services without application-level changes.