dosbox-automation developer reference

dosbox-automation is a DOSBox Staging 0.84 fork with a local HTTP REST API, a headless debugger, and an embedded Lua scripting engine bolted on for automated installs, deterministic testing, and programmatic control. This page is a developer-facing map of what's actually in the binary right now — every endpoint, every config setting, both bundled web UIs — not a pitch.

This particular repo is VorticonCmdr's fork of upstream dosbox-automation/dosbox-automation, adding the debugger REST/Lua area and both web UIs documented below; it's what this page describes. Upstream's own manual and downloads don't include any of it. For this fork's code, the repo.

Quick start

Four steps from a binary to a live API you can curl.

# 1. enable the API (off by default)
dosbox --set webserver_enabled=true

# 2. it prints the URL and writes a bearer token to the config dir
#    (a short preview goes to the log too)

# 3. every request needs the token, except the doc pages and /hello
curl -H "Authorization: Bearer <token>" http://localhost:8386/api/v1/status

# 4. or just open a browser: no token needed to *load* these
#    http://localhost:8386/            landing page
#    http://localhost:8386/api.html    live Swagger explorer
#    http://localhost:8386/control.html  operate everything below the debugger
#    http://localhost:8386/debugger.html full breakpoint/step/watch UI

Configuration

Project-specific settings on top of stock DOSBox Staging config. Every setting also carries a SetHelp() description in the generated config file.

[webserver]

Setting	Default	Description
webserver_enabled	false	Enable the HTTP REST API.
webserver_bind_address	127.0.0.1	IP to bind to. Binding to `0.0.0.0`/`::` also requires `webserver_allow_remote`.
webserver_port	8386	TCP port.
webserver_allow_remote	false	Allow binding to a non-localhost address, exposing the API to the network.
webserver_token_file	true	Write the full bearer token to a `0600` file in the config dir (removed on clean shutdown). Set `false` to rely on the `DOSBOX_API_TOKEN` environment variable instead.
webserver_token_scopes	unrestricted	Comma-separated scope list restricting what the token can do: `read`, `write`, `input`, `script`, `media`, `debug`, `control`. Also gates what a running Lua script may do.
webserver_osd	true	Show on-screen indicators while automation is driving the machine.
mount_allowed_bases	none	Semicolon-separated extra base directories `MOUNT`/`drive/mount` may expose to the guest. Symlink components rejected.
mount_allowed_image_roots	none	Semicolon-separated directories floppy/CD images may be mounted or swapped from.

[debug]

Setting	Default	Description
debugger_window	true	Show the interactive debugger window. Set `false` to keep the debugger fully usable over the REST API (breakpoints, stepping, memory/register access, the web debugger) without ever opening a window — the same headless fallback used when no GPU device is available.

Features

Everything reachable through the API, grouped by area. Each area's exact routes are in the table below.

Status & control

Emulator/program state, graceful shutdown, a pre-auth handshake.

Input

Inject keyboard/mouse event sequences or literal text; read/set the mouse cursor; cancel a running replay.

Recording & replay

Deterministic, frame-accurate keyboard/mouse recording and replay; list, save, delete recordings.

Video & capture

Grab the current frame, scrape the text-mode screen, record ZMBV video with adjustable compression.

Drives & mounting

List drives, swap floppy/CD images, mount a host directory, browse mountable directories/images, lock the mount config.

Memory

Allocate/free, search or pattern-scan a range, snapshot-and-diff to hunt a moving value, freeze addresses, raw read/write.

CPU

Read all registers/flags, write a single register.

DOS internals

Walk the MCB chain, inspect live EMS/XMS driver state (handles, page mappings, A20/HMA/UMB).

Port I/O

Read/write an x86 I/O port.

Headless debugger

Pause/continue/step/step-over/step-out/run-to, execute/interrupt/memory breakpoints, watched variables, disassembly, call-stack backtraces — all over the API, with or without the interactive window.

Lua scripting

Sandboxed scripts run inside the emulator with a dosbox.* API, gated by the same token scopes as the REST API.

Batch execution

Bundle multiple memory/register/port/freeze operations into one atomic emulation-thread pass.

REST API

All 78 operations across 68 routes, extracted straight from resources/webserver/openapi.json and the route table in src/webserver/webserver.cpp — this list can't drift from the binary. The full interactive spec is at /api.html once the server is running.

Method	Path	Area	Summary	Scope

Web UIs

Two hand-built pages ship alongside the generic Swagger explorer at /api.html. Neither needs a token to load — like the landing page, they're static shells; every API call they make still needs one, pasted into the page itself.

/control.html

A routine-operations dashboard: drives & mounting (with a directory browser), input/mouse, recording & replay, live screen preview and video capture, memory freezes and raw reads, CPU registers, port I/O, DOS/EMS/XMS internals, Lua script control, and a raw-JSON escape hatch for batch/wait_for.

/debugger.html

Full interactive debugging: live disassembly with EIP highlighting, execute/interrupt/memory breakpoints (read or write triggers), watched variables, call-stack backtrace, and a memory hex-dump — a browser-based alternative to the native ImGui debugger window.

Lua scripting

POST /api/v1/script/load runs sandboxed Lua inside the emulator with a dosbox.* API mirroring the REST surface (keyboard/mouse input, memory read/write, screen text/matching, on-screen messages, capture control) — useful for install automation and in-emulator test logic that shouldn't need a network round-trip per step. Scripts are gated by the same webserver_token_scopes as the REST API. See src/lua/lua_api.cpp and src/lua/lua_bridge_commands.cpp for the full function list, and docs/CONTRIBUTING.md for the sandbox's limits (instruction count, wall clock, memory cap).