Axemere.ai

Windows (WSL2)

For: Developers and IT engineers running Axemere Gateway on Windows via WSL2.

IT Setup Overview | PostgreSQL Setup | Linux (Debian/Ubuntu) | Linux (RHEL/Fedora) | macOS | Docker/Podman | Kubernetes | Windows (WSL2) | Cloud

Windows users can run Axemere Gateway using the Windows Subsystem for Linux (WSL2). All Linux installation methods (Docker, APT, deb package) work inside a WSL2 environment without modification.

Table of Contents

Virtualization Requirements

WSL2 runs inside a lightweight Hyper-V virtual machine and requires hardware virtualization support.

  • Bare-metal Windows: WSL2 works on any modern Intel or AMD processor with virtualization enabled in BIOS/UEFI.
  • Windows running inside a VM (Parallels, VMware, etc.): WSL2 requires nested virtualization from the host hypervisor.
    • Parallels Desktop on Intel Macs: Nested virtualization is supported. Enable "Nested Virtualization" in the VM's CPU settings before installing WSL2.
    • Parallels Desktop on Apple Silicon (M1--M4) Macs: Nested virtualization is not supported. WSL2 cannot run; Windows silently falls back to WSL1. Use Docker Desktop or the binary download option instead. See Parallels KB #129234 for details.
    • VMware Fusion: Nested virtualization support varies by version; consult VMware documentation.

If you are unsure which version of WSL you have, run wsl --list --verbose from PowerShell -- the VERSION column shows 1 or 2. See the WSL1 Fallback section below if you are on WSL1.

Prerequisites

  • Windows 11 22H2 or later (WSL2 is also available on Windows 10 21H2+ but systemd support requires Windows 11)
  • WSL2 with an Ubuntu 24.04 distro installed: 
    wsl --install -d Ubuntu-24.04
  • For systemd support, enable it in /etc/wsl.conf inside the Ubuntu distro: 
    [boot]
systemd=true
    Then restart WSL: wsl --shutdown (from PowerShell), then relaunch Ubuntu.

PostgreSQL Inside WSL

For WSL2, installing PostgreSQL directly inside the distro is simpler than running a Docker container -- it avoids Docker Desktop dependency and keeps everything in the Linux filesystem:

sudo apt install -y postgresql
sudo systemctl enable --now postgresql
sudo -u postgres psql <<'EOF'
CREATE USER mvgc_gateway WITH PASSWORD '<your-generated-password>';
CREATE DATABASE mvgc_gateway OWNER mvgc_gateway;
EOF

Your DATABASE_URL:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
DATABASE_URL=postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable

Docker Desktop with WSL2 integration also works if you already have it installed -- run a postgres:16 container as described in PostgreSQL Setup (Option A). The container is accessible from WSL at localhost.

You can also point DATABASE_URL at an external managed Postgres instance if you have one.

Option 1 -- Docker Desktop (recommended)

Install Docker Desktop for Windows and enable the WSL2 backend. Docker commands then work identically from either the Windows terminal or the WSL shell. Follow the Docker and Podman instructions verbatim.

Option 2 -- Debian Package (.deb) Inside WSL

The .deb package is the recommended path for running the gateway as a managed systemd service inside WSL2. Systemd must be enabled (see prerequisites above) before installing.

Download the package to /tmp before installing. APT reads local .deb files as the unprivileged _apt user; files in your home directory are not readable by that user and trigger an "unsandboxed as root" notice. /tmp is world-readable and avoids this.

# Replace <version> with the release tag (e.g. v0.3.46)
curl -L -o /tmp/mvgc-gateway.deb \
  https://github.com/Axemere-LLC/mvgc-releases/releases/download/<version>/mvgc-gateway_<version>_linux_amd64.deb

sudo apt install /tmp/mvgc-gateway.deb

After install, configure the gateway before starting it. Edit /etc/mvgc/mvgc.yaml and set database.url and gateway.admin_token at minimum, then enable the service:

sudo nano /etc/mvgc/mvgc.yaml
sudo systemctl enable --now mvgc-gateway

See Linux: Debian and Ubuntu for the full post-install configuration walkthrough, including credential and policy setup -- those steps are identical inside WSL2.

You can also install via the APT repository to enable apt upgrade for future releases. Open the Ubuntu WSL terminal and follow the Linux: Debian and Ubuntu instructions verbatim.

