From d45f8788dabd3e2b3727e16f4f1b7a39b39cf5f8 Mon Sep 17 00:00:00 2001 From: Eliran Cohen Date: Tue, 7 Jul 2026 10:27:25 +0300 Subject: [PATCH 1/7] Press kit: add the A-to-Z setup walkthrough Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/PRESS-KIT.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/PRESS-KIT.md b/docs/PRESS-KIT.md index 3bf9c3c..039d3f0 100644 --- a/docs/PRESS-KIT.md +++ b/docs/PRESS-KIT.md @@ -49,6 +49,51 @@ wsl2-devkit is a staged, **idempotency-proven** provisioning kit for Windows 10/ - Architecture + flow diagrams: rendered Mermaid in the [README](../README.md#how-it-works) - Suggested screenshot: the verifier's green `52 passed, 0 warnings, 0 missing` summary +## From A to Z — the whole setup, honestly + +What a brand-new user actually does, starting from nothing but Windows: + +1. **Check you qualify** — Windows 10 (build 19041+) or Windows 11, virtualization enabled in BIOS/UEFI (usually already is). +1. **Get the code** (PowerShell): + + ```powershell + git clone https://github.com/elirancv/wsl2-devkit + cd wsl2-devkit + # no git yet? Download ZIP works too - then run: Get-ChildItem -Recurse *.ps1 | Unblock-File + ``` + +1. **Stage 0 — Windows apps** *(optional)*: browser, VS Code, Windows Terminal, Git, the Nerd Font that makes terminal icons render. + + ```powershell + powershell -ExecutionPolicy Bypass -File .\windows\stage0-winget.ps1 + ``` + +1. **Stage 1 — turn on WSL2 + install Ubuntu** (as Administrator): + + ```powershell + Set-ExecutionPolicy RemoteSigned -Scope CurrentUser + .\windows\stage1-windows.ps1 + ``` + + It asks for **one reboot**, then you run it once more — Ubuntu installs on the second pass. Open Ubuntu from the Start menu and pick a username + password. + +1. **Stage 2 — the dev toolchain** (inside the new Ubuntu terminal): + + ```bash + git clone https://github.com/elirancv/wsl2-devkit && cd wsl2-devkit + ./wsl/stage2-ubuntu.sh # interactive menu - or --yes for the defaults + exec $SHELL -l + ``` + +1. **Stage 3 — VS Code wiring** (back in PowerShell): `.\windows\stage3-vscode.ps1` +1. **Z — prove it worked**: + + ```bash + make verify # 52 checks; green = you're a Linux developer now + ``` + +Total: ~30 minutes, one reboot, and every step is safe to re-run if anything hiccups. + ## FAQ ammunition **Is it safe to run scripts like this?** Read them first — that's the intended workflow. They're plain PowerShell/bash, MIT-licensed, no telemetry, and each release publishes SHA256 checksums so you can audit a tag and run exactly those bytes. From d026e86b96a4dcdd8a560dd3ec3c8bfcf8eff130 Mon Sep 17 00:00:00 2001 From: Eliran Cohen Date: Tue, 7 Jul 2026 10:31:23 +0300 Subject: [PATCH 2/7] Reframe as project overview docs/OVERVIEW.md: neutral project document - what it is, who it is for, verifiable claims, setup A-to-Z, FAQ. No meta-marketing framing. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/{PRESS-KIT.md => OVERVIEW.md} | 31 +++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) rename docs/{PRESS-KIT.md => OVERVIEW.md} (82%) diff --git a/docs/PRESS-KIT.md b/docs/OVERVIEW.md similarity index 82% rename from docs/PRESS-KIT.md rename to docs/OVERVIEW.md index 039d3f0..9c5b1c2 100644 --- a/docs/PRESS-KIT.md +++ b/docs/OVERVIEW.md @@ -1,16 +1,16 @@ -# wsl2-devkit — Press Kit +# wsl2-devkit — Overview -Everything you need to write or talk about wsl2-devkit. Quote freely; it's MIT. +What this project is, who it's for, and which of its claims you can verify yourself. -**Links:** [Repository](https://github.com/elirancv/wsl2-devkit) · [Latest release](https://github.com/elirancv/wsl2-devkit/releases/latest) · [Full documentation](DOCUMENTATION.md) +**Links:** [Latest release](https://github.com/elirancv/wsl2-devkit/releases/latest) · [Full reference](DOCUMENTATION.md) · [Changelog](../CHANGELOG.md) --- -## One-liner +## In one sentence > Turn a fresh Windows PC into a professional Linux dev machine in about 30 minutes — and keep Windows clean while doing it. -## The pitch — for people who've never heard of WSL2 +## New to WSL2? Windows can run a real Linux system *inside* itself — no dual-boot, no slow virtual machine window, no second computer. Microsoft calls it **WSL2** (Windows Subsystem for Linux), and it's how a huge share of professional developers on Windows actually work: Windows for the browser and editor, Linux for the code. @@ -18,7 +18,7 @@ The catch: setting it up *well* — the languages, the tooling, the SSH keys, th **wsl2-devkit is that evening, scripted.** Four steps you run in order. It asks what you want (Node? Python? Go? Rust?), installs it the right way, and finishes with a **52-point health check** that proves everything works. It even comes with an undo button: built-in backup, restore, and reset tools. -## The pitch — for engineers +## For engineers wsl2-devkit is a staged, **idempotency-proven** provisioning kit for Windows 10/11 + WSL2 Ubuntu: @@ -33,9 +33,11 @@ wsl2-devkit is a staged, **idempotency-proven** provisioning kit for Windows 10/ **Windows stays clean.** Editors, browsers, and fonts live on Windows; every language runtime, linter, and CLI tool lives in WSL2, where the filesystem is fast. The kit enforces the separation instead of hoping you maintain it. -## Numbers that are true +## Verify the claims yourself -| Claim | Backing | +Don't take the bullets above on faith — each maps to something checkable: + +| Claim | Where to check | |---|---| | ~30 minutes, fresh PC → verified dev machine | Stage timings in the README | | 52-check health verifier | `wsl/verify-setup.sh`, run on every CI push | @@ -43,11 +45,10 @@ wsl2-devkit is a staged, **idempotency-proven** provisioning kit for Windows 10/ | Idempotency is CI-enforced, not claimed | Twice-run byte-identical assert in `.github/workflows/ci.yml` | | Every release ships script checksums | `checksums.txt` on each release | -## Assets +## See it -- **Hero GIF** (terminal walkthrough, 1200×750): [`demo/devkit-demo.gif`](../demo/devkit-demo.gif) — reproducible via `make demo`, fully anonymized -- Architecture + flow diagrams: rendered Mermaid in the [README](../README.md#how-it-works) -- Suggested screenshot: the verifier's green `52 passed, 0 warnings, 0 missing` summary +- Terminal walkthrough: [`demo/devkit-demo.gif`](../demo/devkit-demo.gif) — reproducible via `make demo` +- Architecture and flow diagrams: [README → How it works](../README.md#how-it-works) ## From A to Z — the whole setup, honestly @@ -94,7 +95,7 @@ What a brand-new user actually does, starting from nothing but Windows: Total: ~30 minutes, one reboot, and every step is safe to re-run if anything hiccups. -## FAQ ammunition +## FAQ **Is it safe to run scripts like this?** Read them first — that's the intended workflow. They're plain PowerShell/bash, MIT-licensed, no telemetry, and each release publishes SHA256 checksums so you can audit a tag and run exactly those bytes. @@ -102,6 +103,6 @@ Total: ~30 minutes, one reboot, and every step is safe to re-run if anything hic **Why not Dev Containers / Ansible?** Different job. This is a *personal machine* bootstrap optimized for native speed and a clean host — not fleet configuration management. The scaffolding it installs works fine with containers on top. -## Boilerplate +## About -> **wsl2-devkit** is an open-source (MIT) provisioning kit that turns a fresh Windows 10/11 machine into a complete, verified Linux development environment using WSL2 — in four staged scripts and about 30 minutes. Built by [Eliran Cohen](https://github.com/elirancv). +**wsl2-devkit** is MIT-licensed and built by [Eliran Cohen](https://github.com/elirancv). Contributions welcome — see [CONTRIBUTING.md](../CONTRIBUTING.md); security reports go through [private disclosure](../SECURITY.md). From 5c80cb1357a75fec6590a8af4495b5f91c3645f3 Mon Sep 17 00:00:00 2001 From: Eliran Cohen Date: Tue, 7 Jul 2026 10:33:18 +0300 Subject: [PATCH 3/7] Overview: lead with the isolation benefits Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/OVERVIEW.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 9c5b1c2..a2b8530 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -8,7 +8,14 @@ What this project is, who it's for, and which of its claims you can verify yours ## In one sentence -> Turn a fresh Windows PC into a professional Linux dev machine in about 30 minutes — and keep Windows clean while doing it. +> Turn a fresh Windows PC into a professional Linux dev machine in about 30 minutes — with all of development **isolated in WSL2**, so Windows stays clean and nothing you break can touch it. + +## Why isolation is the point + +- **Experiment without fear** — languages, tools, and config live inside the Linux environment. Worst case, `wsl-tools.ps1 reset` gives you a factory-fresh dev machine in minutes; Windows never notices. +- **Windows stays fast and clean** — no runtimes, PATH clutter, or daemons on the host. Editors, browsers, and fonts stay native; code runs where the filesystem is fast. +- **Reversible by design** — built-in backup (rotated), validated restore, and a health check that tells you precisely what state you're in. +- **One machine, both worlds** — full Linux tooling and native Windows apps, no dual-boot, no VM window. ## New to WSL2? From 5b38577ce38bc6ce6bb8b5d8e3b0277037e03195 Mon Sep 17 00:00:00 2001 From: Eliran Cohen Date: Tue, 7 Jul 2026 10:34:52 +0300 Subject: [PATCH 4/7] Overview: positive framing throughout Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/OVERVIEW.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index a2b8530..cf5abdb 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -8,11 +8,11 @@ What this project is, who it's for, and which of its claims you can verify yours ## In one sentence -> Turn a fresh Windows PC into a professional Linux dev machine in about 30 minutes — with all of development **isolated in WSL2**, so Windows stays clean and nothing you break can touch it. +> Turn a fresh Windows PC into a professional Linux dev machine in about 30 minutes — with all of development **isolated in WSL2**, so Windows stays clean and fast no matter what you build, install, or experiment with. ## Why isolation is the point -- **Experiment without fear** — languages, tools, and config live inside the Linux environment. Worst case, `wsl-tools.ps1 reset` gives you a factory-fresh dev machine in minutes; Windows never notices. +- **Experiment freely** — languages, tools, and config live inside the Linux environment, and a factory-fresh dev machine is always one `wsl-tools.ps1 reset` away. Windows never notices. - **Windows stays fast and clean** — no runtimes, PATH clutter, or daemons on the host. Editors, browsers, and fonts stay native; code runs where the filesystem is fast. - **Reversible by design** — built-in backup (rotated), validated restore, and a health check that tells you precisely what state you're in. - **One machine, both worlds** — full Linux tooling and native Windows apps, no dual-boot, no VM window. From 82a3984d6cf27234bf032f860fe9abce79717bee Mon Sep 17 00:00:00 2001 From: Eliran Cohen Date: Tue, 7 Jul 2026 10:42:56 +0300 Subject: [PATCH 5/7] Overview: workstation-as-code framing, dotfiles FAQ, tighter narrative - New-to-WSL2 section opens with the real historical trade-off (pollute the host vs fight a VM) that WSL2 dissolved. - Engineers section positions the kit as workstation-as-code. - FAQ gains the dotfiles differentiation. - Standalone design-principle section folded into the isolation section (one idea, one place). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/OVERVIEW.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index cf5abdb..38e60a1 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -17,17 +17,21 @@ What this project is, who it's for, and which of its claims you can verify yours - **Reversible by design** — built-in backup (rotated), validated restore, and a health check that tells you precisely what state you're in. - **One machine, both worlds** — full Linux tooling and native Windows apps, no dual-boot, no VM window. +The kit enforces this separation by design — not by hope. + ## New to WSL2? -Windows can run a real Linux system *inside* itself — no dual-boot, no slow virtual machine window, no second computer. Microsoft calls it **WSL2** (Windows Subsystem for Linux), and it's how a huge share of professional developers on Windows actually work: Windows for the browser and editor, Linux for the code. +Developing on Windows used to mean choosing between two compromises: install every runtime directly on Windows and watch it slow down under the clutter, or run Linux in a virtual machine and fight the sluggish filesystem and clunky window. + +**WSL2** (Windows Subsystem for Linux) removed that trade-off — Windows runs a real Linux system *inside* itself, at native speed, no dual-boot, no second computer. It's how a huge share of professional developers on Windows actually work: Windows for the browser and editor, Linux for the code. -The catch: setting it up *well* — the languages, the tooling, the SSH keys, the terminal that doesn't look like 1995 — takes an evening of googling and a dozen chances to get something wrong. +The remaining catch: setting it up *well* — the languages, the tooling, the SSH keys, the terminal that doesn't look like 1995 — takes an evening of googling and a dozen chances to get something wrong. **wsl2-devkit is that evening, scripted.** Four steps you run in order. It asks what you want (Node? Python? Go? Rust?), installs it the right way, and finishes with a **52-point health check** that proves everything works. It even comes with an undo button: built-in backup, restore, and reset tools. ## For engineers -wsl2-devkit is a staged, **idempotency-proven** provisioning kit for Windows 10/11 + WSL2 Ubuntu: +Think of it as **workstation-as-code for the individual engineer** — the rigor fleet tooling applies to server farms (pinning, CI gates, provable idempotency), applied to one bare-metal laptop: - **Four ordered stages** — winget apps → WSL2 + auto-sized `.wslconfig` → dev toolchain (nvm/pnpm/bun, pyenv/uv, pinned Go, rustup, modern CLI: eza · bat · ripgrep · fzf · zoxide · starship · lazygit · gh) → VS Code extensions installed *into the WSL server*, not inertly on Windows. - **Supply chain you can audit** — every vendor installer script is fetched from an **immutable tag/commit ref and verified against a SHA256 committed in the repo** before a byte executes. The Go tarball is version-pinned + checksummed. Releases ship `checksums.txt`. @@ -36,10 +40,6 @@ wsl2-devkit is a staged, **idempotency-proven** provisioning kit for Windows 10/ - **Day-2 tooling** — health verifier, distro backup with rotation, validated restore, VHD compaction, typed-confirmation reset. - **No telemetry. Keys generated locally. MIT.** -## Design principle - -**Windows stays clean.** Editors, browsers, and fonts live on Windows; every language runtime, linter, and CLI tool lives in WSL2, where the filesystem is fast. The kit enforces the separation instead of hoping you maintain it. - ## Verify the claims yourself Don't take the bullets above on faith — each maps to something checkable: @@ -104,6 +104,8 @@ Total: ~30 minutes, one reboot, and every step is safe to re-run if anything hic ## FAQ +**How is this different from dotfiles?** Dotfiles personalize an environment that already works — prompts, aliases, editor settings. wsl2-devkit builds the environment underneath: OS features, `.wslconfig` sizing, language toolchains, keys, and the host↔WSL editor bridge. Your dotfiles layer on top nicely. + **Is it safe to run scripts like this?** Read them first — that's the intended workflow. They're plain PowerShell/bash, MIT-licensed, no telemetry, and each release publishes SHA256 checksums so you can audit a tag and run exactly those bytes. **I already have WSL2.** Stage 2 alone still gets you the toolchain + shell setup, and `verify-setup.sh` will tell you what's missing. Everything is safe to re-run. From d73245e4cae369e8ae0813fe21badb5e84ddd556 Mon Sep 17 00:00:00 2001 From: Eliran Cohen Date: Tue, 7 Jul 2026 10:43:48 +0300 Subject: [PATCH 6/7] Overview: widen the audience, keep plumbing out of benefits "Fresh" excluded everyone with an existing PC (the kit is idempotent precisely so it works there too), and a reset command in the first benefit bullet implied resets are coming. Outcomes up top; script names stay in the reference docs. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/OVERVIEW.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 38e60a1..5e14858 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -8,11 +8,11 @@ What this project is, who it's for, and which of its claims you can verify yours ## In one sentence -> Turn a fresh Windows PC into a professional Linux dev machine in about 30 minutes — with all of development **isolated in WSL2**, so Windows stays clean and fast no matter what you build, install, or experiment with. +> Turn a Windows PC into a professional Linux dev machine in about 30 minutes — with all of development **isolated in WSL2**, so Windows stays clean and fast no matter what you build, install, or experiment with. ## Why isolation is the point -- **Experiment freely** — languages, tools, and config live inside the Linux environment, and a factory-fresh dev machine is always one `wsl-tools.ps1 reset` away. Windows never notices. +- **Experiment freely** — languages, tools, and config live inside the Linux environment, which you can rebuild from scratch in minutes whenever you choose. Windows never notices. - **Windows stays fast and clean** — no runtimes, PATH clutter, or daemons on the host. Editors, browsers, and fonts stay native; code runs where the filesystem is fast. - **Reversible by design** — built-in backup (rotated), validated restore, and a health check that tells you precisely what state you're in. - **One machine, both worlds** — full Linux tooling and native Windows apps, no dual-boot, no VM window. From ba950a9e850b6f36d3569a170ede631d33e00533 Mon Sep 17 00:00:00 2001 From: Eliran Cohen Date: Tue, 7 Jul 2026 10:47:42 +0300 Subject: [PATCH 7/7] Fold the overview into the README; drop the separate file Two parallel what-is-this documents drift apart. The README absorbs the four pieces the overview added that it lacked: a collapsible new-to-WSL2 explainer with the isolation benefits, the workstation-as-code framing, a verify-the-claims table in Security & trust, and a short FAQ. One front door, one source of truth. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 36 ++++++++++++++- docs/OVERVIEW.md | 117 ----------------------------------------------- 2 files changed, 35 insertions(+), 118 deletions(-) delete mode 100644 docs/OVERVIEW.md diff --git a/README.md b/README.md index d466438..f752c63 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,23 @@ wsl2-devkit provisions a fresh machine in four staged scripts: baseline Windows apps, WSL2 + Ubuntu, the full Linux dev toolchain, and VS Code — then hands you a one-command **health check** to prove it all worked. -**Design principle:** Windows stays clean. Editors, browsers and fonts live on Windows; every language runtime, linter and CLI tool lives in WSL2, where your code runs fast. +**Design principle:** Windows stays clean. Editors, browsers and fonts live on Windows; every language runtime, linter and CLI tool lives in WSL2, where your code runs fast. Think of it as **workstation-as-code** — the rigor fleet tooling applies to server farms, applied to one machine. The kit enforces the separation by design, not by hope. + +
+New to WSL2? What it is and why isolation matters + +Developing on Windows used to mean choosing between two compromises: install every runtime directly on Windows and watch it slow down under the clutter, or run Linux in a virtual machine and fight the sluggish filesystem and clunky window. + +**WSL2** (Windows Subsystem for Linux) removed that trade-off — Windows runs a real Linux system *inside* itself, at native speed, no dual-boot, no second computer. It's how a huge share of professional developers on Windows actually work: Windows for the browser and editor, Linux for the code. + +Isolation is what makes it liberating: + +- **Experiment freely** — languages, tools, and config live inside the Linux environment, which you can rebuild from scratch in minutes whenever you choose. Windows never notices. +- **Windows stays fast and clean** — no runtimes, PATH clutter, or daemons on the host. +- **Reversible by design** — built-in backup (rotated), validated restore, and a health check that tells you precisely what state you're in. +- **One machine, both worlds** — full Linux tooling and native Windows apps, no dual-boot, no VM window. + +
--- @@ -239,12 +255,30 @@ doesn't do: `~/.bashrc` block is replaced (not duplicated) between markers, and a flaky network on any single download degrades to a warning instead of aborting the run. +Don't take any of this on faith — each claim maps to something checkable: + +| Claim | Where to check | +|---|---| +| ~30 minutes, fresh PC → verified dev machine | Stage timings in the quick start above | +| 52-check health verifier | [wsl/verify-setup.sh](wsl/verify-setup.sh), run on every CI push | +| 8/8 vendor installers pinned + checksum-verified in-repo | `fetch_verified()` in [wsl/stage2-ubuntu.sh](wsl/stage2-ubuntu.sh) | +| Idempotency is CI-enforced, not claimed | Twice-run byte-identical assert in [ci.yml](.github/workflows/ci.yml) | +| Every release ships script checksums | `checksums.txt` on each [release](https://github.com/elirancv/wsl2-devkit/releases) | + ## Requirements - Windows 10 version 2004 (build 19041) or later, or Windows 11 - Virtualization enabled in firmware (for WSL2) - Administrator access for Stage 1 +## FAQ + +**How is this different from dotfiles?** Dotfiles personalize an environment that already works — prompts, aliases, editor settings. wsl2-devkit builds the environment underneath: OS features, `.wslconfig` sizing, language toolchains, keys, and the host↔WSL editor bridge. Your dotfiles layer on top nicely. + +**I already have WSL2.** Stage 2 alone still gets you the toolchain + shell setup, and `verify-setup.sh` will tell you what's missing. Everything is safe to re-run. + +**Why not Dev Containers / Ansible?** Different job. This is a *personal machine* bootstrap optimized for native speed and a clean host — not fleet configuration management. The scaffolding it installs works fine with containers on top. + ## Documentation Full reference — every setting, the staging rationale, and troubleshooting — lives in [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md). Version history is in [CHANGELOG.md](CHANGELOG.md). diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md deleted file mode 100644 index 5e14858..0000000 --- a/docs/OVERVIEW.md +++ /dev/null @@ -1,117 +0,0 @@ -# wsl2-devkit — Overview - -What this project is, who it's for, and which of its claims you can verify yourself. - -**Links:** [Latest release](https://github.com/elirancv/wsl2-devkit/releases/latest) · [Full reference](DOCUMENTATION.md) · [Changelog](../CHANGELOG.md) - ---- - -## In one sentence - -> Turn a Windows PC into a professional Linux dev machine in about 30 minutes — with all of development **isolated in WSL2**, so Windows stays clean and fast no matter what you build, install, or experiment with. - -## Why isolation is the point - -- **Experiment freely** — languages, tools, and config live inside the Linux environment, which you can rebuild from scratch in minutes whenever you choose. Windows never notices. -- **Windows stays fast and clean** — no runtimes, PATH clutter, or daemons on the host. Editors, browsers, and fonts stay native; code runs where the filesystem is fast. -- **Reversible by design** — built-in backup (rotated), validated restore, and a health check that tells you precisely what state you're in. -- **One machine, both worlds** — full Linux tooling and native Windows apps, no dual-boot, no VM window. - -The kit enforces this separation by design — not by hope. - -## New to WSL2? - -Developing on Windows used to mean choosing between two compromises: install every runtime directly on Windows and watch it slow down under the clutter, or run Linux in a virtual machine and fight the sluggish filesystem and clunky window. - -**WSL2** (Windows Subsystem for Linux) removed that trade-off — Windows runs a real Linux system *inside* itself, at native speed, no dual-boot, no second computer. It's how a huge share of professional developers on Windows actually work: Windows for the browser and editor, Linux for the code. - -The remaining catch: setting it up *well* — the languages, the tooling, the SSH keys, the terminal that doesn't look like 1995 — takes an evening of googling and a dozen chances to get something wrong. - -**wsl2-devkit is that evening, scripted.** Four steps you run in order. It asks what you want (Node? Python? Go? Rust?), installs it the right way, and finishes with a **52-point health check** that proves everything works. It even comes with an undo button: built-in backup, restore, and reset tools. - -## For engineers - -Think of it as **workstation-as-code for the individual engineer** — the rigor fleet tooling applies to server farms (pinning, CI gates, provable idempotency), applied to one bare-metal laptop: - -- **Four ordered stages** — winget apps → WSL2 + auto-sized `.wslconfig` → dev toolchain (nvm/pnpm/bun, pyenv/uv, pinned Go, rustup, modern CLI: eza · bat · ripgrep · fzf · zoxide · starship · lazygit · gh) → VS Code extensions installed *into the WSL server*, not inertly on Windows. -- **Supply chain you can audit** — every vendor installer script is fetched from an **immutable tag/commit ref and verified against a SHA256 committed in the repo** before a byte executes. The Go tarball is version-pinned + checksummed. Releases ship `checksums.txt`. -- **CI that tests the kit, not just the syntax** — every push runs the real installer **twice** on a clean runner and asserts the managed `~/.bashrc` block is *byte-identical* after the re-run, then passes the 52-check verifier. ShellCheck, PSScriptAnalyzer, and a genuine Windows PowerShell 5.1 parse job gate every PR. -- **Unattended mode** — `--yes` / `--all` / `--profile file.conf` for golden images and repeatable rebuilds. -- **Day-2 tooling** — health verifier, distro backup with rotation, validated restore, VHD compaction, typed-confirmation reset. -- **No telemetry. Keys generated locally. MIT.** - -## Verify the claims yourself - -Don't take the bullets above on faith — each maps to something checkable: - -| Claim | Where to check | -|---|---| -| ~30 minutes, fresh PC → verified dev machine | Stage timings in the README | -| 52-check health verifier | `wsl/verify-setup.sh`, run on every CI push | -| 8/8 vendor installers pinned + checksum-verified in-repo | `fetch_verified()` in `wsl/stage2-ubuntu.sh` | -| Idempotency is CI-enforced, not claimed | Twice-run byte-identical assert in `.github/workflows/ci.yml` | -| Every release ships script checksums | `checksums.txt` on each release | - -## See it - -- Terminal walkthrough: [`demo/devkit-demo.gif`](../demo/devkit-demo.gif) — reproducible via `make demo` -- Architecture and flow diagrams: [README → How it works](../README.md#how-it-works) - -## From A to Z — the whole setup, honestly - -What a brand-new user actually does, starting from nothing but Windows: - -1. **Check you qualify** — Windows 10 (build 19041+) or Windows 11, virtualization enabled in BIOS/UEFI (usually already is). -1. **Get the code** (PowerShell): - - ```powershell - git clone https://github.com/elirancv/wsl2-devkit - cd wsl2-devkit - # no git yet? Download ZIP works too - then run: Get-ChildItem -Recurse *.ps1 | Unblock-File - ``` - -1. **Stage 0 — Windows apps** *(optional)*: browser, VS Code, Windows Terminal, Git, the Nerd Font that makes terminal icons render. - - ```powershell - powershell -ExecutionPolicy Bypass -File .\windows\stage0-winget.ps1 - ``` - -1. **Stage 1 — turn on WSL2 + install Ubuntu** (as Administrator): - - ```powershell - Set-ExecutionPolicy RemoteSigned -Scope CurrentUser - .\windows\stage1-windows.ps1 - ``` - - It asks for **one reboot**, then you run it once more — Ubuntu installs on the second pass. Open Ubuntu from the Start menu and pick a username + password. - -1. **Stage 2 — the dev toolchain** (inside the new Ubuntu terminal): - - ```bash - git clone https://github.com/elirancv/wsl2-devkit && cd wsl2-devkit - ./wsl/stage2-ubuntu.sh # interactive menu - or --yes for the defaults - exec $SHELL -l - ``` - -1. **Stage 3 — VS Code wiring** (back in PowerShell): `.\windows\stage3-vscode.ps1` -1. **Z — prove it worked**: - - ```bash - make verify # 52 checks; green = you're a Linux developer now - ``` - -Total: ~30 minutes, one reboot, and every step is safe to re-run if anything hiccups. - -## FAQ - -**How is this different from dotfiles?** Dotfiles personalize an environment that already works — prompts, aliases, editor settings. wsl2-devkit builds the environment underneath: OS features, `.wslconfig` sizing, language toolchains, keys, and the host↔WSL editor bridge. Your dotfiles layer on top nicely. - -**Is it safe to run scripts like this?** Read them first — that's the intended workflow. They're plain PowerShell/bash, MIT-licensed, no telemetry, and each release publishes SHA256 checksums so you can audit a tag and run exactly those bytes. - -**I already have WSL2.** Stage 2 alone still gets you the toolchain + shell setup, and `verify-setup.sh` will tell you what's missing. Everything is safe to re-run. - -**Why not Dev Containers / Ansible?** Different job. This is a *personal machine* bootstrap optimized for native speed and a clean host — not fleet configuration management. The scaffolding it installs works fine with containers on top. - -## About - -**wsl2-devkit** is MIT-licensed and built by [Eliran Cohen](https://github.com/elirancv). Contributions welcome — see [CONTRIBUTING.md](../CONTRIBUTING.md); security reports go through [private disclosure](../SECURITY.md).