Webserver

dosbox-automation includes a built-in HTTP webserver that serves the REST API and hosts static files from your configuration directory. It is off by default.

Enabling the webserver

Set webserver_enabled to on in your configuration file and restart dosbox-automation:

[webserver]
webserver_enabled = on

The webserver generates a random 64-character hex token at startup. There are three ways to receive it:

  1. Environment variable -- set DOSBOX_API_TOKEN before starting to use a specific token instead of a random one. Useful for CI/CD pipelines and launcher integration. The log confirms the env var was used but does not print the token.
  2. Token file -- enable webserver_token_file to write the token to a file in the config directory. The log shows the file path, not the token. The file is created at startup and removed on shutdown.
  3. Log output (fallback) -- if neither of the above is configured, the log shows only the first 8 characters of the token. The full token is never printed to the log.

You need this token for all API requests. See the REST API page for how to use it.

API explorer (Swagger UI)

The webserver ships its own live API documentation. With the webserver running, open

http://localhost:8386/api.html

in a browser to get a bundled, offline Swagger UI explorer: every endpoint with its parameters and response schemas, straight from the server's own OpenAPI specification (/openapi.json). The documentation pages are readable without a token, so you can browse the API surface freely; executing a request from the explorer still requires the bearer token (use the Authorize button). Everything is served locally, nothing is fetched from the internet.

This is the quickest way to poke at the API: browse an endpoint, fill in the parameters, hit execute, and see the live response from the running emulator.

Built-in tools

Open http://localhost:8386/ in a browser while dosbox-automation is running to see the built-in API documentation and tools. These are served from the webserver directory inside your configuration folder.

The extras/api/ directory in the dosbox-automation source tree contains ready-to-use HTML tools and a JavaScript API wrapper:

  • Memory Monitor -- watch and edit memory locations live
  • Memory Scanner -- find where specific values are stored (like Cheat Engine for DOS)
  • Memory Viewer -- hex viewer with built-in x86 disassembler
  • JavaScript API wrapper (api.js) -- a class for building custom tools on top of the API, with TypeScript definitions in api.d.ts

Copy these files into the webserver directory to use them.

Configuration settings

The webserver settings are configured in the [webserver] section.

webserver_enabled

Enable the HTTP REST API that exposes internal state and memory. Open http://localhost:8386 in a browser (or use the configured port) to view the API documentation.

Possible values: on, off (default)

webserver_bind_address

Bind to the given IP address (127.0.0.1 by default). This API gives full control over DOSBox; do not expose this to untrusted hosts. By default only local connections are allowed.

webserver_port

TCP port to bind to (8386 by default). Valid range: 1-65535.

webserver_allow_remote

Must be set to on to bind to a non-localhost address. If webserver_bind_address is set to anything other than 127.0.0.1 or ::1, the webserver refuses to start unless this flag is explicitly enabled. This is a safety gate against accidental network exposure.

Possible values: on, off (default)

webserver_token_file

Write the API token to a file in the config directory instead of logging it. The file is created at startup and removed on shutdown. Launchers can read the file to obtain the token without parsing log output.

Possible values: on, off (default)

webserver_osd

Show on-screen indicators while automation is driving the machine (script running, recording, replay, injected input). Enabled by default so it is always clear when the machine is under remote control. Set to false to hide the overlay.

The overlay renders on both the OpenGL backend and output=texture, so it is visible regardless of the output setting. Batch files can show their own overlay text with the bundled osd command while the web server runs.

Possible values: on (default), off

mount_allowed_bases

Semicolon-separated list of host directories that directory mounts are allowed from. When the webserver is enabled, the MOUNT command can only create directory mounts inside the config file's parent directory or the paths listed here. Supports $HOME, %USERPROFILE%, and $XDG_DATA_HOME. Maximum 3 entries.

This setting is read from the primary config file only. A bundled --conf file cannot override it.

mount_allowed_bases = $HOME/Games;$HOME/dos
mount_allowed_image_roots

Semicolon-separated list of host directories that the drive-swap API can load disk images from. When configured, the /api/v1/drive/swap endpoint only accepts images under these paths. Same environment variable support and 3-entry limit as mount_allowed_bases.

This setting is read from the primary config file only.

mount_allowed_image_roots = $HOME/Images;/mnt/cdrom