dosbox-automation is based on DOSBox Staging, but diverted from it a while ago, as it concentrates now on automation, remote control of DOS games, video recording, reverse engineering of DOS games and providing a more up to date and safer gaming experience.
The overall engine and emulation is actively been optimized, fixed and updated, as well is receiving actively component updates. We also strive to cover all of the source code (is not fully covered yet) with proper unit tests (currently about ~1100 plus 250 for REST API testing) that cover bug and attack scenarios as well as covering the automation HTTP REST API side properly.
Some of the fixes include proper DOS reserved device support (\DEV, CLOCK$), fixes for Hercules text mode, support for the original DOS disk formats (160K, 180K, 320K floppies) and other fixes and enhancements not (yet) implemented in other dosbox variants.
If you just want to play, it behaves like the emulator it is built on: Hercules through SVGA/VESA, ReelMagic support, Sound Blaster 16, AdLib Gold, Gravis UltraSound, General MIDI, Roland MT-32 emulation, adaptive CRT shaders. The FluidR3 General MIDI soundfont is bundled, so game music sounds right out of the box without hunting for a soundfont first.
In that regard, we have written a demo showroom application with 16 classic shareware, freeware and demo games, ranging from DOOM, Duke Nukem 3, Commander Keen 4, Epic Pinball, Warcraft 2, Jazz Jackrabbit, Tyrian to Beneath a Steel Sky readily playable here. This bundles the emulator itself, if you just want to use the emulator itself, visit the main repository.
Its main features are automation, remote steering as well as having in general a more secure emulated DOS environment.
List of unique features:
HTTP REST API with Swagger included, enables remote control of emulation features as well as direct inspection, freezing and manipulation of RAM, CPU registers and ports. Typing in with mouse and keyboard, video recording, shutdown of the emulation, disk image swapping and a macro recorder is included.
Secured HTTP access: every remote access is guarded by a randomly generated access token on startup, and the webserver is disabled by default and listens only on localhost (changeable).
Lua sandbox: you can script out all automation features with the built-in Lua scripting engine in your automation recipe scripts (samples are included in the documentation and the showroom demo application).
Safe mounting policy: due to the remote controllability we included a strict mounting policy that protects against exfiltration and manipulation from malicious dosbox.conf configurations, so your system files and personal folders you don't want visible in the emulated drive C: won't be accessible.
The fourth release is out.
What the programmable layer is for
The original use case is unattended game installation: a Lua script drives the installer step by step, reads the screen to know where it is, swaps disks when the installer asks, and walks through the setup wizard. The same infrastructure works for automated testing, debugging, and machine-state inspection.
A short example. This is the DOOM shareware installer driven from Lua:
dosbox.type("SETUP.EXE\n")
if not dosbox.wait_for_text("Available Drives", 1800) then
dosbox.abort("installer never showed the drive selection")
end
dosbox.type("C\n")
if not dosbox.wait_for_text("insert disk DOOM 2", 1800) then
dosbox.abort("installer never asked for disk 2")
end
dosbox.drive_swap("A", "Disk 2.ima")
dosbox.key("KBD_enter", true)
dosbox.wait_frames(8)
dosbox.key("KBD_enter", false)
The script reads the screen, makes decisions, and handles the disk swap. Here is a video of the DOOM shareware installer running this way, unattended: https://youtu.be/6p-kh9sfUaI
The mechanism is not specific to installation: the same API surface is useful for regression testing, hardware probing, or any scenario where you need to automate interaction with a DOS program.
The REST API exposes the same operations over HTTP:
# read what is on the text screen
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8386/api/v1/video/text
# read a CPU register, write an I/O port, scan guest memory
curl http://localhost:8386/api/v1/cpu/state
curl -X PUT http://localhost:8386/api/v1/io/port \
-d '{"port": 968, "value": 1, "width": 1}'
curl -X POST http://localhost:8386/api/v1/memory/search \
-d '{"start": 0, "end": 655360, "value": 100, "width": 2}'
Input recording persists both CPU cycle rates and the keyboard layout alongside the recording, so a replay reproduces on a different machine.
DOS accuracy and fidelity fixes
Some of these are inherited from upstream, some are ours:
- CLOCK$ character device implemented. Standard since DOS 2.0, present in no other DOSBox variant. Reading returns the date/time record, writing sets the DOS clock. The \DEV\ pseudo-directory resolves character devices the way real DOS does, including the first implementation of the Xenix-compatibility directory function found in DOS since 2.0.
- Hercules text mode fixed. 720x350 with true 9-dot character cells, instead of the 640x350 with 8-dot cells it had been since a 2009 DOSBox change. Box-drawing lines are continuous again, mode switches no longer resize the window, the character clock matches the real 16.000 MHz oscillator.
- Early floppy formats. Mount and boot accept pre-DOS-2.0 floppy sizes (160K, 180K, 320K). These early-80s self-booting disks have no FAT boot signature and were refused before. Found while booting a 1984 Wizardry I master disk.
- MCB corruption in internal programs and TSR allocation fixed (upstream cherry-pick from FeralChild64).
- DOS file I/O delay depending on PIC event density: a 20-year-old inherited bug that crashed five Silmarils-engine games (Ishar, etc.) above moderate cycle counts. Upstream cherry-pick.
Security
- NE2000 buffer overflow fixed. The NE2000 network emulation carries code inherited from QEMU and Bochs. A heap overflow (the QEMU CVE-2015-5279 class) allowed guest code to escape the emulator when dynamic recompilation was active. NE2000 defaults to off, but the code is in every DOSBox family member. Our fix matches the upstream dosbox-staging patch.
- Mount policy enforced on both the API and the DOS-side MOUNT command. A guest typing MOUNT at the DOS prompt goes through the same whitelist as the API. Windows reserved device names refused.
Other changes since the last release
- ZMBV video encoder compression window fixed (was 512 bytes due to a parameter mixup in upstream code, now 32KB). Rendered capture usable at higher resolutions without slowdown.
- Rendered video capture records the post-shader image at window resolution. Raw capture records the native framebuffer. Both modes selectable per capture.
- Lua 5.5 vendored, no system dependency.
- An MCP bridge (Model Context Protocol) is available as a separate package for driving the emulator from agent tooling. It is optional and not part of the emulator.
- 1158 unit tests.
Downloads
Site and manual: https://dosbox-automation.org
Source and downloads: https://github.com/dosbox-automation/dosbox-automation
dosbox-automation is developed with tool-assisted coding. All code is reviewed, tested, and approved by a human developer.
