Configuring Foundry VTT with options.json

Overview

Foundry VTT stores its runtime configuration in options.json, located at:

<dataPath>/Config/options.json

For a typical installation with --dataPath=/foundry-data, this file is at:

/foundry-data/Config/options.json

Most settings can be changed through the Setup menu in the browser, which writes to this file automatically. However, understanding the raw file is essential for headless servers, container environments, and troubleshooting.

Editing options.json

Always stop the Foundry server before manually editing options.json. Foundry reads this file at startup; changes made while the server is running will be overwritten when Foundry next writes the file.

# Stop the server first, then edit
nano /foundry-data/Config/options.json

Key Configuration Fields

port

"port": 30000

The TCP port Foundry listens on. Default is 30000. Change this if you need to run multiple instances or if your panel assigns a different port. See Port Configuration and Firewall Setup.

dataPath

"dataPath": "/foundry-data"

Full path to the data directory. This can also be passed as a command-line argument (--dataPath=...), which takes precedence over the file value.

hostname

"hostname": ""

Binding hostname. Leave empty to listen on all interfaces. Set to a specific IP if you need to restrict which interface Foundry binds to.

proxyPort and proxySSL

"proxyPort": 443,
"proxySSL": true

These two settings are required when Foundry is running behind a reverse proxy (such as nginx). proxyPort tells Foundry what external port clients are connecting on. proxySSL tells Foundry that the proxy is handling HTTPS, so Foundry should generate https:// links internally. Without these settings, invitation links and asset URLs will be incorrect.

See Setting Up SSL/HTTPS with nginx for full reverse proxy configuration.

upnp

"upnp": false

Set to true to attempt automatic UPnP port forwarding on your router. Only useful in home lab environments — disable in datacenter or panel-hosted setups where UPnP is not available.

updateChannel

"updateChannel": "stable"

Controls which update track Foundry checks. Use "stable" for production. "testing" provides access to release candidates.

sslCert and sslKey

"sslCert": "/path/to/cert.pem",
"sslKey": "/path/to/key.pem"

Paths to SSL certificate and private key if you want Foundry to handle HTTPS directly (without a reverse proxy). For most setups, using nginx with proxySSL: true is preferred over configuring Foundry's built-in SSL.

adminPassword

"adminPassword": "<hashed value>"

The admin password stored as a hash. Do not set this manually — use the Setup menu. To reset a forgotten password, stop the server and delete Config/admin.txt. See Setting Up and Resetting the Admin Password.

Complete Example

A typical production configuration behind an nginx reverse proxy:

{
  "port": 30000,
  "dataPath": "/foundry-data",
  "hostname": "",
  "proxySSL": true,
  "proxyPort": 443,
  "upnp": false,
  "updateChannel": "stable"
}

A container-based setup using Pterodactyl with a non-default port:

{
  "port": 32145,
  "dataPath": "/home/container/data",
  "proxySSL": false,
  "upnp": false,
  "updateChannel": "stable"
}

Command-Line Overrides

Several options can be passed directly on the command line and will override options.json values:

node main.mjs --dataPath=/foundry-data --port=30000

In Pterodactyl/WISP environments, the startup command typically passes --dataPath and --port via egg variables, so you may not need to edit options.json directly for those values.

Related

• Installing Foundry VTT on Your Server
• Port Configuration and Firewall Setup
• Setting Up SSL/HTTPS with nginx
• Setting Up and Resetting the Admin Password