Marek NovákNix WSL Wrapper (nix.exe)
A robust, transparent Windows executable wrapper designed to intercept native Windows commands and execute them seamlessly inside Nix Subsystem for Linux (WSL). This wrapper is particularly useful for allowing Windows-based MCP servers (like utensils/mcp-nixos), IDE integrations, and build tools to run nix commands natively on a Windows host without requiring full native Nix compile chains.
Key Features
- Clean Architecture & SOLID: Built in C# using Domain-Driven Design (DDD) to encapsulate domain validation (e.g.
WslTarget,NixArguments). - Deadlock-Free I/O Streaming: Spawns background threads to redirect standard input, standard output, and standard error without blocking host tools.
- Premium CLI UI & Diagnostics: Integrates
Spectre.Consoleto render beautiful diagnostic dashboards, system statuses, and automated validation tests. - Highly Configuration-driven: Environment variables allow configuring the WSL distribution name, username, and path to the Nix profile.
Architectural Layout
- NixWslWrapper.Core: The domain layer defining value objects (
WslTarget,NixArguments,ExecutionResult) and interfaces (ICommandExecutor,IStreamCopier). - NixWslWrapper.Infrastructure: Contains execution strategies (
WslCommandExecutor), builder patterns (ProcessBuilder), and threaded stream piping (ThreadedStreamCopier). - NixWslWrapper.Cli: Presentation layer resolving services via Dependency Injection (
Microsoft.Extensions.DependencyInjection), handling command forwarding, and presenting styled dashboard visuals withSpectre.Console. - NixWslWrapper.Tests: The testing suite compiling xUnit tests and mock assertions.
Getting Started
Prerequisites
- WSL2 must be active.
- A Linux distribution installed in WSL (e.g.
DebianorUbuntu). - Nix Package Manager installed inside the WSL distribution.
Build and Publish
Compile the project to a single self-contained executable for Windows:
dotnet publish src/NixWslWrapper.Cli/NixWslWrapper.Cli.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -o ./dist
This will generate nix.exe inside the ./dist folder. Place this executable in your Windows %PATH% (e.g., in a WinGet Links directory or your IDE binary directory).
Configuration
Configure the wrapper using the following Windows environment variables:
| Environment Variable | Description | Default Value |
|---|---|---|
NIX_WSL_DISTRO |
Target WSL Linux distribution name. | Debian |
NIX_WSL_USER |
The user to execute WSL commands under. | root |
NIX_WSL_PROFILE |
Path to the nix-daemon profile script inside WSL. | /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh |
Command Flags
When running the wrapper, standard arguments are forwarded directly to WSL. Two special flags are intercepted by the wrapper for system administration:
--wsl-status: Renders a premium diagnostic panel checking your WSL execution and verifying the Nix version inside your distro.--wsl-help: Displays wrapper-specific configuration details.
Running Tests
Run the xUnit test suite from the root of the project:
dotnet test