A declarative, portable, idempotent Infrastructure-as-Code tool for Windows
powered by modern, dependency-free, single-file .NET.
I built WinHome to create a lightweight, dependency-free configuration tool that runs natively on Windows as a single-file EXE — no Python, Ruby, or agent installations required. This project was heavily inspired by NixOS's home-manager but tailored specifically for the Windows ecosystem.
WinHome focuses on the real needs of Windows developers, including:
- First-class Winget support
- Deep WSL provisioning
- Native Registry tweaks and system settings
The goal is to make Windows environment automation as simple, fast, and reliable as possible.
WinHome ships as a self-contained single EXE (no .NET runtime needed), compatible with all Windows x64 systems.
- Visit the Releases Page
- Download WinHome.exe
- Run it from PowerShell or CMD
Invoke-WebRequest -Uri "https://github.com/DotDev262/WinHome/releases/latest/download/WinHome.exe" -OutFile "WinHome.exe"WinHome reads a declarative config.yaml that defines your desired system state.
A built-in Reconciliation Engine compares it to the live system and ensures everything matches.
- Tracks system state in
winhome.state.json - Detects and corrects configuration drift
- Fully idempotent — run it once or 100 times: the result is identical
For a detailed breakdown of all configuration options, refer to the Configuration Wiki.
- Winget
- Scoop
- Chocolatey
- Mise
- Auto-install and configure distros
- Run post-provision scripts
- Kernel settings and version management
This roadmap is a living document that outlines the project's future direction. It will be updated with new features and ideas as the project evolves.
-
Windows Services management -
Scheduled Tasks provisioning -
Add Chocolatey uninstall support - VSCode Integration: Automatically sync settings and extensions.
- Resource Dependencies: Introduce a
dependsOn:attribute to control execution order. - Plugin Architecture: Redesign the core to support external providers for services and package managers.
- Transactional Rollbacks: Implement logic to automatically undo changes on a failed run.
- Windows Container Support: Add features for provisioning and managing Windows containers.
- Hyper-V VM Provisioning: Introduce capabilities for managing local Hyper-V virtual machines.
-
State diff viewer (--diff) - Configuration Schema Validation: Validate
config.yamlagainst a formal schema to provide better error messages. - Advanced State Management: Add CLI commands to view, backup, and restore system state.
- Structured Output: Add a
--jsonflag for machine-readable output of run results. - GUI Mode: Develop a simple graphical user interface for non-technical users.
- Profile-based PATH Overrides: Allow different profiles to have unique PATH environment variables.
- "Generate" Function: Add a command to generate a
config.yamlfile from the current state of a live system. - DSL: Evolve the configuration into a more powerful Domain-Specific Language (similar to Nix).
-
Mocked tests for registry operations - Containerized Acceptance Tests: Build a full acceptance test suite that runs inside a clean Windows container.
- Complete Unit Test Coverage: Ensure all services and managers have comprehensive unit tests.
- Publish Docs to GitHub Pages: Automate the publishing of the
/docsdirectory to a professional documentation website. - Automate Release Notes: Use tools like
release-drafterto auto-generate changelogs for new releases. - Formalize Contribution Process: Create a
CONTRIBUTING.mdfile and GitHub templates for issues and PRs. - Refactor Core Logic: Decouple
Program.csand simplify the Dependency Injection setup.
Here is a tentative plan for upcoming releases.
Focus: Internal refactoring, test coverage, and developer experience.
- Complete Unit Test Coverage
- Formalize Contribution Process (
CONTRIBUTING.md, templates) - Refactor Core Logic (DI,
Program.cs) - Add Configuration Schema Validation
- Build Containerized Acceptance Test Suite
Focus: Adding highly-requested features for end-users.
- VSCode Integration (Settings & Extension Sync)
- Advanced State Management (
state list,state backup) - Structured JSON Output (
--json) - Publish Docs to GitHub Pages
Focus: Major architectural changes to support long-term extensibility and power.
- Introduce a full Plugin Architecture
- Implement Resource Dependencies (
dependsOn:) - Implement Transactional Rollbacks on failure
- Evolve configuration towards a true DSL
- Split
Interfaces.cs: Moved each interface into its own file insrc/Interfaces/. - Split
Model.cs: Moved each model class into its own file insrc/Models/. - Remove Unused Files: Deleted
tests/WinHome.Tests/UnitTest1.cs. - Review
.gitignore: Audited and improved the.gitignorefile.
Built with modern .NET engineering patterns:
- Dependency Injection (
Microsoft.Extensions.Hosting) - Strategy Pattern across package managers
- Testable Core via abstractions (Registry, FS, Processes)
- CI/CD via GitHub Actions (SingleFile & Native builds)
.\WinHome.exe [options]
--config <path>--dry-run,-d--profile <name>--debug--diff
version: "1.0"
apps:
- id: "Microsoft.PowerToys"
manager: "winget"
- id: "neovim"
manager: "scoop"
- id: "[email protected]"
manager: "mise"
dotfiles:
- src: "./files/.gitconfig"
target: "~/.gitconfig"
envVars:
- variable: "EDITOR"
value: "nvim"
action: "set"
- variable: "Path"
value: "%USERPROFILE%\\bin"
action: "append"
registryTweaks:
- path: "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced"
name: "HideFileExt"
value: 0
type: "dword"
systemSettings:
showFileExtensions: true
darkMode: true
taskbarAlignment: "left"
git:
userName: "John Doe"
userEmail: "[email protected]"
settings:
"core.editor": "code --wait"
"init.defaultBranch": "main"
wsl:
update: true
defaultDistro: "Debian"
defaultVersion: 2
distros:
- name: "Ubuntu-20.04"
- name: "Debian"
profiles:
work:
git:
userName: "John Doe (Work)"
userEmail: "[email protected]"Contributions, discussions, and feature ideas are welcome! Please open an Issue or Pull Request on GitHub.
WinHome stands on the shoulders of incredible open-source technologies:
- Microsoft .NET
- Winget / Scoop / Chocolatey / Mise
- YAML
- GitHub Actions
- PowerShell
And most importantly, the open-source community. ❤️
Released under the MIT License.