Overview

dosbox-automation exposes the emulator's internals through an HTTP REST API. Any tool that can make HTTP requests -- a shell script, a Python program, a game launcher, or an automated test harness -- can control what happens inside DOSBox.

What you can do

Install games without touching the keyboard. Send keystrokes and mouse events through the API to walk through an installer. Swap disk images on the fly for multi-disk installs. The entire process can run unattended, and install recipes describe whole installations as declarative TOML files.

Record and replay input. Capture a sequence of keyboard and mouse events with frame-accurate timing. Play it back later for regression testing or generating screenshots. The replay is deterministic -- same inputs, same frames, same results.

Inspect the machine while it runs. Read CPU registers, peek into memory at any address, read back DOS internal data structures. Useful for debugging, reverse engineering, or building cheat tools.

Run Lua scripts inside the emulator. Load sandboxed Lua scripts that interact with the emulated machine directly: read the screen, send input, inspect memory, wait for specific text to appear. Scripts run as coroutines, yielding between frames, so they stay in sync with the emulation without polling from the outside. Results are returned through the API.

Capture what's on screen. Pull the current video frame as a PNG or JPEG through the API. Record the screen to ZMBV-encoded AVI files for later analysis. Use it for automated screenshots, visual diffing between versions, or building promo footage.

Lock down host access. Mount operations are validated against a whitelist. Directory mounts are restricted to configured paths. Image mounts require structural validation (real disk images, not arbitrary files). A one-way mount lock freezes the drive layout after installation completes, so a running game cannot mount new host directories.

Control the emulator lifecycle. Start dosbox-automation from a launcher, configure it through files or command-line flags, monitor its status via the web server API, and shut it down cleanly when done. Token provisioning supports environment variables and file-based handoff for integration with launchers and CI systems.

Integration patterns

Game launchers use the API to install games, configure DOSBox for each title, launch it, and clean up afterwards. The launcher talks to the webserver while dosbox-automation handles the DOS side.

Scripted installs walk through game installers by sending input sequences or running a Lua script that waits for prompts and responds. Combined with disk swapping, this handles even installers that span multiple floppies or CDs. The mount lock secures the host filesystem after install completes.

Regression testing records a known-good play session and replays it after code changes. The frame capture endpoint and ZMBV video recording let you compare visual output between runs. Lua scripts can assert on screen content directly.

CI/CD pipelines for DOS software can start dosbox-automation in headless mode, run a build or test suite inside DOS, check the exit state, and capture output -- all from a shell script.

AI-assisted testing

dosbox-automation's REST API provides the building blocks for automated testing pipelines, including ones driven by AI agents.

The interface is straightforward: any client that can make HTTP requests can drive the emulator. What makes it useful for AI-assisted testing is the combination of endpoints:

  • Frame capture delivers the current screen as a PNG image. Combined with OCR or visual recognition, an automated agent can read what is on screen -- menus, dialog boxes, error messages, game state.

  • Keyboard and mouse injection sends input events to the emulated DOS environment. An agent can type commands, navigate menus, click buttons, and interact with software the same way a human would.

  • Memory and CPU register inspection exposes the internal state of the emulated machine. An agent can verify that a game loaded correctly, check specific memory addresses for expected values, or read CPU flags during debugging.

  • Program state monitoring reports what the emulator is doing: whether a program is running, what state the machine is in. An agent can wait for an installer to finish or detect when a game has crashed.

With Lua scripting, much of this can run inside the emulator rather than through external HTTP calls. A Lua script can read the screen with dosbox.screen_text(), wait for specific output with dosbox.wait_for_text(), and respond with input - all at frame-level granularity, without network round-trips. External AI agents coordinate through the REST API; the Lua engine handles the low-latency interaction loop.

These capabilities make it possible to build automated QA pipelines for DOS software - including ones where the testing agent makes decisions based on what it sees on screen, not just hardcoded input sequences.

For MCP-capable clients like Claude Code there is a ready-made bridge: dosbox-mcp on PyPI wraps this REST API as MCP tools, so an agent gets the screen, input, memory, and Lua endpoints without writing any HTTP glue. One line sets it up:

claude mcp add dosbox -- uvx dosbox-mcp