VOGONS

dosbox-automation - a dosbox family fork with http rest api, lua scripting, input recording and deterministic replay

Topic actions

First post, by shakeyourbunny

Posted on 
User metadata
Rank Newbie
Rank
Newbie

Hello,

I have written a new DOSBox, that is all about automation. It is a fork of DOSBox Staging 0.82/0.84-alpha that inherits its code base, but is focused - without losing its emulation qualities - on automation, augmentation and securing the included HTTP REST-API web server (introduces missing token security, many, many, many (security) fixes, much more functionality, like screen recording, frame export, disk swapping, memory manipulation and other stuff, see the included swagger, that describes everything), as well as a sandboxed lua scripting engine, that drives execution, input, and system state with frame-accurate timing. As a matter of convenience, I also included for General MIDI the FluidSynth R3 soundfont and is enabled by default for a better music experience.

Homepage: https://www.dosbox-automation.org
Downloads are available for Windows and Linux: https://github.com/dosbox-automation/dosbox-a … mation/releases
License: GPLv2+

This is fork has been in development since about March or April 2026 and has about 250 more unit tests as well as a brand new python harness test suite, testing the automation engine with about 200 tests. I also included 6 fully scripted game installation tests, driven by TOML recipes used by a sample installation engine, as well as a macro recorder in Python. The sample installation engine can be used as a base for your own integrations and automation code as well the macro recorder has been used in conjunction with the former. In this sample scripts every new capability of dosbox-automation is employed, as well as video recording the installation process, screen snapping to produce screenshots of it, a s well as runtime log of the executed calls. You can find these scripts in the folder tests/integration/ and the TOML recipes in tests/files/, as well the documentation for that in https://www.dosbox-automation.org/0.84-da1/au … ipes/index.html

I have made a playlist of demo'ing this feature, letting scripted installation sessions, as well as recorded macro sessions run, with enabled On Screen Display indicating the automated activity.
https://www.youtube.com/playlist?list=PLazWnU_un5ig

Playlist includes installation (with automated disk swaps) of Turbo Pascal 5.5 (lua scripted), System Shock (input replay, keyboard and mouse), Epic Pinball (lua scripted), DOOM shareware (lua scripted), The Incredible Machine demo (input replay, mostly mouse), Quest for Glory IV (input replay, mixed).

This whole package enables gamers, developers and game launchers to have a much more remote control over the DOSBOX, as in these features different and added to upstream:
- HTTP REST API (with swagger, enforced token authentication): https://www.dosbox-automation.org/0.84-da1/au … -api/index.html
- HTTP REST API: crisp video memory frame capture and information in PNG,JPG,RAW(+palette)
- HTTP REST API: video recording in ZMBV (start,stop,pause,status )
- HTTP REST API: drive swap (and mounting): intended for automatic disk image change for installation and other situations, where an automatic image swap is needed. CD iso swap is supported.
- HTTP REST API: keyboard (presses) + mouse events (movement, buttons) injection and recording (start,stop,pause,status),
- sandboxed lua script (loads, run, status via HTTP REST API call), most functions like REST API + wait for text on screen and other things, see https://www.dosbox-automation.org/0.84-da1/au … /lua/index.html

A notable change is also the introduction - due to the webserver - of a tight, white-list orientated mounting policy, that blocks and restricts remote access to the local file system via the dosbox emulator meaningfully. This prevents the scenario of shipping a trojanized dosbox.conf, as well as - as that is the reason for doing that - prevent remote mounting of any local directories via REST API or letting it remote keyboard type in these mount commands. For more details, please read

If you have any questions or feedback, I'd gladly answer your questions.

Note: This software (and parts of the documentation) has been developed with the aid of tooled assistance, but I've been reviewing, testing and signing off the code myself; but upstream also uses AI nowadays heavily.

Reply 1 of 2, by shakeyourbunny

Posted on 
User metadata
Rank Newbie
Rank
Newbie

A note to the mounting policy, if that is not well understood or curious and want to have a more in-depth explanation of it:

https://www.dosbox-automation.org/0.84-da1/au … rity/index.html

This web page also includes a comparison matrix, what is allowed, or not, or whitelisted, when the webserver module is running or not. TLDR is, if the webserver is not active, the rules for mounting a disk image are more relaxed, because you cannot exploit that remotely without it.

Reply 2 of 2, by shakeyourbunny

Posted on 
User metadata
Rank Newbie
Rank
Newbie

TLDR: dosbox-automation was updated to 0.85.0 and added (at least in this thread) a good chunk of new features and fixes.

Download: https://github.com/dosbox-automation/dosbox-a … mation/releases for Windows and Linux

