WoWS Remote Agent

A restricted remote control agent for Windows. It lets Codex or other MCP/HTTP-capable AI, over a Tailscale private network, do the following:

• View game PC and World of Warships process status;

• Capture current desktop screenshot;

• Launch and focus locally configured game programs;

• Click locally calibrated menu positions;

• Execute pre-audited menu workflows;

• Emergency stop via local Ctrl+Alt+F12 or remote abort at any time.

The project does not provide autopilot, aiming, firing, AFK farming, or anti-detection. It is not an official Wargaming project and is not affiliated with Wargaming.

Safety Boundaries

The agent has no arbitrary shell, arbitrary program launch, or file management interfaces. The remote side can only launch the single program specified in the configuration file; the keyboard whitelist includes only menu keys such as Enter, Esc, Tab, Space, and arrow keys, not W/A/S/D. Arbitrary single-step clicks are disabled by default; only locally configured workflows are allowed.

All write operations are recorded at:

C:\ProgramData\WoWSRemoteAgent\logs\audit.jsonl

The start_battle workflow also requires the AI to pass confirmed=true when calling it. This cannot replace your supervision; only use it when you can see the game PC screen.

World of Warships Rule 5.07 prohibits using bots, clickers, macros, and similar schemes when players are not participating or are passively participating. There is no automation exemption for cooperative mode. Therefore this project is only for launch and menu navigation, and should not be extended into an automated battle tool. Please verify the latest rules in your region before use.

Related MCP server: Desktop Commander MCP Server

Quickest Installation

Requirements:

• Game PC running Windows 10/11;

• Open PowerShell as administrator;

• Windows has winget, or Python 3.11+ already installed;

• Game uses borderless window, with fixed resolution and UI scaling.

Run in admin PowerShell:

Set-ExecutionPolicy -Scope Process Bypass -Force
irm https://raw.githubusercontent.com/jesson-hh/wows-remote-agent/v0.1.0/scripts/bootstrap.ps1 | iex

This is a one-liner for convenient first-time installation that directly executes a script from GitHub. For higher security requirements, first download and read bootstrap.ps1, verify the repository and version before running; in production, it is recommended to pin to a specific release tag rather than following main long-term.

The installer will:

1. Install or reuse Python 3.11+;

2. Create an isolated virtual environment;

3. Install Tailscale, and guide login if needed;

4. Generate a 64-character random access token;

5. Allow only the Tailscale address range to access the agent port;

6. Create a scheduled task for "after user logon";

7. Generate C:\ProgramData\WoWSRemoteAgent\connection.json.

If you don't want the installer to manage Tailscale:

irm https://raw.githubusercontent.com/jesson-hh/wows-remote-agent/v0.1.0/scripts/bootstrap.ps1 -OutFile "$env:TEMP\wows-bootstrap.ps1"
& "$env:TEMP\wows-bootstrap.ps1" -SkipTailscale

Do not upload connection.json to GitHub, cloud drives, or chat groups. It contains the access token.

Set Game Path

If not filled in during installation, run in admin PowerShell:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\configure.ps1' `
  -GamePath 'D:\Games\World_of_Warships\WorldOfWarships.exe'

Please fill in the actual launcher program on your PC. The installer does not scan or modify game files.

Calibrate Co-op Mode Buttons

Keep the game at a fixed resolution and borderless window. After each command run, move the mouse to the corresponding button before the countdown ends; do not click:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name battle_type_button
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name coop_mode
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name confirm_mode
& 'C:\ProgramData\WoWSRemoteAgent\scripts\calibrate.ps1' -Name battle_button

Correspondingly:

1. Battle type button in the port;

2. Co-op mode option;

3. Mode selection confirm button;

4. "Start Battle" button.

Recalibrate after changing resolution, monitor primary/secondary order, or Windows scaling.

Check Game PC

& 'C:\ProgramData\WoWSRemoteAgent\scripts\doctor.ps1'

If local health check fails:

Get-ScheduledTask -TaskName 'WoWS Remote Agent'
Start-ScheduledTask -TaskName 'WoWS Remote Agent'
Get-Content 'C:\ProgramData\WoWSRemoteAgent\logs\audit.jsonl' -Tail 30

The agent must run in an interactive Windows session that is logged in. Windows services run in Session 0, which cannot reliably screenshot or click the desktop, so the installer uses a "start at logon" scheduled task; desktop control will not work after lock screen or logout.

Connect Codex on Control PC

First, have both PCs log into the same Tailscale tailnet. Securely copy connection.json from the game PC to the control PC, then run on the control PC:

git clone https://github.com/jesson-hh/wows-remote-agent.git
cd wows-remote-agent
& .\scripts\configure-codex.ps1 -ConnectionFile 'D:\Safe\connection.json'

The script will:

• Write the access token into the current Windows user's WOWS_REMOTE_AGENT_TOKEN environment variable;

• Use codex mcp add to register the Streamable HTTP MCP;

• Not write the plaintext token into Codex config.toml.

Restart the ChatGPT/Codex desktop app and enter /mcp; you should see wows-remote-agent.

You can also configure manually:

[mcp_servers.wows-remote-agent]
url = "http://100.x.y.z:8765/mcp"
bearer_token_env_var = "WOWS_REMOTE_AGENT_TOKEN"
default_tools_approval_mode = "prompt"
tool_timeout_sec = 150

Test Remote Connection

Run on the control PC:

& .\scripts\test-connection.ps1 -AgentIP 100.x.y.z

The test script hides the entered token, then verifies /health and the authenticated /v1/status.

What to Say to Codex

It is recommended to issue instructions in small steps:

检查游戏电脑状态，不要执行操作。

运行 open_game，等它完成后截图并告诉我当前界面。

先截图；只有画面确实是港口时才运行 enter_coop，然后再次截图。

我确认现在可以点击开始战斗。运行 start_battle，confirmed=true，然后停止操作。

If the UI differs from expected:

立即调用 abort，不要尝试猜测按钮。

MCP Tools

The REST equivalent endpoints are at /v1/*, all requiring Authorization: Bearer ...; only /health does not require a token.

Update

Re-run the same command to reinstall the current pinned version, preserving existing config.json, calibration points, access token, and logs. When upgrading, replace v0.1.0 in the command with the new version listed on the GitHub Releases page. It is still recommended to back up before installation or upgrade:

Copy-Item 'C:\ProgramData\WoWSRemoteAgent\config.json' "$env:USERPROFILE\Desktop\wows-agent-config.backup.json"

Uninstall

Keep configuration and logs:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\uninstall.ps1' -KeepConfig

Fully delete the agent, configuration, and logs:

& 'C:\ProgramData\WoWSRemoteAgent\scripts\uninstall.ps1'

The uninstall script will not uninstall Tailscale, Python, or the game.

Development

py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install -e '.[test]'
.\.venv\Scripts\python -m ruff check .
.\.venv\Scripts\python -m pytest

Copy the sample configuration, set a temporary token, and start locally:

Copy-Item config.example.json .local-config.json
$env:WOWS_AGENT_CONFIG = (Resolve-Path .local-config.json)
$env:WOWS_AGENT_TOKEN = 'development-token-at-least-32-characters'
.\.venv\Scripts\python -m wows_remote_agent --config .local-config.json --host 127.0.0.1

See Deployment and Troubleshooting and Security Model for more details.

The repository includes a GitHub Actions CI example. Repository maintainers, if the token has workflow permission, can copy it to .github/workflows/ci.yml to automatically run checks on Windows and Ubuntu with Python 3.11/3.12.