Skip to main content

Stream Deck for Foundry VTT

Set up Stream Deck with Foundry VTT

Connect the Stream Deck plugin, local companion and JDR Ninja module, then choose your Foundry session and test a first command.

What you need

Prepare Foundry V14 or later, the enabled JDR Ninja module, the Stream Deck application, its JDR Ninja plugin and Node.js 24. The server may be remote, but open the Foundry browser on the computer running Stream Deck and the companion.

Install the Foundry module

Install the plugin and companion

Public distribution is being prepared. If you have a development build, install its .streamDeckPlugin file in the Stream Deck application. For the companion, open a terminal in the source stream-deck directory and install dependencies with the following command.

npm ci

If you received the companion .tgz runtime archive, extract it, open a terminal in its directory and use this command instead. Install Node.js 24 separately.

npm install --omit=dev --ignore-scripts

The companion runs in the terminal. It includes no autostart, tray application or Node.js installer. Keep this window open while playing.

Prepare the local connection

Run initialization. Enter the exact Foundry browser origin, such as http://localhost:30000 or https://foundry.example.net, with no path or trailing slash. Copy the generated pairing key and keep it for both clients. Then start the companion.

npm run companion:init
npm run companion

Configuration stays in your private profile at the paths below. Initialization will not overwrite an existing file. To change the origin, port or key, stop the companion, edit the file and restart it. Update both clients if the key changes.

  • Windows : %LOCALAPPDATA%\JDR Ninja\companion.json
  • macOS / Linux : ~/.config/jdr-ninja/companion.json

Connect Foundry to the companion

In the JDR Ninja module's Stream Deck settings in Foundry, enter the address below and the pairing key. Save, then explicitly enable integration in this browser. Check that the companion connection is established.

ws://127.0.0.1:19114/jdr-ninja

Connect the Stream Deck plugin

Add Foundry Control to a key. In its inspector, enter the address below in Companion address, paste the same Pairing key and choose Connect. Connection settings are shared across keys. The key field clears after saving.

ws://127.0.0.1:19114/stream-deck

This key pairs clients with the local companion. It differs from the Atlas connection token and your JDR Ninja account credentials. Do not paste those other credentials into the pairing field.

Choose the Foundry session

In Foundry world and browser, choose the intended world, user and browser. Wait for Ready and the available commands and documents. Each key stores its own session, command and parameters. It never automatically switches worlds, users or browsers.

Create and test your first key

In Command, choose Open actor and select an actor whose sheet you can open. Press the key once. Check that the sheet opens in Foundry and the inspector reports Completed. An admitted command may still be waiting for execution.

An uncertain outcome may briefly display ? on the key. Check what happened in Foundry before pressing again. Then add scene, music or combat controls as needed and permitted.

After reconnecting

Each new Foundry connection gets a new session identity. Select it again on every affected key, including after restarting the companion. Reconnecting only the plugin can rediscover a still-connected Foundry session. Ctrl+C stops the companion and closes its connections.

Advanced options

Start with fixed values. For a personal counter, create a writable Number variable in Foundry. In the inspector, choose Increase variable, that variable and a fixed adjustment of 1. Check the result in Foundry. Computed variables can supply values but cannot be changed by this command.

Lists and macro arguments are optional. Choose compatible variables and a macro that declares its arguments in Foundry. Every press checks the session, values and permissions. A combined command may save variables before an action fails: check both outcomes before trying again.

The JDR Ninja module for Foundry

Troubleshooting

  • No connection: check that the companion is running, addresses use 127.0.0.1 with the correct paths, and both clients have the same key.
  • Foundry refused or missing: check the exact allowed origin in companion.json and Stream Deck enablement in that browser. A different server address changes the origin.
  • HTTPS Foundry: the browser may require wss and a trusted local certificate. Configure tlsCert and tlsKey with absolute PEM file paths, then use wss in both clients. The certificate must cover the local address and be trusted by both browsers. The companion does not install it.
  • Missing or synchronizing session: wait until it is ready, then reselect the world, user and browser on the key.
  • Refused command or missing document: check the Foundry account's permissions and target document. Selecting a session grants no additional rights.
  • Overlay test unavailable: check JDR Ninja account connection, overlay enablement in Foundry and Premium verification. The local key does not confirm this access.
  • Uncertain or partial result: inspect the affected sheet, scene, variables or combat in Foundry before pressing again. An interruption can occur after execution. The plugin does not automatically retry the command.

Frequently asked questions

Why does the key disappear from the field?

The plugin clears the field after saving so the stored key is not displayed. This does not mean the connection was removed.

Why must I select the session again?

A Foundry reconnection creates a new identity. Keys keep their previous choice to avoid sending commands to another world, user or browser.

Can I repeat a command with an uncertain result?

Check Foundry first. The command may already have executed despite the connection interruption. Every new press is a new command.

Stream Deck for Foundry VTT The JDR Ninja module for Foundry