Skip to content

🔥🔥🔥 You are viewing a development version of the website. Things will blow up. 🔥🔥🔥

Regular users, please follow the exit signs.

# HTTP API

DOSBox Staging can expose an HTTP REST API that gives external tools access to the internal state of the emulated machine. Use cases include displaying game information in external overlays, game modding, memory inspection, bug investigation, function hooking, and building cheat tools.

All endpoints access the internal state atomically between steps of the emulated CPU. They are never executed during natively implemented DOS functions or interrupts, so the internal data structures are guaranteed to be consistent in any given snapshot.

The API only binds to `localhost` by default — never expose it to untrusted networks, as it gives full control over the emulator.

Warning

This feature is intended for developers and advanced users. Do not enable it unless you know what you’re doing.

Note

The HTTP API has been primarily tested with `core = normal`. Your experience with other CPU cores may vary.

## Enabling the API

Set `webserver_enabled` to `on` in your config and restart DOSBox:

    [webserver]
    webserver_enabled = on

Then open `http://localhost:8080/` in a browser while DOSBox is running to see the built-in API documentation.

## API endpoints

### CPU registers

`GET /api/cpu`

  Returns all x86 CPU registers: `eax`, `ebx`, `ecx`, `edx`, `esi`, `edi`, `esp`, `ebp`, `eip`, `flags`, `cs`, `ds`, `es`, `ss`, `fs`, `gs`.

### Reading memory

`GET /api/memory/:offset/:len`
`GET /api/memory/:segment/:offset/:len`

  Read memory at the given address. The optional segment parameter can be the name of a segment register (`CS`, `SS`, `DS`, `ES`, `FS`, `GS`) or a numeric value. All URL parameters accept hex values with the `0x` prefix.

  By default, the raw binary data is returned. Set `Accept: application/json` to receive a JSON response with the data encoded in Base64.

  Maximum read size is 128 MiB per request.

  Example — download the entire conventional memory area:

      GET /api/memory/0/0x100000

### Writing memory

`PUT /api/memory/:offset`
`PUT /api/memory/:segment/:offset`

  Write memory to the given address. Path parameters work the same as for reading.

  Accepts raw binary data with `Content-Type: application/octet-stream`, or a JSON object with a Base64-encoded `data` field with `Content-Type: application/json`.

  Supports atomic compare-and-swap: set the `If-Match` header to Base64-encoded expected data. Returns HTTP 412 (Precondition Failed) if the current memory contents don’t match.

### Memory allocation

`POST /api/memory/allocate`

  Allocate memory from the emulated machine.

  Request body:

      {
          "size": 1024,
          "area": "conv",
          "strategy": "best_fit"
      }

  - `area` — `conv` (conventional), `UMA` (upper memory), or `XMS`.
  - `strategy` — `best_fit` (default), `first_fit`, or `last_fit`. The XMS allocator only supports `best_fit`.

  Response:

      {
          "addr": 655360
      }

  Returns HTTP 503 if allocation fails.

`POST /api/memory/free`

  Free previously allocated memory.

  Request body:

      {
          "addr": 655360
      }

  Returns HTTP 400 on invalid addresses.

### DOS information

`GET /api/dos`

  Returns pointers to internal DOS data structures:

  - `listOfLists` — pointer to the DOS list of lists (INT 21h AH=52h)
  - `dosSwappableArea` — DOS swappable area pointer (INT 21h AX=5D06h)
  - `firstShell` — pointer to the first shell’s PSP (start of usable memory)

### System information

`GET /api/info`

  Returns DOSBox Staging version and relevant filesystem paths.

## Example tools

The `extras/api/` directory in the DOSBox Staging source tree contains ready-to-use HTML tools and a JavaScript API wrapper. To use them, copy the files to the `webserver` directory inside your DOSBox configuration folder.

### Memory Monitor

Monitor and manipulate memory locations live. As an example, run the Commander Keen Episode 4 Demo with the default configuration and import the following config string into the Memory Monitor:

    W3siYWRkciI6IjB4YzhlZmUiLCJ0eXBlIjoiY3N0cmluZyIsImxhYmVsIjoiRmlsZSJ9LHsiYWRkciI6IjB4MzgyZjgiLCJ0eXBlIjoidWludDgiLCJsYWJlbCI6IkFtbW8ifSx7ImFkZHIiOiIweDAzODMwYSIsInR5cGUiOiJ1aW50OCIsImxhYmVsIjoiTGl2ZXMifV0==

You will now see the current values for lives and ammo — and yes, you can edit them.

### Memory Scanner

A lightweight version of tools like Cheat Engine. It identifies where specific values are stored in memory by iteratively tracking changes:

1. Search for a known value (e.g., your current ammo count).
2. Perform an action in-game that changes that value.
3. Filter the results. Repeat until you’ve isolated the memory address.

### Memory Viewer

A memory viewer with a built-in x86 disassembler.

### JavaScript API wrapper

The `api.js` file provides a JavaScript class for building custom tools on top of the API. It handles Base64 encoding/decoding, segment register resolution, and compare-and-swap operations. TypeScript type definitions are available in `api.d.ts`.

## Configuration settings

You can set the web server parameters in the `[webserver]` configuration section.

##### webserver_bind_address

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

##### webserver_enabled

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

  Possible values: `on`, `off` default

##### webserver_port

  TCP port to bind to (`8080` by default).