dosbox-automation is a DOS integration runtime for game launchers, AI agents (including MCP), debugging, reverse engineering, development and integration into CI/CD, while staying a quality DOS emulator alternative for gamers. It is also intended for use in game trainers, as well as recording of properly rendered gameplay videos.

This is mainly a bugfix, code base refactoring, third-party libraries update and cleanup release.

First release under our own version number, as we have cut ties to upstream fully since release 0.84-da4. Although dosbox-automation has retained most features of the recently released of DOSBox Staging 0.83, the widening divergence warrants being an independent project.

Currently we sport 1167 unit tests covering a wide range of our C++ codebase, as well as 232 python based unit tests covering all aspects of our accessible end points as well as some full range tests (remote game installation, audio cd playback).

Homepage: https://www.dosbox-automation.org/

Vendored library changes and updates

[/b]augra-lib 0.1.0[/b]
Homepage: https://github.com/augra-project/augra-log
- Added, to replace Loguru and provide Python-style logging for C++. This is a new library written by a sister project of dosbox-automation.

httplib 0.52.0 to 0.53.1
Full changelog: https://github.com/yhirose/cpp-httplib/releases
- Stack overflow guard on regex routes, IPv6 host literal parsing fix - http://[::1]evil.com/ silently parsed as host ::1, payload_max_length enforced on decompressed size for unframed requests

enet 2.3.6 to 2.7.0
Full changelog: https://github.com/zpl-c/enet/releases
- IPv4-only support, missing channelID bounds check fix (2.6.3), peer count raised to 65k optional (2.5.0), enet_packet_resize fix (2.3.😎, CWE-476 null pointer fix from dosbox-staging's own PR (2.3.1).

simpleini 4.22 to 4.26
Full changelog: https://github.com/brofield/simpleini/releases
- Replaced ConvertUTF with inline SI_UTF8 conversion (removes a separately-licensed dependency), bug fixes with code review (4.24), cmake modernization.

r_flac 0.12.41 to 0.13.4, dr_mp3 0.6.37 to 0.7.4, dr_wav 0.13.11 to 0.14.6
Repository: https://github.com/mackron/dr_libs (no formal releases, tagged per library)
Seek deadlock fix (dr_flac), Xing/Info tag overflow (dr_mp3), malformed-file metadata parsing errors (dr_wav) , u8/s32 conversion fix (dr_wav)

New features, breaking changes and additions

Support for trainers, cheats etc
This feature (also known as memory searching, freezing, manipulation, as well as other related) has been already around in enhanced functionality since 0.84-da2, but was not really documented.

For more specific information about that, see https://www.dosbox-automation.org/0.85.0/auto … est-api/#memory as well consult the integrated HTTP REST API swagger, when the web server is enabled and an instance is running, via http://localhost:8386 .

Audio capture and mixer control over the API.
If you want to record only audio and not only video+audio via REST API, it is now possible to record the mixer output to a .WAV file. In addition, the master volume, the individual channels as well as muting is readable and controllable through Lua and REST API. See also https://www.dosbox-automation.org/0.85.0/auto … /#mixer-control

Structured logging system.
Introducing augra-log (https://github.com/augra-project/augra-log), basically a C++ port of the Python logger module, logging is now structured, with a timestamp, a log level and a component tag. Any new code and features will use this logging system.

The old logging system is still present and is routed through a compatibility shim into augra-log, but is deprecated and may be fully removed in one of the future releases.

Repository layout cleanup
The repository has been refactored and cleaned up, for details see the full release page.

General fixes
window decorations, GNOME dock icon
GNOME does not properly support standard desktop environment interoperability regarding title decorations, so dosbox-automation now includes a custom libdecor plugin, that also supports dark / light mode.

Using Appimages, you will also be asked now to install a desktop file in your system for displaying a proper dock icon, if you are using a GNOME-based desktop.

MODE symbolic names
The MODE BW40, BW80 and MONO commands now set the text modes properly to their respective video modes instead of faking it and aliasing it to the standard color modes.

Note that within the SVGA_S3 (Trio64 S3) machine, mode MONO (0x07) may lead to misbehaving DOS applications. This is not the emulators fault, but the application has not been written to tackle the situation, that a VGA card switches to a MDA mode. During testing, this behaviour could be replicated in other emulators like 86Box and on physical hardware.

build instructions for macOS
- Fixed and verified on Apple Silicon by an outside contributor (PR #5).
- No macOS binaries (reason: no access to build machines)

Downloads
Downloads are availabe at https://github.com/dosbox-automation/dosbox-a … mation/releases for Windows and Linux.

SHA256SUMS included in the release assets.

--
dosbox-automation has been written with the help of tooled assistance, but has been designed, reviewed and thoroughly tested and signed off by its developer.

Go to top of page Go to top of page
Back to PC Emulation
Close window
Close window