A safer DOSBox fork with an HTTP REST API, sandbox Lua scripting, and frame-accurate input recording - for gamers, game recordings, game launchers, and CI pipelines alike.
Available for Linux, Windows | Downloads | Documentation | Security
Download from the releases page, unpack, run. Linux ships as a portable tarball and AppImage, Windows as a zip and installer.
To use the API, add webserver_enabled = true to the [webserver] section in your config. The Swagger UI is then at http://localhost:8386 with every endpoint documented and testable.
The project manual has the rest.
All screenshots captured from dosbox-automation's own rendering, with adaptive CRT shaders and correct aspect ratios - zero configuration.
dosbox-automation runs DOS games with good defaults for graphics and sound. The automation features are additional, not a replacement for normal use.
Better sound: dosbox-automation includes the FluidR3 soundfont. General MIDI games sound right on the first run. Sound Blaster 16, AdLib, Gravis UltraSound, MT-32 emulation is included, as well the traditional PC beeper for old games.
CRT shaders: A combination of shaders simulate the look of old CRT monitors of yesteryear. The right shader settings for each graphics mode are picked automatically across CGA, EGA, VGA, SVGA, Tandy, and Hercules, with correct aspect ratios and integer scaling.
Video and image capture: You can record your gameplay with CTRL+F7, dosboxctl (included helper script in source distribution) or programmatic API calls, either in the original screen resolution or as they are rendered on screen.
Safer to run: DOS games you download can be setup to only access folders where your dosbox configuration lives and it is harder for malicious setups to do harm to your computer.
Left to right: Legend of Kyrandia 2: Hand of Fate on VGA, Blockout on Hercules, Railroad Tycoon on EGA.
For the full feature set see the documentation.
dosbox-automation has an HTTP REST API and a Lua scripting engine built in. You can install games, type commands, swap disks, grab screenshots, and shut down the emulator without ever touching the keyboard.
To get started, enable the web server in your config and set up a token. Every API call needs one.
[webserver]
webserver_enabled = true
webserver_token_file = trueStart dosbox-automation, wait a couple of seconds, and the token is written to ~/.config/dosbox-automation/webserver/api_token. You can also set the DOSBOX_API_TOKEN environment variable before starting if you prefer to generate your own. The Swagger UI is at http://localhost:8386 once the server is running.
# grab a screenshot
curl -s http://localhost:8386/api/v1/video/frame \
-H "Authorization: Bearer $TOKEN" \
--output screenshot.png
# read what is on screen (text modes)
curl -s http://localhost:8386/api/v1/video/text \
-H "Authorization: Bearer $TOKEN"
# type a command
curl -X POST http://localhost:8386/api/v1/input/type \
-H "Authorization: Bearer $TOKEN" \
-d '{"text": "dir c:\n"}'Lua scripts run on the emulation thread with frame-accurate timing. They can wait for specific text on screen, navigate setup menus, swap floppy disks, and report results back through the API.
Games can also be installed from TOML recipe files. A Python reference harness reads the recipe, downloads the media, runs the installer unattended, and handles multi-disk floppy swaps:
[game]
name = "DOOM Shareware"
publisher = "id Software"
year = 1993
[install]
media = [{ type = "cdrom", path = "doom-shareware.iso" }]
target = "C:\\DOOM"Keyboard and mouse input can be recorded as JSON and replayed frame-accurately on another machine. The recording includes the CPU speed and keyboard layout so the replay is deterministic.
The API also gives you read and write access to guest memory and CPU registers. Useful for debugging DOS programs, building trainers, or writing test assertions that check what the game actually did.
The test suite has over 1100 C++ unit tests and 160 Python integration tests. Several of those are full game installations that run end to end through the API.
Recorded and scripted with the included reference harness, driving the emulator through the REST API.
| Quest for Glory IV | System Shock |
| Floppy install with automated disk swaps | CD-ROM install, fully unattended |
| DOOM shareware | Epic Pinball |
| Install and launch | Installation replay |
| The Incredible Machine | Turbo Pascal 5.5 |
| Demo install by recipe | Compiler install, scripted end to end |
Watch the videos on dosbox-automation.org
An HTTP server inside an emulator is an attack surface and we treat it as one: bearer-token auth on every endpoint, host header validation, and mount restrictions that limit what the guest can reach on the host. The security policy has the details.
Security reports go to the contact address in the policy. Everything else goes on the issue tracker.
dosbox-automation's upstream code, its modifications and contributors is licensed under the GNU General Public License v2.0 or later.
This project is developed with the help of tooled assistance, but tested, reviewed and signed off by a human developer.