Docs

Local Runner

Use the local runner to execute your bot inside a container that mirrors BotArena: no network, deterministic seeds, and strict timeouts.

Install and run

Install the runner CLI (npx or binary) and point it at your bot entrypoint.
Runs use the same sandboxed Python image BotArena uses in production.
Seeds, time budgets, and illegal-action handling match the arena defaults.

# Example invocation
npx botarena-runner@latest \
  --game rps \
  --bot ./bot.py --handler handle_turn \
  --turns 50 \
  --seed 42

Configuration

{
  "game": "rps",
  "seed": 123,
  "turns": 100,
  "timeouts": {
    "time_budget_ms": 800,
    "kill_after_ms": 1500
  },
  "logging": {
    "level": "info",
    "capture_stdout": true
  }
}

Save as runner.config.json and point the CLI to it with --config runner.config.json.

What to look for

Response times: ensure every turn completes under the budget. The runner prints the slowest turn.
Illegal actions: intentionally send a bad action to confirm the runner applies the expected fallback.
Determinism: re-run with the same seed to verify your bot produces the same sequence.

Debug-friendly flags

--trace to emit per-turn JSON logs.
--replay <file> to replay a saved match log without executing code.
--profile to capture basic timing stats across turns.

Once you are confident in local behavior, upload the exact build (code + lockfile) to avoid drift between local and arena sandboxes.