WinBoat Bridge

WinBoat Bridge is an orchestration tool that allows a Linux system to run commands inside a virtualized Windows environment (WinBoat) transparently.

Unlike standard solutions like SSH or WinRM (used only for bootstrap), WinBoat Bridge provides a direct and fast channel, ideal for Continuous Integration (CI) pipelines and test automation.

If you are in a hurry and want to skip building from source, check the simple quickstart at docs/quickstart.md for using the ready-made binaries.

1. Configuration (.env File)

The project uses a .env file to manage paths and credentials. Copy the example file and customize it before you start:

cp .env.example .env

⚠️ IMPORTANT - .env File Syntax:

• Use double backslashes (\\) for Windows paths
• DO NOT use quotes for values

Correct example:

WINBOAT_EXE_PATH=C:\\Users\\gianca\\Desktop\\Shared\\progetti\\rust\\winboat-bridge\\target\\release\\winboat-bridge.exe
WINBOAT_LOG_PATH=C:\\Users\\gianca\\server.log

Main parameters:

• WINBOAT_EXE_PATH: Absolute path (on Windows side) where the server is located
• WINBOAT_HOST / PORT: Address and port for bootstrap (WinRM)
• WINBOAT_CLIENT_PORT: Port on the Linux system (Host) mapped to the container
• WINBOAT_SERVER_PORT: Internal port of the Windows container that the server listens on

The .env file is automatically searched in:

1. Current working directory
2. Executable directory
3. Project root (if executable in target/release)

2. Compilation

The project generates a single binary. It must be compiled for Windows (Server) and Linux (Client).

A. Build for Windows (Server)

You have two options, depending on where you are:

Option 1: Cross-compilation from Linux (Recommended for CI/CD)

If you're working on NixOS or Linux, use the dedicated script:

./build_windows.sh

Option 2: Native compilation on Windows

If you have direct access to a Windows system with Rust installed:

1. Open a PowerShell in the project root.
2. Run: cargo build --release
3. You'll find the file in target\release\winboat-bridge.exe.

Make sure the file is in the shared folder and that the path in .env (WINBOAT_EXE_PATH) points correctly to this binary.

B. Build for Linux (Client)

On your Linux machine, compile normally:

cargo build --release

3. Global Installation (Linux)

To run winboat-bridge from any folder, create a symbolic link in the user binaries directory. Following the XDG standard, the correct directory is ~/.local/bin.

# Create the directory if it doesn't exist
mkdir -p ~/.local/bin

# Create a symbolic link to the newly compiled binary
ln -sf "$(pwd)/target/release/winboat-bridge" ~/.local/bin/winboat-bridge

Note: Make sure ~/.local/bin is in your $PATH (check ~/.bashrc or ~/.zshrc).

4. Docker Compose Integration

Configure port mapping in your docker-compose.yml to expose the necessary services:

services:
  windows:
    ports:
      - "127.0.0.1:47320:5985"  # WinRM (For automatic bootstrap)
      - "127.0.0.1:47330:5330"  # WinBoat Bridge (Client-Server communication)

5. Usage Examples

Once the .env file is configured, the Linux client will handle everything automatically (including starting the Windows server if it's off).

Verify connection:

winboat-bridge -c "ipconfig"

Run PowerShell script:

winboat-bridge -c "powershell -File C:\Scripts\Setup-Test.ps1"

6. Support the project (aka "The Star Section" ⭐)

Building tools like this is fun, but seeing stars is better!

If this tool saved you time or just made your life easier, please drop a star on this repository. It costs you $0.00, but it gives me the fuel (and the dopamine) to keep building and sharing more cool stuff for free.

Go on, click that star. You know you want to! 😉

Troubleshooting

Problem	Possible Cause	Solution
The command "hangs"	Zombie connection	Ctrl+C and restart; the client will force a new bootstrap.
Connection Refused	Wrong port mapping	Check with docker ps that port 47330 is open.
"WINBOAT_EXE_PATH must be set"	.env file not found or wrong syntax	Verify that the .env file exists and uses double backslashes (\\) without quotes. Run with --help to see the message [DEBUG] Loaded .env from: ...
.env parsing error	Wrong syntax	Use double backslashes (\\) for Windows paths and DO NOT use quotes.

.env Loading Debug

To verify that the .env file is loaded correctly, run:

./target/release/winboat-bridge --help 2>&1 | grep DEBUG

You should see:

[DEBUG] Loaded .env from: /path/to/.env

If you see [WARNING] No .env file found, check that:

1. The .env file exists in the current directory, executable directory, or project root
2. The syntax is correct (double backslashes, no quotes)
3. The file has correct read permissions