Timmy-time-dashboard/docs/research/bannerlord-vm-setup.md

Bannerlord Windows VM Setup Guide

Issue: #1098 Parent Epic: #1091 (Project Bannerlord) Date: 2026-03-23 Status: Reference

---

Overview

This document covers provisioning the Windows VM that hosts Bannerlord + GABS mod, verifying the GABS TCP JSON-RPC server, and confirming connectivity from Hermes.

Architecture reminder:

Timmy (Qwen3 on Ollama, Hermes M3 Max)
  → GABS TCP/JSON-RPC (port 4825)
    → Bannerlord.GABS C# mod
      → Game API + Harmony
        → Bannerlord (Windows VM)

---

1. Provision Windows VM

Minimum Spec

Resource	Minimum	Recommended
CPU	4 cores	8 cores
RAM	16 GB	32 GB
Disk	100 GB SSD	150 GB SSD
OS	Windows Server 2022 / Windows 11	Windows 11
Network	Private VLAN to Hermes	Private VLAN to Hermes

Hetzner (preferred)

# Hetzner Cloud CLI — create CX41 (4 vCPU, 16 GB RAM, 160 GB SSD)
hcloud server create \
  --name bannerlord-vm \
  --type cx41 \
  --image windows-server-2022 \
  --location nbg1 \
  --ssh-key your-key

DigitalOcean alternative

Droplet: General Purpose 4 vCPU / 16 GB / 100 GB SSD
Image: Windows Server 2022
Region: Same region as Hermes

Post-provision

1. Enable RDP (port 3389) for initial setup only — close after configuration
2. Open port 4825 TCP inbound from Hermes IP only
3. Disable Windows Firewall for 4825 or add specific allow rule:

   New-NetFirewallRule -DisplayName "GABS TCP" -Direction Inbound `
     -Protocol TCP -LocalPort 4825 -Action Allow
   

---

2. Install Steam + Bannerlord

Steam installation

1. Download Steam installer from store.steampowered.com
2. Install silently:

   .\SteamSetup.exe /S
   

3. Log in with a dedicated Steam account (not personal)

Bannerlord installation

# Install Bannerlord (App ID: 261550) via SteamCMD
steamcmd +login <user> <pass> +app_update 261550 validate +quit

Pin game version

GABS requires a specific Bannerlord version. To pin and prevent auto-updates:

1. Right-click Bannerlord in Steam → Properties → Updates
2. Set "Automatic Updates" to "Only update this game when I launch it"
3. Record the current version in docs/research/bannerlord-vm-setup.md after installation

# Check installed version
Get-Content "C:\Program Files (x86)\Steam\steamapps\appmanifest_261550.acf" |
  Select-String "buildid"

---

3. Install GABS Mod

Source

• NexusMods: https://www.nexusmods.com/mountandblade2bannerlord/mods/10419
• GitHub: https://github.com/BUTR/Bannerlord.GABS
• AGENTS.md: https://github.com/BUTR/Bannerlord.GABS/blob/master/AGENTS.md

Installation via Vortex (NexusMods)

1. Install Vortex Mod Manager
2. Download GABS mod package from NexusMods
3. Install via Vortex — it handles the Modules/ directory layout automatically
4. Enable in the mod list and set load order after Harmony

Manual installation

# Copy mod to Bannerlord Modules directory
$BannerlordPath = "C:\Program Files (x86)\Steam\steamapps\common\Mount & Blade II Bannerlord"
Copy-Item -Recurse ".\Bannerlord.GABS" "$BannerlordPath\Modules\Bannerlord.GABS"

Required dependencies

• Harmony (BUTR.Harmony) — must load before GABS
• ButterLib — utility library Install via the same method as GABS.

GABS configuration

GABS TCP server listens on 0.0.0.0:4825 by default. To confirm or override:

%APPDATA%\Mount and Blade II Bannerlord\Configs\Bannerlord.GABS\settings.json

Expected defaults:

{
  "ServerHost": "0.0.0.0",
  "ServerPort": 4825,
  "LogLevel": "Information"
}

---

4. Verify GABS TCP Server

Start Bannerlord with GABS

Launch Bannerlord with the mod enabled. GABS starts its TCP server during game initialisation. Watch the game log for:

[GABS] TCP server listening on 0.0.0.0:4825

Log location:

%APPDATA%\Mount and Blade II Bannerlord\logs\rgl_log_*.txt

Local connectivity check (on VM)

# Verify port is listening
netstat -an | findstr 4825

# Quick TCP probe
Test-NetConnection -ComputerName localhost -Port 4825

Send a test JSON-RPC call

$msg = '{"jsonrpc":"2.0","method":"ping","id":1}'
$client = New-Object System.Net.Sockets.TcpClient("localhost", 4825)
$stream = $client.GetStream()
$writer = New-Object System.IO.StreamWriter($stream)
$writer.AutoFlush = $true
$writer.WriteLine($msg)
$reader = New-Object System.IO.StreamReader($stream)
$response = $reader.ReadLine()
Write-Host "Response: $response"
$client.Close()

Expected response shape:

{"jsonrpc":"2.0","result":{"status":"ok"},"id":1}

---

5. Test Connectivity from Hermes

Use scripts/test_gabs_connectivity.py (checked in with this issue):

# From Hermes (M3 Max)
python scripts/test_gabs_connectivity.py --host <VM_IP> --port 4825

The script tests:

1. TCP socket connection
2. JSON-RPC ping round-trip
3. get_game_state call
4. Response latency (target < 100 ms on LAN)

---

6. Firewall / Network Summary

Source	Destination	Port	Protocol	Purpose
Hermes (local)	Bannerlord VM	4825	TCP	GABS JSON-RPC
Admin workstation	Bannerlord VM	3389	TCP	RDP setup (disable after)

---

7. Reproducibility Checklist

After completing setup, record:

• VM provider + region + instance type
• Windows version + build number
• Steam account used (non-personal, credentials in secrets manager)
• Bannerlord App version (buildid from appmanifest)
• GABS version (from NexusMods or GitHub release tag)
• Harmony version
• ButterLib version
• GABS settings.json contents
• VM IP address (update Timmy config)
• Connectivity test output from test_gabs_connectivity.py

---

References

• GABS GitHub: https://github.com/BUTR/Bannerlord.GABS
• GABS AGENTS.md: https://github.com/BUTR/Bannerlord.GABS/blob/master/AGENTS.md
• NexusMods page: https://www.nexusmods.com/mountandblade2bannerlord/mods/10419
• Parent Epic: #1091
• Connectivity test script: scripts/test_gabs_connectivity.py