PokeSim Agent

PokeSim's original autopilot, plus optional OpenAI, Gemini, and local ML agents.

Watch an automatic player catch Pokémon, earn badges and challenge the League in your browser. Take control whenever you like, then hand the adventure back.

This fork is built on upstream PokeSim. The default player is the upstream StrategicPolicy, so existing adventures behave exactly like original PokeSim. Each adventure can use different AI strategies: strategic default autopilot, vision model (any OpenAI-compatible endpoint), Gemini (Google's AI), local machine learning, or manual play. Optionally set per-adventure goals to guide the vision and remote agents. The emulator, library, settings, trading and statistics are upstream PokeSim's.

Five ways to play each adventure

AI player	Configuration	Network
Default	Upstream strategic autopilot, unchanged	None
Vision agent	OpenAI-compatible endpoint via AI_BASE_URL, AI_MODEL, AI_API_KEY	Yes
Gemini agent	Google Gemini via GEMINI_API_KEY (optional GEMINI_BASE_URL, GEMINI_MODEL)	Yes
ML agent	Local machine learning player with decision-tree learning	None
Manual only	You control the game via keyboard and on-screen buttons	None

Choose the player when creating an adventure, then switch live in Adventure settings. Optional per-adventure goals (max 2000 chars) guide vision and Gemini agents. ML agent learns from gameplay patterns without external services. See agent architecture and original PokeSim.

Keep the adventure going

• Many games side by side: Run any mix of Generation I and II adventures, each with its own saves and speed. Check CPU, memory and observed speed in the Library.
• A growing collection: Explore the Pokédex and search every PC box. Compare power, types and DV quality to find promising Pokémon.
• They trade with each other: Adventures meet in the in-game Cable Club and exchange Pokémon over a virtual link cable, including trade evolutions. Generation I and II games trade with each other through the Time Capsule.
• Milestones and stats: Follow catches, League wins, collection strength and marathon personal bests in the Journal.
• Life after the League: Keep training, rotate League teammates, revisit eligible encounters and earn new Pokémon.
• Your own touch: Add nickname prefixes and suffixes, take over the controls, or export your save to continue in another emulator.

Journal entries	Adventure stats

Generation I: Red, Blue and Yellow

Red and Blue adventures play the Kanto story to the Hall of Fame and keep going. Yellow starts with Pikachu and follows its own story, including Jessie and James and the gift starters. Exports are a standard .sav.

Generation II: Gold, Silver and Crystal

Gold, Silver and Crystal adventures earn all 16 badges, beat Red and work toward the 251-species Pokédex, with breeding, held items and roaming beasts. Crystal adds the Battle Tower and an optional Celebi event.

The cartridge clock that decides day, night and weekday events runs on game time. At 1x it keeps pace with a console, and at Max the days pass as fast as the run plays. Exports are a .zip holding the .sav and its .rtc clock file. Put both next to the ROM. How the clock works and cartridge details.

The collection is half the fun

Want every species? Run more than one game and let them trade version exclusives and trade evolutions automatically, across generations too. New adventures created in the Library have these rewards and return visits enabled by default, so the collection keeps growing beyond the original games' one-time encounters:

• Another Eevee, another fossil (Generation I): After becoming Champion and unlocking the original events, revisit gifts, fossils, the Fighting Dojo and supported NPC trades after 100,000 steps by default.
• Legendary rematches: Previously acquired legendary birds and Mewtwo, or the legendary beasts, Lugia and Ho-Oh, return to be caught again every 1,000,000 steps by default. Sudowoodo and Snorlax return in Generation II too.
• A mythical reward: A custom Mew gift arrives in the PC after your first League win. Mew isn't normally obtainable in these games. Another million steps followed by a new League win earns another.
• More starters: Receive a random Kanto starter in Generation I, or a random Johto starter in Generation II, after each new League win.

Change or disable these rewards in each adventure's settings. How return visits work.

Pokédex	PC collection

A few extras for the long run

• Meet WAFFLEKING: 6,117 built-in nicknames, plus your own prefixes and suffixes. Every collection deserves a few questionable names.
• Milestones in your pocket: Catch updates and adventure screenshots through ntfy, Discord or Telegram.
• The Kanto Marathon: Sometimes the next big goal is a run around Kanto. Follow the race and see whether your trainer beats their personal best.

Follow the changelog for new additions.

Your adventure library

Manage games in one place, with live screens, recent activity, CPU and memory usage, and the speed each simulation is actually reaching. Each game you own gets one cartridge slot in Settings → Game cartridges. Drop a ROM on any slot and PokeSim recognises the game and files it in the right one. New adventure then lets you pick from the cartridges you have installed.

Install

Bring your own supported Pokémon Red, Blue, Yellow, Gold, Silver or Crystal ROM that you are entitled to use. Supported builds are English USA/Europe, with Crystal Rev 1. Professor Oak supplies starters, not ROMs. PokeSim does not include or download ROMs. Your ROM stays on the machine running PokeSim.

Docker Compose (recommended)

The published image is ghcr.io/billbutter/pokesim-agent:latest for linux/amd64. Create a folder, drop your ROMs into roms/, and start it:

mkdir -p pokesim/roms pokesim/data
cd pokesim
cp /path/to/PokeSim-Agent/docker-compose.ghcr.yml docker-compose.yml
docker compose up -d --wait

Without a source checkout, save the docker-compose.ghcr.yml file from GitHub as docker-compose.yml. Supported .gb, .gbc and .zip files in roms/ are imported automatically at startup. The mount is read-only; saves, settings and generated game data live in data/.

Open 127.0.0.1:8000. The first adventure start downloads about 2 MB of reference data unless the image can reach GitHub. To run a vision adventure, set the endpoint before starting:

cat > .env <<'EOF'
AI_BASE_URL=http://host.docker.internal:11434/v1
AI_MODEL=qwen2.5-vl
AI_API_KEY=
EOF
docker compose up -d

Build the image locally instead:

git clone https://github.com/BillButter/PokeSim-Agent.git
cd PokeSim-Agent
mkdir -p roms data
docker compose up -d --build --wait

The image runs as UID/GID 1000. If your host user differs, chown the data folder or uncomment the user: line in the Compose file. Keep the port bound to loopback unless you put an authenticated proxy in front.

Already installed? Back up data/, then update the image or rebuild. The data directory layout follows upstream PokeSim. See operations and self-hosting.

Podman Quadlet

deploy/pokesim-agent.container runs the published image with registry auto-updates. See the Quadlet guide.

Run from source

Python 3.12 or newer and uv are required. The emulator backend and generated game data are installed by the project.

git clone https://github.com/BillButter/PokeSim-Agent.git
cd PokeSim-Agent
uv sync --extra acceleration
mkdir -p roms data
ROM_DIR=roms DATA_DIR=data uv run python -m pokesim serve --data-dir data

Open http://127.0.0.1:8000. Game data is prepared on first adventure start. Pass --game-data-dir only when you already have a prepared reference directory.

Games continue after you close the browser tab. Keep the host awake and use Save and quit to stop cleanly. The Library has no login, so anyone who can reach it can manage it. Default installations bind to localhost. Never expose it directly to the internet. For remote access, put it behind something that adds authentication, such as Tailscale, Cloudflare Access, or your own reverse proxy with a login.

Help and documentation

Adventures can reach the Hall of Fame, but the automatic player can still get stuck. See release status and known limits.

• Gameplay and notifications
• Statistics and counting rules
• Backups and troubleshooting
• Authentication and view links
• Report a bug or request a feature
• Discussions and contributing
• Security and community guidelines

PokeSim Agent is an unofficial fan project, unaffiliated with Pokémon's rights holders. The upstream PokeSim code is MIT licensed, and this fork keeps the same licence. ROMs, model credentials and generated game data are not distributed. The default player uses local rules; only the optional vision player contacts the configured model endpoint. See third-party notices and dependency licenses.