{"id":47719853,"url":"https://github.com/vitruviansoftware/devx","last_synced_at":"2026-06-07T20:01:08.883Z","repository":{"id":348147245,"uuid":"1196688875","full_name":"VitruvianSoftware/devx","owner":"VitruvianSoftware","description":"Supercharged local dev environment","archived":false,"fork":false,"pushed_at":"2026-05-02T07:59:50.000Z","size":17658,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T09:25:35.109Z","etag":null,"topics":["cli","cloudflare","developer-experience","developer-tools","devops","golang","local-development","ngrok-alternative","platform","platform-engineering","podman","tailscale"],"latest_commit_sha":null,"homepage":"https://devx.vitruviansoftware.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VitruvianSoftware.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T00:14:56.000Z","updated_at":"2026-05-02T07:59:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/VitruvianSoftware/devx","commit_stats":null,"previous_names":["vitruviansoftware/devx"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/VitruvianSoftware/devx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VitruvianSoftware%2Fdevx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VitruvianSoftware%2Fdevx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VitruvianSoftware%2Fdevx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VitruvianSoftware%2Fdevx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VitruvianSoftware","download_url":"https://codeload.github.com/VitruvianSoftware/devx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VitruvianSoftware%2Fdevx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32560938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cloudflare","developer-experience","developer-tools","devops","golang","local-development","ngrok-alternative","platform","platform-engineering","podman","tailscale"],"created_at":"2026-04-02T19:17:55.285Z","updated_at":"2026-05-23T10:05:03.594Z","avatar_url":"https://github.com/VitruvianSoftware.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e⚡ devx\u003c/h1\u003e\n  \u003cp align=\"center\"\u003eThe unified orchestration layer for your modern developer lifecycle\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/VitruvianSoftware/devx/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/VitruvianSoftware/devx/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/VitruvianSoftware/devx/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/VitruvianSoftware/devx\" alt=\"Release\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/VitruvianSoftware/devx/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/VitruvianSoftware/devx\" alt=\"License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/VitruvianSoftware/devx\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/VitruvianSoftware/devx\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/hero.png\" alt=\"devx — Supercharged Local Development\" width=\"600\"\u003e\n\u003c/p\u003e\n\n## Mission Statement\n\n**devx** exists to bring absolute joy back to local development. \nWe 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.\n\n## Why `devx`? (More than just Compose or Skaffold)\n\nWhile 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**. \n\nWe 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:\n\n### Local Infrastructure\n* 🐳 **Container VMs \u0026 Providers:** Provision customized Fedora CoreOS VMs via your chosen backend (Podman, Docker, OrbStack, Lima, Colima).\n* 🗄️ **Ephemeral Databases \u0026 Emulators:** One-click spin up of Postgres, Redis, GCP Cloud Emulators, and local S3 buckets with automatic `.env` injection. AI-driven synthetic data generation (`devx db synthesize`) creates chaotic, edge-case-heavy test records via local or cloud LLMs.\n* ☢️ **The Nuke Button:** Instantly hard-reset corrupted project caches, volumes, and images with a single atomic command (`devx nuke`).\n\n### Kubernetes \u0026 Hybrid\n* 🚀 **Skaffold-Class Cluster Deploy:** Deploy a service to any cluster with `runtime: kubernetes` — devx renders your manifests (`kustomize` via `kubectl apply -k`, or `raw` via `-f`) and applies them to the target context/namespace, then readiness-gates the DAG on the namespace's Deployments becoming `Available` (no port-forward needed). Resources are pruned on shutdown. (Helm renderer + image build/load are on the roadmap.)\n* 🔗 **Hybrid Bridge to Kubernetes:** Declaratively bridge remote K8s services into `devx up` with `runtime: bridge`. Outbound port-forwarding and inbound traffic interception participate natively in the DAG.\n* ☸️ **Zero-Config Local Kubernetes:** Spin up an instant, isolated K3s control plane directly inside your VM without destroying your host machine.\n* 🖥️ **Multi-Node Clusters:** Scale your local K8s development beyond a single laptop by provisioning distributed, highly available K3s clusters across multiple physical machines via Lima VMs.\n\n### Networking \u0026 Edge\n* 🌐 **Instant Public Ingress:** Stop paying for ngrok. Securely wire your local containers to the internet instantly via Cloudflare Tunnels (`*.ipv1337.dev`).\n* 📧 **Local Webhook \u0026 Email Catchers:** Integrated Bubble Tea TUIs for intercepting, caching, and replaying HTTP webhooks and SMTP traffic locally.\n\n### Orchestration \u0026 State\n* 🚦 **Intelligent Orchestration:** Seamless DAG-based `depends_on` startup sequences rivaling Docker Compose, plus native Multirepo composing via `include:` directives.\n* 🔑 **Vault Secrets Syncing:** Stop DMing `.env` files. `devx` connects to 1Password, Bitwarden, or GCP Secret Manager to inject secrets directly into your containers.\n* ⚡ **Smart File Syncing:** Bypass slow VirtioFS volume mounts with intelligent Mutagen-powered file syncing (`devx sync up`) that propagates changes in milliseconds.\n* 🔍 **Instant PR Sandboxing:** Review any PR without switching branches. `devx preview 42` creates an isolated worktree with dedicated databases and tunnel URLs, then cleans up automatically on exit.\n* ⏪ **Diagnostics \u0026 State:** Snapshot and restore complete database volumes using CRIU, bundle and share your exact environment with teammates (`devx state share`), and generate redact-safe diagnostic dumps for frictionless support.\n\n### Testing \u0026 Telemetry\n* 🧪 **Ephemeral E2E Testing:** Dynamically clone isolated, randomized copies of your database topology to run Cypress/Playwright tests safely.\n* 🩺 **Environment Doctor:** Run the built-in health check (`devx doctor`) to audit, authenticate, and auto-install all prerequisites effortlessly.\n* 📊 **Distributed Tracing \u0026 Mocking:** Instantly spawn OpenTelemetry backends (Jaeger/Grafana) and Prisma mock servers for complete observability and API isolation.\n\n### Pipelines \u0026 CI/CD\n* 🔬 **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.\n* ⏱️ **Predictive Pre-Building:** Local telemetry tracks build durations and proactively nudges you to enable background pre-building to prime container caches.\n* 🤖 **AI-Native from Day 1:** Fully compliant with AI Agents via deterministic `--json` outputs, `--dry-run` safety mechanisms, and native Agent Skill discovery.\n\n`devx` provisions a customized **Fedora CoreOS** VM via your chosen backend (Lima, Colima, Docker, OrbStack, or Podman) and seamlessly drives this entire supercharged ecosystem.\n\n---\n\n## Installation\n\n### From Homebrew (recommended for macOS/Linux)\n\n```bash\nbrew install vitruviansoftware/tap/devx\n```\n\n### From Releases\n\nDownload the latest binary from [GitHub Releases](https://github.com/VitruvianSoftware/devx/releases/latest):\n\n```bash\n# macOS (Apple Silicon)\ncurl -sL https://github.com/VitruvianSoftware/devx/releases/latest/download/devx_darwin_arm64.tar.gz | tar xz\nsudo mv devx /usr/local/bin/\n\n# macOS (Intel)\ncurl -sL https://github.com/VitruvianSoftware/devx/releases/latest/download/devx_darwin_amd64.tar.gz | tar xz\nsudo mv devx /usr/local/bin/\n\n# Linux (amd64)\ncurl -sL https://github.com/VitruvianSoftware/devx/releases/latest/download/devx_linux_amd64.tar.gz | tar xz\nsudo mv devx /usr/local/bin/\n```\n\n### From Source\n\n```bash\ngo install github.com/VitruvianSoftware/devx@latest\n```\n\n## Quick Start\n\n### Step 0: Check Prerequisites\n\nRun the built-in health check to audit and install prerequisites automatically:\n\n```bash\ndevx doctor            # check what's installed\ndevx doctor install    # install missing tools\ndevx doctor auth       # authenticate required services\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eManual Installation Prerequisites\u003c/summary\u003e\n\n| Tool | Install | Purpose |\n|------|---------|---------|\n| [Podman](https://podman.io) / [Lima](https://lima-vm.io/) / [Colima](https://github.com/abiosoft/colima) / [Docker](https://docker.com) | | Any VM backend of your choice |\n| [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/) | `brew install cloudflare/cloudflare/cloudflared` | Cloudflare tunnel daemon |\n| [butane](https://coreos.github.io/butane/) | `brew install butane` | Ignition config compiler |\n| [gh](https://cli.github.com) | `brew install gh` | GitHub CLI (for `devx sites`, `devx preview`) |\n\n\u003c/details\u003e\n\n### Step 1: The Magic (TL;DR)\n\n```bash\ndevx vm init    # One command. Done.\n```\n\nYou get a fully-configured Fedora CoreOS VM via your chosen provider with:\n\n- 🌐 **Instant public HTTPS** — Your machine gets `your-name.ipv1337.dev` automatically\n- 🔒 **Zero-trust corporate access** — The VM joins your Tailnet transparently\n- 🚀 **ngrok-like port exposure** — `devx tunnel expose 3000` gives you a public URL in seconds\n- 🏗️ **Host-level isolation** — Pre-tuned `inotify` limits, rootful containers, dedicated kernel\n\n### Path A: The Golden Path (Starting a Project)\n\n```bash\n# 1. Provision your dev environment\ndevx vm init\n\n# 2. Generate a pre-wired API (e.g. go-api, node-api)\ndevx scaffold go-api\n\n# 3. Boot required databases and tunnel mappings\ncd new-project\ndevx up\n\n# 4. Enter the isolated dev container (with AI and secrets injected!)\ndevx shell\n```\n\n### Path B: The 'ngrok' Alternative\n\nIf you just want to punch a secure hole through to an app running on your Macbook right now:\n\n```bash\n# 1. Start your local application natively\nnpm run dev # (running on localhost:3000)\n\n# 2. Expose it via Cloudflare Tunnels instantly\ndevx tunnel expose 3000 --name myapp\n# → https://myapp.your-name.ipv1337.dev\n```\n\n## Configuration Domains\n\nThe `devx` ecosystem separates configuration into two distinct files based on the scope of orchestration:\n\n1. **`devx.yaml` (Project-Level Local Dev):** This is the primary configuration file. It lives in your application's repository and defines the local development topology (databases, tunnels, CI steps, and dependent services). It is used by almost all `devx` commands (e.g., `devx up`, `devx test`, `devx action`).\n   - **Discovery Behavior**: `devx` automatically searches the current directory and all parent directories upward until it finds a `devx.yaml` file. This allows you to seamlessly run `devx` commands from any nested subdirectory within your project.\n2. **`cluster.yaml` (Infrastructure-Level Multi-Node Dev):** This file is exclusively used by the `devx cluster` command suite. It defines the desired state of a multi-node Kubernetes cluster (node IPs, K3s versions, VM allocations) and is usually kept in a dedicated infrastructure repository.\n   - **Discovery Behavior**: Similar to `devx.yaml`, `devx cluster` automatically crawls upward from the current directory to locate your `cluster.yaml` configuration.\n\nThese files do not override each other; they serve completely different domains.\n\n### Discovery Order (`devx.yaml`)\n\n1. Walk upward from CWD → first `devx.yaml` found wins\n2. `include:` directives within that file compose additional configs (relative to the config's directory)\n3. `~/.devx/config.yaml` provides machine-local overrides (e.g., VM provider)\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph devlaptop[\"Developer's Mac\"]\n        direction TB\n        Code[VS Code / Terminal] --\u003e |podman run| UserContainers\n\n        subgraph podmanvm[\"Podman Machine (Fedora CoreOS)\"]\n            subgraph daemons[\"Systemd Controlled\"]\n                TS[Tailscale Daemon]\n                CF[Cloudflared Tunnel]\n            end\n\n            subgraph UserContainers[\"Developer's Apps\"]\n                App[\"API / Web App\u003cbr/\u003ePort 8080\"]\n                DB[(Local DB)]\n            end\n\n            CF --\u003e|Forwards Ingress| App\n            TS --\u003e|Exposes Subnets| App\n        end\n    end\n\n    subgraph internet[\"Public Web\"]\n        CFEdge((Cloudflare Edge))\n        PublicURL[\"https://developer.ipv1337.dev\"]\n        ExternalUser((External User / Webhook))\n\n        ExternalUser --\u003e PublicURL\n        PublicURL --\u003e CFEdge\n    end\n\n    subgraph tailnet[\"Internal Network (Corporate Tailnet)\"]\n        StagingDB[(Staging Database)]\n        InternalAPI[Internal Microservices]\n    end\n\n    CFEdge \u003c--\u003e|Secure Encrypted Tunnel| CF\n    TS \u003c--\u003e|Zero-Trust VPN Overlay| tailnet\n\n    classDef vm fill:#f0f4f8,stroke:#0288d1,stroke-width:2px;\n    classDef daemon fill:#e1f5fe,stroke:#0277bd,stroke-width:1px;\n    classDef container fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px;\n\n    class podmanvm vm;\n    class TS,CF daemon;\n    class App,DB container;\n```\n\n## Design Principles\n\n- **One CLI, everything** — VM, tunnels, databases, agent skills, and site hosting are all subcommands of `devx`.\n- **Convention over configuration** — Sensible defaults, but everything is overridable.\n- **Transparency \u0026 Idempotency** — Destructive operations show an impact summary. Commands are designed to be run repeatedly safely.\n- **AI-native** — Agent skill files and `--json` output make `devx` controllable by AI coding assistants.\n- **CLI + YAML parity** — Every configurable behavior is available both as a CLI flag and as a `devx.yaml` property.\n- **Optimized Inner Loop** — Developer flow state is sacred. Every feature is optimized to radically reduce cycle time.\n- **Client-Side First Architecture** — No bloated centralized SaaS proxy servers required. `devx` runs completely locally.\n- **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.\n\n## 📚 Documentation\n\nThe full documentation for `devx`, including all CLI commands, advanced networking, and AI Agent workflows, is available at [devx.vitruviansoftware.dev](https://devx.vitruviansoftware.dev).\n\n## Contributing\n\nWe welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- Development setup\n- Code style and conventions\n- Pull request process\n- Commit message format\n\n## License\n\n[MIT](LICENSE) © VitruvianSoftware \n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitruviansoftware%2Fdevx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitruviansoftware%2Fdevx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitruviansoftware%2Fdevx/lists"}