Install on Linux

Validated on WSL2 only. Linux is a supported target, but every test so far ran Dungeondraft 1.2.0.1 and this companion on Ubuntu 24.04 under WSL2 on Windows. Native Linux desktops and other distributions have not been tested.

Install the purchased Linux version of Dungeondraft, along with your AI client, in the same Linux environment. For WSL, use Ubuntu’s Linux filesystem and run the client inside Ubuntu too; do not reuse the Windows companion or its registration. The earlier setup used the Linux editor, not the Windows editor through Wine.

1. Open Releases and download battlemap-mcp-mod-<version>.zip and battlemap-mcp-companion-<version>-linux-x64.tar.gz from the same release’s Assets. This package is for Intel/AMD 64-bit Linux; there is no Linux ARM package. Skip the Source code archives. If no Linux asset is listed, that release does not yet have a downloadable Linux companion.

2. Extract the archive with your file manager. Move the whole extracted battlemap-mcp folder into a permanent folder you own, such as Apps in your home folder. Keep _internal and all other files together.

3. Open a terminal in the extracted battlemap-mcp folder and run:

   ./battlemap-mcp --version

   It should print the package version. No Python, uv, Git, sudo, or PATH change is needed.

1. Extract the mod ZIP. Move its battlemap-mcp-bridge folder into a writable mods folder in your Linux home directory, such as Dungeondraft Mods. Keep an existing writable mods folder if you already use one.
2. In the Linux Dungeondraft app, choose Mods → Browse and select the folder containing battlemap-mcp-bridge. The default /opt/Dungeondraft/mods location may require administrator access; use your own folder instead.
3. Tick Battlemap MCP Bridge and click Accept. Then fully quit and reopen Dungeondraft: it reads mods only when it starts. Create or open a map and wait for loading to finish. Do not run Dungeondraft or the companion as root.

With your chosen client installed, run one of these commands:

./battlemap-mcp setup --client codex

./battlemap-mcp setup --client claude-code

./battlemap-mcp setup --client opencode

For OpenCode 1, setup prints the entry to paste instead of registering (see OpenCode). Read the displayed plan and confirm it. Setup installs the bundled skills and registers this companion’s permanent path. Restart your client afterward. You may run both commands if you use both clients. See client help if automatic registration is unavailable.

With Battlemap MCP Bridge enabled and a map open in the Linux editor, run:

./battlemap-mcp doctor --live --brief

Expect Ready: connected to Battlemap MCP Bridge. Restart your AI client and ask it to check the connection and report the open map’s dimensions without changing it. If the checker cannot connect, confirm the editor and companion are in the same Linux environment, the correct mods folder is selected, and a map has finished loading. The bridge’s private state defaults to ~/.local/state/battlemap-mcp; do not point the Linux client at Windows token files.