Play Red Alert with AI agents. LLMs, scripted bots, or RL — your agent commands armies in the classic RTS through a Python API.

Website • Leaderboard • HuggingFace • Docs • Issues

pip install openra-rl
openra-rl play

On first run, an interactive wizard helps you configure your LLM provider (OpenRouter, Ollama, or LM Studio). The CLI pulls the game server Docker image and starts everything automatically.

# Cloud (OpenRouter)
openra-rl play --provider openrouter --api-key sk-or-... --model anthropic/claude-sonnet-4-20250514

# Local (Ollama — free, no API key)
openra-rl play --provider ollama --model qwen3:32b

# Developer mode (skip Docker, run server locally)
openra-rl play --local --provider ollama --model qwen3:32b

# Reconfigure later
openra-rl config

• Docker — the game server runs in a container
• Python 3.10+
• An LLM endpoint (cloud API key or local model server)

openra-rl play       Run the LLM agent (wizard on first use)
openra-rl config     Re-run the setup wizard
openra-rl server     start | stop | status | logs
openra-rl replay     watch | list | copy | stop
openra-rl bench      submit   Upload results to the leaderboard
openra-rl mcp-server Start MCP stdio server (for OpenClaw / Claude Desktop)
openra-rl doctor     Check system prerequisites
openra-rl version    Print version

OpenRA-RL exposes all 48 game tools as a standard MCP server:

openra-rl mcp-server

Add to your MCP client config (e.g. ~/.openclaw/openclaw.json):

{
  "mcpServers": {
    "openra-rl": {
      "command": "openra-rl",
      "args": ["mcp-server"]
    }
  }
}

Then chat: "Start a game of Red Alert on easy difficulty, build a base, and defeat the enemy."

Data flow: Agent <-> FastAPI (port 8000) <-> gRPC bridge (port 9999) <-> OpenRA game engine

The game runs at ~25 ticks/sec independent of agent speed. Observations use a DropOldest channel so the agent always sees the latest game state, even if it's slower than real time.

A hardcoded state-machine bot that demonstrates all action types. Deploys MCV, builds a base, trains infantry, and attacks.

python examples/scripted_bot.py --url http://localhost:8000 --verbose --max-steps 2000

A planning-aware bot that uses game knowledge tools (tech tree lookups, faction briefings, map analysis) to formulate strategy before playing.

python examples/mcp_bot.py --url http://localhost:8000 --verbose --max-turns 3000

An AI agent powered by any OpenAI-compatible model. Supports cloud APIs (OpenRouter, OpenAI) and local model servers (Ollama, LM Studio).

python examples/llm_agent.py \
  --config examples/config-openrouter.yaml \
  --api-key sk-or-... \
  --verbose \
  --log-file game.log

CLI flags override config file values. See python examples/llm_agent.py --help for all options.

OpenRA-RL uses a unified YAML config system. Settings are resolved with this precedence:

CLI flags > Environment variables > Config file > Built-in defaults

Copy and edit the default config:

cp config.yaml my-config.yaml
# Edit my-config.yaml, then:
python examples/llm_agent.py --config my-config.yaml

Key sections:

game:
  openra_path: "/opt/openra"      # Path to OpenRA installation
  map_name: "singles.oramap"      # Map to play
  headless: true                  # No GPU rendering
  record_replays: false           # Save .orarep replay files

opponent:
  bot_type: "normal"              # AI difficulty: easy, normal, hard
  ai_slot: "Multi0"              # AI player slot

planning:
  enabled: true                   # Pre-game planning phase
  max_turns: 10                   # Max planning turns
  max_time_s: 60.0                # Planning time limit

llm:
  base_url: "https://openrouter.ai/api/v1/chat/completions"
  model: "qwen/qwen3-coder-next"
  max_tokens: 1500
  temperature: null               # null = provider default