Option 3 -- Binary Download

Download the latest linux/amd64 tarball from the GitHub Releases page, extract it into your WSL home directory, and run the binary directly:

ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
URL=$(curl -fsSL https://api.github.com/repos/Axemere-LLC/mvgc-releases/releases/latest \
  | grep -oE "https://github.com/Axemere-LLC/mvgc-releases/releases/download/[^\"]+/mvgc-gateway_[0-9.]+_linux_${ARCH}\.tar\.gz" | head -1)
curl -fsSL "$URL" | tar -xz mvgc-gateway
chmod +x mvgc-gateway
./mvgc-gateway

Persistence: The binary download does not install a systemd service. To persist records across sessions, set MVGC_RECORD_LOG_FILE to a path outside /tmp before starting the gateway (e.g., export MVGC_RECORD_LOG_FILE=~/mvgc-records.jsonl).

Networking

The WSL2 VM has its own IP address, but Windows handles port forwarding automatically on Windows 11 -- services listening on localhost inside WSL2 are reachable at localhost on the Windows host without any extra configuration.

On Windows 10, port forwarding is not automatic. Use the WSL2 VM IP address instead:

# Run this inside WSL2 to find the VM IP
hostname -I

Then connect from Windows using that IP (e.g., http://172.x.x.x:7080).

If you need to reach the gateway from outside the Windows host, configure Windows Firewall rules to allow inbound traffic on port 7080.

CLI Tool

The .deb package installs the mvgc CLI to /usr/bin/mvgc alongside the gateway binary. Use it to verify connectivity after the service starts:

# Check that the gateway is reachable and healthy
mvgc health

# If running locally on the default port, set the URL once:
mvgc config set-url http://localhost:7080

WSL1 Fallback

If WSL2 cannot be installed (e.g., nested virtualization is unsupported by your hypervisor), Windows may silently fall back to WSL1.

How to check which version you have:

wsl --list --verbose

The VERSION column shows 1 or 2. If you see 1, you are on WSL1.

WSL1 limitations for Axemere Gateway:

  • No systemd. systemctl commands will fail with: 
    System has not been booted with systemd as init system (PID 1). Can't operate.
    This is a WSL1 symptom, not a gateway bug. Run the gateway binary directly (./mvgc-gateway) instead of as a systemd service.
  • Docker: Use Docker Desktop for Windows rather than APT-installing Docker inside WSL1. Docker Desktop integrates with WSL1 and WSL2 without requiring systemd.
  • Binary download (Option 3): This is the simplest path on WSL1 -- no systemd required. Download the linux/amd64 tarball and run the binary directly as described in Option 3 above.
  • PostgreSQL: Install via sudo apt install postgresql-16 (the PostgreSQL service must be started manually with sudo service postgresql start, not systemctl) or use a Docker Desktop container.

Recommended path on WSL1: Use Docker Desktop (Option 1) or the binary download (Option 3). Both work without systemd.

Known Limitations

  • WSL2 systemd has occasional quirks on first enable. If systemctl returns errors after enabling systemd in /etc/wsl.conf, run wsl --shutdown from PowerShell and relaunch the distro.
  • Keep all Axemere config and data files under the Linux filesystem (e.g., /etc/mvgc/, /var/lib/mvgc/) -- do not use Windows-mounted paths (/mnt/c/...). The Linux filesystem has significantly better I/O performance for file-heavy workloads, and Windows-mounted paths may interfere with the 0600 permission requirement on Ed25519 key files.
  • WSL2 does not support cgroup v1 in some configurations, which can prevent PostgreSQL from starting. If sudo systemctl start postgresql fails, check the output of sudo journalctl -u postgresql for cgroup-related errors. Upgrading to a recent WSL2 kernel or switching to a managed Postgres instance resolves this.
  • Native Windows (non-WSL) installation is not supported. Use WSL2 or Docker Desktop.

Trusting the CA Certificate

When using SSL MITM proxy mode inside WSL2, follow the Ubuntu/Debian trust store instructions since WSL2 runs Ubuntu:

See Linux (Debian/Ubuntu) -- Trusting the CA Certificate.

If Windows applications also need to connect through the proxy, you must install the CA certificate in both the WSL2 trust store and the Windows certificate store.

See Also