3LC Environment Variables

3LC supports the use of environment variables for controlling a variety of settings and configuration options. Relevant environment variables are described in the specific sections of the documentation where they apply, but they are also gathered here for convenient reference.

Environment variables must generally be set in the environment before running the 3lc command or calling import tlc from Python code to take effect.

In the tables below, environment variables with an asterisk (*) are part of the 3LC Configuration system, which generally means they control settings that may also be affected by other input mechanisms (e.g. config file, command-line arguments, etc.).

3LC Key Activation

3LC must be activated with either an API key or a license key, depending on which deployment is being used.

Environment Variable	Description
TLC_API_KEY*	Set the API key or provide the location of a file containing the API key to use to activate 3LC. See also the API Key page for details.
TLC_LICENSE*	Set the license key or provide the location of a file containing the license key to use to activate 3LC; used with the 3LC Enterprise On-Prem deployment. See also the License Key page for details.
TLC_OBJECT_SERVICE_AUTH_SECRET	The authentication secret used to secure communication between the Dashboard and Object Service when a license key is used. This secret should be a strong, random string known only to the Dashboard and Object Service. NOTE: This value is not required and is ignored when using an API key. See also the 3LC Enterprise On-Prem Secure Communication page for details.

3LC File Locations

By default, 3LC stores its various files at platform-specific locations on your system as described in Default File Locations. The following environment variables can be used to override the defaults.

Environment Variable	Description
TLC_DEFAULT_ROOT_DIR	Set the default root directory to ensure that all 3LC files are stored by default under a single root directory rather than across the various platform-specific locations. Note that the other environment variables listed may affect this behavior since they can be used to control the location of specific 3LC files.
TLC_CONFIG_FILE	Set an explicit location for the 3LC configuration file to use instead of the default.
TLC_LOG_FILE*	Set an explicit location for the 3LC log file to use instead of the default. (The legacy name TLC_LOGFILE is honored with a deprecation warning.)
TLC_LOG_LEVEL*	Set the log level to use for 3LC. (The legacy name TLC_LOGLEVEL is honored with a deprecation warning.)
TLC_PROJECT_ROOT_URL*	Set an explicit root location to use for 3LC projects instead of the default. (The legacy name TLC_CONFIG_PROJECT_ROOT_URL is honored with a deprecation warning.)
TLC_SCAN_URLS*	Provide a comma-separated list of URLs to scan for 3LC objects, in addition to those found at the project root location. Per-type scans (tables only, runs only) are expressed in the configuration file via scan-urls dict entries with object_type: table or object_type: run. (The legacy name TLC_CONFIG_PROJECT_SCAN_URLS is honored with a deprecation warning.)

3LC Aliases

3LC aliases are described in Sharing 3LC Tables and Runs, and the instructions for Setting Aliases include how to do so using environment variables.

Environment Variable	Description
TLC_ALIAS_...	Set an alias for a particular path, e.g. TLC_ALIAS_PROJECT_DATA="/data/project".

3LC Object Service Configuration

There are several environment variables that apply specifically to running the 3LC Object Service using the 3lc service command.

Environment Variable	Description
TLC_SERVICE_HOST*	Specify the host address to bind to for the Object Service server.
TLC_SERVICE_PORT*	Specify the port to bind to for the Object Service server.
TLC_SERVICE_DISABLE_EXTERNAL_MEDIA_URLS*	Disable cloud-direct media URLs and force the Dashboard to fetch every media sample through the Object Service’s proxy endpoint. Use this when the Object Service can reach cloud storage backends but the Dashboard’s browser cannot. Defaults to off.
NGROK_TOKEN	Specify the token to use with the NGrok reverse proxy integration when the --ngrok argument is provided to the 3lc service command. See here for details on using NGrok with the Object Service.

3LC Indexing Configuration

The indexer’s scan cadence and timestamp-debouncing behavior can be tuned via the following environment variables. The defaults are appropriate for most users; adjust only when investigating responsiveness or write-amplification issues.

Environment Variable	Description
TLC_INDEXING_SCAN_INTERVAL*	Interval (in seconds) between indexer scans for new or modified objects. Controls overall indexing responsiveness.
TLC_INDEXING_DEBOUNCE_INTERVAL*	Initial debounce interval (in seconds) before writing timestamp files. Part of a dynamic debounce system that adapts to write frequency.
TLC_INDEXING_DEBOUNCE_BACKOFF_THRESHOLD*	Number of writes within the debounce interval before exponential backoff is applied to timestamp writes.
TLC_INDEXING_DEBOUNCE_BACKOFF_MAX_LEVEL*	Upper limit of the exponential backoff for timestamp writes. Zero disables backoff.
TLC_INDEXING_DEBOUNCE_BACKOFF_MULTIPLIER*	Multiplier governing how aggressively the debounce interval grows when multiple writes occur within the current interval.

Miscellaneous 3LC Configuration

Environment Variable	Description
TLC_DISPLAY_PROGRESS*	Whether to display progress bars or not. The option can be either 0 or 1, where 0 means no progress bars and 1 means progress bars.

Cloud Storage Integrations

3LC has integrations to support reading and writing data on various cloud storage backends. Those integrations are affected by environment variables specific to the cloud storage backend (e.g. AWS_..., GOOGLE_..., AZURE_...). See URLs for details.