tools:
  categories:                     # Toggle tool groups on/off
    read: true
    knowledge: true
    movement: true
    production: true
    # ... see config.yaml for all categories
  disabled: []                    # Disable specific tools by name

alerts:
  under_attack: true
  low_power: true
  idle_production: true
  no_scouting: true
  # ... see config.yaml for all alerts

# Pull a model with tool-calling support
ollama pull qwen3:32b

# For models that need more context (default is often 2048-4096 tokens):
cat > /tmp/Modelfile <<EOF
FROM qwen3:32b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-32k -f /tmp/Modelfile

# Run
openra-rl play --provider ollama --model qwen3-32k

Note: Not all Ollama models support tool calling. Check with ollama show <model> — the template must include a tools block. Models known to work: qwen3:32b, qwen3:4b.

1. Load a model in LM Studio and start the local server (default port 1234)
2. Run:

openra-rl play --provider lmstudio --model <model-name>

openra-rl server start              # Start game server container
openra-rl server start --port 9000  # Custom port
openra-rl server status             # Check if running
openra-rl server logs --follow      # Tail logs
openra-rl server stop               # Stop container

# LLM agent via Docker Compose
OPENROUTER_API_KEY=sk-or-... docker compose up agent

After each game, replays are automatically copied to ~/.openra-rl/replays/. Watch them in your browser:

openra-rl replay watch              # Watch the latest replay (opens browser via VNC)
openra-rl replay watch <file>       # Watch a specific .orarep file
openra-rl replay list               # List replays (Docker + local)
openra-rl replay copy               # Copy replays from Docker to local
openra-rl replay stop               # Stop the replay viewer

The replay viewer runs inside Docker using the same engine that recorded the game, so replays always play back correctly. The browser connects via noVNC — no local game install needed.

Version tracking: Each replay records which Docker image version was used. When you upgrade, old replays are still viewable using their original engine version.

For running the game server natively (macOS/Linux):

OpenRA/ is a git submodule — clone it alongside the repo:

git clone --recurse-submodules https://github.com/yxc20089/OpenRA-RL.git

Or if you already cloned without submodules:

git submodule update --init --recursive

Create and activate a dedicated environment (Python 3.10 recommended):

Conda:

conda create --name openra python=3.10
conda activate openra

venv:

python3.10 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -e ".[dev]"

macOS (Apple Silicon):

brew install dotnet@8
echo 'export PATH="/opt/homebrew/opt/dotnet@8/bin:$PATH"' >> ~/.profile
source ~/.profile

macOS (Intel): same, but replace /opt/homebrew with /usr/local.

Ubuntu/Debian:

sudo apt install dotnet-sdk-8.0

Other Linux: see https://learn.microsoft.com/dotnet/core/install/linux

macOS:

brew install sdl2 openal-soft freetype luajit

Ubuntu/Debian:

sudo apt install libsdl2-dev libopenal-dev libfreetype-dev libluajit-5.1-dev

cd OpenRA && make && cd ..

Known build issue (macOS + .NET 8): If you see error CS0121: The call is ambiguous for CryptoUtil.SHA1Hash in OpenRA.Game/Map/Map.cs, change line 286 from:

return CryptoUtil.SHA1Hash([]);

to:

return CryptoUtil.SHA1Hash(Array.Empty<byte>());

Then re-run make.

cp $(brew --prefix sdl2)/lib/libSDL2.dylib OpenRA/bin/SDL2.dylib
cp $(brew --prefix openal-soft)/lib/libopenal.dylib OpenRA/bin/soft_oal.dylib
cp $(brew --prefix freetype)/lib/libfreetype.dylib OpenRA/bin/freetype6.dylib
cp $(brew --prefix luajit)/lib/libluajit-5.1.dylib OpenRA/bin/lua51.dylib

On Linux this step is not needed.

Set game.openra_path to the absolute path of the OpenRA/ directory:

game:
  openra_path: "/path/to/OpenRA-RL/OpenRA"  # use $(pwd)/OpenRA
  headless: true   # true = no window, runs anywhere (recommended for agents)
                   # false = opens a real OpenRA window so you can watch live

Use headless: true for agent training and CI. Use headless: false only if you want to watch the game in a live OpenRA window (requires a display and SDL2).

openra-rl play --local --provider ollama --model qwen3:32b

python openra_env/server/app.py

pytest

Each tick, the agent receives structured game state:

18 action types available through the command API:

The LLM agent interacts through 48 MCP (Model Context Protocol) tools organized into categories:

Tools can be toggled per-category or individually via config.yaml.

Game results are automatically submitted to the OpenRA-Bench leaderboard after each game. Disable with BENCH_UPLOAD=false or bench_upload: false in config.

Customize how your agent appears on the leaderboard:

# Environment variables
AGENT_NAME="DeathBot-9000" AGENT_TYPE="RL" openra-rl play

# Or in config.yaml
agent:
  agent_name: "DeathBot-9000"
  agent_type: "RL"
  agent_url: "https://github.com/user/deathbot"  # shown as link on leaderboard

Upload a saved result (with optional replay file):

openra-rl bench submit result.json
openra-rl bench submit result.json --replay game.orarep --agent-name "MyBot"

If you're building your own agent (RL, CNN, multi-agent, etc.) that doesn't use the built-in LLM agent, use build_bench_export() to create a leaderboard submission from a final observation:

from openra_env.bench_export import build_bench_export

# obs = final observation from env.step()
export = build_bench_export(
    obs,
    agent_name="DeathBot-9000",
    agent_type="RL",
    opponent="Normal",
    agent_url="https://github.com/user/deathbot",
    replay_path="/path/to/replay.orarep",
)
# Saves JSON to ~/.openra-rl/bench-exports/ and returns dict with "path" key

Then submit:

openra-rl bench submit ~/.openra-rl/bench-exports/bench-DeathBot-9000-*.json --replay game.orarep

OpenRA-RL/
├── OpenRA/                     # Game engine (git submodule, C#)
├── openra_env/                 # Python package
│   ├── cli/                    #   CLI entry point (openra-rl command)
│   ├── mcp_server.py           #   Standard MCP server (stdio transport)
│   ├── client.py               #   WebSocket client
│   ├── config.py               #   Unified YAML configuration
│   ├── models.py               #   Pydantic data models
│   ├── game_data.py            #   Unit/building stats, tech tree
│   ├── reward.py               #   Multi-component reward function
│   ├── bench_export.py         #   Build leaderboard submissions from observations
│   ├── bench_submit.py         #   Upload results to OpenRA-Bench leaderboard
│   ├── opponent_intel.py       #   AI opponent profiles
│   ├── mcp_ws_client.py        #   MCP WebSocket client
│   ├── server/
│   │   ├── app.py              #     FastAPI application
│   │   ├── openra_environment.py  #  OpenEnv environment (reset/step/state)
│   │   ├── bridge_client.py    #     Async gRPC client
│   │   └── openra_process.py   #     OpenRA subprocess manager
│   └── generated/              #   Auto-generated protobuf stubs
├── examples/
│   ├── scripted_bot.py         #   Hardcoded strategy bot
│   ├── mcp_bot.py              #   MCP tool-based bot
│   ├── llm_agent.py            #   LLM-powered agent
│   └── config-*.yaml           #   Example configs (ollama, lmstudio, openrouter, minimal)
├── skill/                      # OpenClaw skill definition
├── proto/                      # Protobuf definitions (rl_bridge.proto)
├── tests/                      # Test suite
├── .github/workflows/          # CI, Docker publish, PyPI publish
├── config.yaml                 # Default configuration
├── docker-compose.yaml         # Service orchestration
├── Dockerfile                  # Game server image
└── Dockerfile.agent            # Lightweight agent image

GPL-3.0