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.
Before using WinHome, ensure your environment meets the following requirements:
- Operating System: Windows 10 (Version 1809 or higher) or Windows 11.
- Privileges: Must be executed with Administrator privileges to modify system settings and install packages.
- Internet Connection: Required for downloading packages and updates.
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"Post-Install Note: For easier global access, we recommend moving
WinHome.exeto a folder included in your system'sPATHenvironment variable (e.g.,C:\Users\<User>\bin).
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.
Do not commit config.yaml to public repositories if it contains sensitive information such as API tokens, passwords, or private environment variables. We recommend using a private repository or .gitignore for configurations containing secrets.
- Winget (with auto-install support)
- Scoop
- Chocolatey
- Auto-install and configure distros
- Run post-provision scripts
- Kernel settings and version management
WinHome implements enterprise-grade security controls to prevent common infrastructure automation pitfalls.
WinHome actively detects if it is running as SYSTEM (common in CI/CD or Scheduled Tasks) and blocks attempts to modify HKEY_CURRENT_USER. This prevents the "Admin Context Trap" where settings are accidentally applied to the LocalSystem profile instead of the logged-in user.
The state engine uses a Write-Through pattern. Every successful action (e.g., installing an app, applying a registry key) is immediately flushed to disk (winhome.state.json). If the process crashes or is terminated (Ctrl+C), your progress is saved, and the next run will resume correctly without "zombie" state issues.
External plugins (Python/Node.js) run in a sandboxed process with strict limits:
- Memory Limit: 10MB max output buffer to prevent OOM attacks.
- Time Limit: 30-second execution timeout to prevent hangs.
- Isolation: Plugins communicate strictly via JSON over Stdin/Stdout.
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 - Winget Auto-Install: Automatically installs Winget if missing.
- Plugin Architecture: Redesign the core to support external providers for services and package managers.
- VSCode Plugin: Automatically sync settings and extensions using the new plugin architecture.
- Resource Dependencies: Introduce a
dependsOn:attribute to control execution order. - 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) - Enhanced Logging: Filtered, real-time output for package managers.
- 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.
- Native GitHub Actions Testing: End-to-end testing on real Windows VMs.
- Complete Unit Test Coverage: Ensure all services and managers have comprehensive unit tests.
- Refactor Core Logic: Decouple
Program.csand simplify the Dependency Injection setup. - 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.
Here is a tentative plan for upcoming releases.
Focus: Internal refactoring, test coverage, and developer experience.
- Complete Unit Test Coverage:
-
DotfileService -
WslService -
GitService -
EnvironmentService -
WingetService -
ScoopService -
ChocolateyService -
RegistryService -
SystemSettingsService -
ScheduledTaskService -
WindowsServiceManager
-
- Refactor Core Logic:
- Simplify Dependency Injection in
Program.cs. - Decouple
Program.csby moving logic into dedicatedCliBuilderandAppHostclasses.
- Simplify Dependency Injection in
- Logging & Testability:
- Introduce a proper
ILoggerservice (Console/JSON). - Support
WINHOME_CONFIG_PATHenvironment variable. - Implement distinct exit codes for automation.
- Introduce a proper
- Validation & Automation:
- Add Configuration Schema Validation (JSON Schema).
- Finalize Containerized Acceptance Test Suite.
- Formalize Contribution Process (
CONTRIBUTING.md, templates).
Focus: Redesigning the core for extensibility and adding community-requested features.
- Plugin Architecture: Redesign the core to support external providers for services and package managers.
- VSCode Plugin: Implement VSCode settings and extension sync as the first official plugin.
- Vim/Neovim Plugin: Configure plugins and settings for Vim/Neovim.
- Config Generator (
winhome generate): Scan the system and create aconfig.yamlbased on installed apps and settings. - Advanced State Management (
state list,state backup,state restore). - Secret Reference Logic: Add support for referencing secrets from environment variables or secure vaults.
- Self-Update Mechanism: Allow
WinHometo update itself to the latest version. - Security Hardening Presets: Add pre-defined configurations for locking down Windows security settings.
- Automation:
- Publish Docs to GitHub Pages (DocFx).
- Automate Release Notes (
release-drafter).
- Structured Output: Finalize
--jsonintegration for all modules.
Focus: Major architectural changes to support long-term power and reliability.
- Implement Resource Dependencies (
dependsOn:) - Implement Transactional Rollbacks on failure
- Evolve configuration towards a true DSL
Built with modern .NET engineering patterns:
- Dependency Injection (
Microsoft.Extensions.Hosting) - Strategy Pattern across package managers
- Testable Core via abstractions (Registry, FS, Processes)
- Cross-Platform Dev: Can be developed/unit-tested on Linux & macOS.
- 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"
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: "john.doe@example.com"
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: "john.doe@work.com"WinHome is fully portable. To uninstall it:
- Delete the
WinHome.exefile. - Delete the state file
winhome.state.json(located in the same directory).
No registry keys or hidden folders are left behind by the tool itself.
"Winget not recognized"
Ensure the App Installer is updated from the Microsoft Store. WinHome attempts to use the system-level Winget.
PowerShell Script Errors
If you encounter execution policy errors, try running
Set-ExecutionPolicy RemoteSigned -Scope CurrentUserin an administrative PowerShell window.
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
- YAML
- GitHub Actions
- PowerShell
And most importantly, the open-source community. ❤️
Released under the MIT License.