A declarative, portable, idempotent Infrastructure-as-Code tool for Windows
powered by modern, dependency-free, single-file .NET.
- GitHub Discussions: The best place for "How do I...?" questions and community support. Join the conversation!
- Issues: For bug reports and feature requests. Open a new issue using our templates.
- GSSOC 2026: Participants should check our Contributing Guide for program-specific instructions.
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"Once WinHome is published to the Windows Package Manager repository, you will be able to install it with:
# Coming soon — pending winget submission
winget install DotDev262.WinHomeOnce the Scoop bucket is published:
# Coming soon — pending Scoop bucket submission
scoop bucket add winhome https://github.com/DotDev262/scoop-winhome
scoop install winhomeOnce the Chocolatey package is published:
# Coming soon — pending Chocolatey package approval
choco install winhomePost-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.
For complete, real-world setup examples (Developer, Minimalist, Gamer), see the Configuration Cookbook.
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 (Bun, Uv) 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.
- Obsidian Plugin: Manage settings and community plugins across your Obsidian vaults.
- Oh My Posh Plugin: Manage PowerShell terminal prompt themes.
- 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"
envVars:
- variable: "EDITOR"
value: "code"
action: "set"
- variable: "Path"
value: "%USERPROFILE%\work\bin"
action: "append"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.
For a comprehensive troubleshooting guide, see Troubleshooting.
"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! WinHome is an open-source project and we'd love your help to make it better.
| Resource | Description |
|---|---|
| Contributing Guide | Full guide: branching, commit style, PR process |
| GSSOC 2026 Instructions | Program-specific labels & tracking info |
| Configuration Wiki | Understand WinHome's configuration schema |
| Configuration Cookbook | Real-world config.yaml examples |
| Testing Guide | How to write and run tests |
| Cross-Platform Dev | Developing on Linux/macOS |
| Security Guide | Security practices and guidelines |
| Troubleshooting | Common issues and solutions |
| GitHub Discussions | Community Q&A and ideas |
| Open Issues | Find something to work on |
- Fork the repository → Fork WinHome
- Clone your fork and create a branch:
git checkout -b <issue-number>-short-description - Build:
dotnet build WinHome.sln - Test:
dotnet test WinHome.sln - Format:
dotnet format WinHome.sln(required before submitting) - Open a Pull Request and link it to the relevant issue (
Closes #<issue-number>)
💡 GSSOC 2026 participants: Please read the Contributing Guide for program-specific instructions on PR labels and leaderboard tracking.
Please open an Issue or Pull Request on GitHub.
Thanks goes to these wonderful people (emoji key):
 DotDev262 💻 🎨 🤔 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!
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. ❤️
📘 For detailed security guidance and best practices, see the Security Guide.
Released under the MIT License.