Foundry Virtual Tabletop has two primary ways to set configuration options, command line flags and directives in options.json. In most cases, options set via command line flag will override the corresponding directives in options.json, however, the number of flags available is comparatively limited.

## Command Line Flags

Foundry has four command-line flags that can be passed when the application is run at the command line. These work with both the packaged Electron executable as well when starting Foundry via Node.js.

--port
This specifies the port Foundry will listen on for incoming connections. If not specified, Foundry will use the port defined in options.json, or 30000.
--world
This allows for a specific world to be opened immediately as Foundry launches. Note that this option will not work if some setup steps are not completed, such as EULA acceptance.
--dataPath
This lets you specify the user data directory that Foundry will load up to source systems, modules, and world data.
--noupnp
This disables universal plug and play. If this flag is set, port forwarding will need to be set up, or the server Foundry is running on will need to have a public IP in order for Foundry to be externally accessible by your players.

Example usage of the command line syntax to launch the application for various environments are:

#### Node.js

node main.js --port=30000 --world=myworld --dataPath=/local/data/foundryvtt

#### Electron (Windows)

FoundryVTT.exe --port=30000 --world=myworld --dataPath=D:\FoundryVTT

#### Electron (Linux)

foundryvtt --port=30000 --world=myworld --dataPath=/local/data/foundryvtt

## Configuration Options

Foundry's behavior can also be customized via editing the options.json file stored in the Config directory located in the user data directory. The directives take one of three data types:

String
Alphanumeric characters enclosed in double-quotes. Example: "examplestring"
Integer
Numbers without decimal points or other punctuation. Example: 12345
Boolean
The values true or false, all lower-case, without punctuation. true enables a given option, false disables it.

All options can also be set to null, which disables that option. Do not set a value to null unless you're certain it can be disabled.

Note: JSON is syntax-sensitive, and a malformed options.json file may cause Foundry to not start. It is strongly advised that you back up options.json before editing it manually.

port
Integer -- defines the default port used by the application unless one is explicitly provided using the     --port flag.
fullscreen
Boolean -- determines whether to run the Electron application in fullscreen mode.
dataPath
String -- you may specify an explicit path to the user data directory which should be used as the source for packages and other content. This option is only used of the command line flag with the same name is not also passed.
hostname
String -- a custom hostname to use in place of the host machine's public IP address when displaying the address of the game session. This allows for reverse proxies or DNS servers to modify the public address.
routePrefix
String -- a path which is appended to the base hostname to serve Foundry VTT content from a specific namespace. For example setting this to demo will result in data being served from http://x.x.x.x:30000/demo/.
sslKey
String -- an absolute or relative path that points towards a SSL key file which is used jointly with the sslCert option to enable SSL and https connections. If both options are provided, the server will start using HTTPS automatically.
sslCert
String -- an absolute or relative path that points towards a SSL certificate file which is used jointly with the sslKey option to enable SSL and https connections. If both options are provided, the server will start using HTTPS automatically.
awsConfig
String -- an absolute or relative path which points to an optional AWS configuration file in JSON format containing accessKeyId, secretAccessKey, and region properties. This file is used to configure integrated AWS connectivity for S3 assets and backup.
upnp
Boolean -- allow Universal Plug and Play to automatically request port forwarding for the Foundry VTT port to your local network address. Default is true.
proxySSL
Boolean -- indicates whether the software is running behind a reverse proxy that uses SSL. This allows invitation links and A/V functionality to work as if the Foundry Server had SSL configured directly.
proxyPort
Boolean -- informs Foundry that the software is running behind a reverse proxy on some other port. This allows the invitation links created to the game to include the correct external port.

## Where Is My Data Stored?

In order to comply with operating system expectations (most notably on Windows and MacOS), it is important not to store actively updated user data inside the application directory itself. Therefore Foundry Virtual Tabletop relies upon the concept of a user data path which defines the location that user data is saved. There are four ways that the user data location can be set.

1. Command Line Flag. See the Command Line Options above.
2. Environment Variable. Set FOUNDRY_VTT_DATA_PATH.
3. Config Data Override. See the Application Configuration Options section above.
4. Default OS Application Data. See below for details.

These options are evaluated in the above order, so if multiple options are set, the first valid option will be used. The default application data location for each operating system is the following:

Windows

%localappdata%/FoundryVTT

Note that when configuring a custom path in Windows you need to either use forward slashes, for example D:/path/to/appdata or escaped backwards slashes, D:\\path\\to\\appdata.

MacOS

~/Library/Application Support/FoundryVTT

Linux (in order of availability)

/home/$USER/.local/share/FoundryVTT /home/$USER/FoundryVTT
/local/FoundryVTT


These default locations may not be ideal for many users, so it is recommended to use one of the above alternative methods to point Foundry VTT to a different data location as suits your preferences. The user data folder contains the following basic directory and file structure.

• Config/ - The configuration directory
• options.json - Application configuration options
• Data/ - User data directory
• systems/ - Installed game systems
• modules/ - Installed add-on modules
• worlds/ - Installed game worlds
• Logs/ - Server log files

When referencing data from within the virtual tabletop application, any content stored inside the Data directory is publicly available to be served directly. This is where you should put your content that you intend to use inside the application. You are free to create any folder or directory structure that you want inside this data directory. For example, if you have the following file in your file system

<User Data Path>/Data/worlds/my-world/maps/dungeons/deadly-dungeon-01.jpg

When using that map image inside Foundry VTT, you can reference it as a web-accessible URL using the path relative to the Data folder

worlds/my-world/maps/dungeons/deadly-dungeon-01.jpg

#### Regarding File Naming Conventions

Since Foundry VTT works as a web server, you should be sure to use directory and file names which conform to web file and URL encoding conventions. You should generally avoid using spaces or special characters as these are likely to cause issues when serving your content to other players. See  the Google URL Guidelines for more detail.