Configuration

dosbox-automation uses plain-text configuration files to control every aspect of the emulation. If you've ever edited an .ini file, the syntax will feel familiar.

The two main configuration types in dosbox-automation are the primary configuration and local configuration. They have the exact same format and you can configure the same things in both - they only different by their purpose and their location on the filesystem.

Primary configuration

The primary configuration holds global settings for dosbox-automation. It is always loaded if it exists; if it doesn't, it will be created when you start the emulator with the default settings.

The primary config file is stored in a platform-specific location:

On Linux, the primary config is looked up in other common XDG path locations as well.

Run dosbox-automation with the --printconf argument from the command line to see the exact path on your system. You can use --editconf to open the primary config in your default text editor.

Local configuration

dosbox-automation also supports local configurations, which are also referred to as per-game configuration. If DOSBox finds a config named dosbox.conf in its startup folder (working directory), it will load it after the primary configuration, thus potentially overriding global settings.

Local configs are typically used in setups where you create a subfolder for each game in your "DOS games" folder. Broad settings controlling general emulator behavior and settings applicable for applicable for each game should live in your primary config, then per-game overrides in the local configs.

This folder structure illustrates how a per-game setup would typically look like:

DOS Games
├── Azrael's Tear
│   └── dosbox.conf
│       ...
├── Dungeon Master
│   └── dosbox.conf
│       ...
├── Ultima Underworld
│   └── dosbox.conf
│       ...
...

The Tutorials guide walks through creating several per-game configs in detail.

If you start dosbox-automation from a different folder, you can still set the working directory via command line arguments, then the local dosbox.conf will be loaded from that directory.

Portable setup

If a dosbox-automation.conf file is placed in the same directory as the DOSBox Staging executable, DOSBox will use that directory as its configuration directory instead of the platform-specific location. This is useful for running DOSBox from a USB drive or keeping everything self-contained in a single folder - a setup commonly preferred by Windows users.

macOS document packages

On macOS, you can turn a game folder into a launchable document package by adding the .dosbox extension. The folder should contain a dosbox.conf file and optionally the drives/ subdirectory structure used by automounting:

My Game.dosbox/
  dosbox.conf
  drives/
    c/
      GAME.EXE
      ...

Double-clicking the .dosbox folder in Finder launches dosbox-automation with that folder as its working directory, loading the local dosbox.conf and automounting any drives inside it. This lets you treat each game as a self-contained app-like bundle.

Config layering

In addition to the primary and local configuration, you can specify additional config files to be loaded with the --conf command line argument. The possibilities don't end there; you can also set config values directly via --set <setting>=<value> arguments.

The various configuration mechanism are applied in this order (later values override earlier ones):

1. The primary config file is loaded first (unless the --noprimaryconf command line parameter is used).
2. A local dosbox.conf in the working directory is loaded next (unless --nolocalconf is used).
3. Additional config files specified via --conf are applied in the order given.
4. Individual --set <setting>=<value> overrides are applied last and take highest priority.

This layering system lets you keep your general preferences in the primary config and only override what's needed per game.

Refer to this section of the Tutorials guide for a more detailed description.

Syntax

Config files are divided into sections, each starting with a [section] header. Settings use key = value syntax. Lines starting with # are comments and are ignored.

[render]
# Use the 'sharp' shader instead of the default CRT emulation
shader = sharp

[cpu]
# Set 486DX2/66 speed
cpu_cycles = 25000

[autoexec]
c:
mixer opl 50
prince

The [autoexec] section is special; see Autoexec for details.

[cpu]
cpu_cycles = 25000  # Set 486DX2/66 speed

Autoexec

The [autoexec] section is the last section in the configuration file. Each line in this section is executed at startup as a DOS command.

Unlike other configuration sections, the [autoexec] section does not contain individual settings. Instead, it's a freeform block of DOS commands, one command per line, that are run sequentially when DOSBox starts up. This is similar to how the AUTOEXEC.BAT file works on a real DOS PC.

Here's an example configuration that launches a game executable PRINCE from the C: drive, then exits dosbox-automation after you quit the game (taken from the Getting started guide; you'll find more such config examples there):

[sdl]
fullscreen = on
pause_when_inactive = yes

[mixer]
reverb = large
chorus = normal

[autoexec]
c:
prince
exit

See the autoexec_section setting for how autoexec sections from multiple config files are handled.

Generating a default config

If you want to start fresh, delete your primary config file (use --printconf to find the file) or run --eraseconf. dosbox-automation will create a new primary config with default settings on next launch.

See Command-line usage for all available launch options.

Changing settings at runtime

Most configuration settings can be changed while DOSBox is running, directly from the DOS prompt. This is useful for experimenting with settings without restarting - you can try different shaders, adjust audio levels, or tweak CPU speed on the fly and hear or see the difference immediately.

There are two ways to change a setting:

• Full form: CONFIG -set section setting = value(e.g., CONFIG -set render shader = sharp)

• Shortcut form: setting = value, or simply setting value (e.g., shader = sharp, or just shader sharp)

The shortcut form works for most settings and is the quickest way to experiment. If a value is invalid, the error is displayed in the DOS console so you can see what went wrong.

To get help for any setting, use the /? shortcut:

sbtype /?
shader /?

This is equivalent to CONFIG -h setting but much quicker to type.

Some settings - such as machine --- require a reboot to take effect. After changing such a setting, use CONFIG -r to restart DOSBox. The setting's help text will tell you if a restart is needed.

Configuration best practices

• Local configurations are great for customising your settings per game. This is especially true if you're interested in playing games from different DOS eras that require very different hardware configurations.

• As dosbox-automation comes with sensible defaults, you can keep your local configs quite minimal. There’s absolutely no need to specify every single setting in your local game-specific configs. Fully-populated configs are very cumbersome to manage if you have a large game library. The Tutorials guide contains several such local config examples (Prince of Persia, Passport to Adventure, Beneath A Steel Sky, Star Wars: Dark Forces).

• A good, easy-to-manage approach is to only change settings in the primary config that affect the general workings of the emulator (e.g., fullscreen, pause_when_inactive, language, setting the master volume, etc.) Settings that set up specific hardware required by a game can then go into the local configs. If you reconfigure hardware in the primary config, there's always a risk that games configured for a certain hardware in their setup utility will stop working.