# Run a bot in your browser

Play a bot from a web page, in Python, with nothing to install: on a computer, on a phone, or in the installed app.

Part of apigaming's docs: https://apigaming.com/docs (the bot API), https://apigaming.com/docs/tournaments.md, https://apigaming.com/docs/browser-bots.md,
and https://apigaming.com/agents.md (the complete guide in one file). The index is https://apigaming.com/llms.txt.

## What it is

- Run in browser runs your bot's Python code in the page itself (Pyodide, Python built for the browser). It plays through the same public API as any bot, with its own play key.
- Use the ready-made bot for a game (the same file as that game's starter bot on `/starter`), or your own file.

## Starting a bot

- Sign in and open My bots (`/bots`, a tab at the foot of the screen on a phone): every bot of the account (up to 10), each with Start and Stop, and Start all and Stop all. A bot's own page has the same controls for that bot on its Run in browser tab.
- Tick the games the bot should play: one chip per enabled game. A greyed-out game cannot run in the browser, and the reason is shown.
- For each game, choose the code: the ready-made bot, or your own Python file.
- On a bot's Run in browser tab, choose what it plays first: nobody yet (it connects and waits; take or post a challenge with it in the Lobby and it plays), the house at level 1, 2 or 3 (free practice), or another bot in the lobby (10 points at stake). Practice and the lobby play the first ticked game.
- Press Start. The first Start makes a play key for the browser. The page keeps it in memory: it is never shown, saved or put in a link. Starting again later makes a new one, which stops the bot wherever it ran in a browser before.

## Auto-play and the Lobby

- While a bot runs it tells the server which games it can play now (`POST /v1/me/ready`, every 30 s; it lapses 90 s after the last one). The Lobby then offers Take with <bot> in one tap.
- Auto-play, a switch per game, lets the server start lobby sets for the bot on its own: it keeps one quick-match seek for the bot at the default stake (50 points, within the game's limits and the bot's maximum stake). Each set stakes the bot's points. It plays one set of a game at a time and stops within seconds of Stop, or of the page closing.

## Your own bot file

- One Python file: `.py`, or `.txt` with Python in it (a phone may only save `.txt`), up to 200 KB.
- It defines `GAME_TYPE`, the game it plays (such as `"fourfall"`), and `choose(match, deadline)`, which returns the move as a dict, or `None` when it has nothing to post yet. `match` is the object `GET /v1/matches/{id}` returns; `deadline` is a `time.monotonic()` value to answer by. This is the same contract as `python -m bots.client`, so one file runs in the browser and on a computer alike.
- Name the file after your bot, not after a standard module such as `random.py` or `json.py`.
- It may use the Python standard library, except the modules a browser cannot run: `_thread`, `asyncio`, `concurrent`, `ctypes`, `curses`, `dbm`, `ensurepip`, `fcntl`, `idlelib`, `lzma`, `mmap`, `multiprocessing`, `pty`, `readline`, `resource`, `select`, `selectors`, `signal`, `socket`, `sqlite3`, `ssl`, `subprocess`, `termios`, `threading`, `tkinter`, `tty`, `turtle`, `venv`, `webbrowser`.
- The file stays in this browser (local storage) and is never uploaded. Another browser or device needs it picked again.

## How long it keeps playing

- In a browser tab the bot plays while the tab stays open. Reload or close the page and it disconnects, and a game in progress is lost on time; the page asks before you leave while bots play.
- In the installed app the bot keeps playing while you move around apigaming and stops when the app closes. A phone may pause it while the app is in the background.
- In turn-based games the runner waits a moment before each move so the log and the board can be followed. In games played in parallel (the race games) it posts at once.
- To keep a bot playing all the time, or to enter a tournament, run it on a computer or a VPS: the Run in browser tab offers the bot as a `.zip` and the command to run it.

## Safety

- The bot's code runs in a sandboxed frame: no cookies, no storage and no access to your session or the page. It can only call apigaming's API, with the bot's own key.