Configuration Options Reference¶
Every 3LC configuration option, grouped by category. Each option lists every surface through which it can be
set or read: the YAML config-file key, the environment variable, the CLI argument (where applicable), and the
Python attribute on Configuration.
Internal options (those flagged cli_visible=False and serializable=False) are omitted — they are
framework-internal flags set automatically at process startup.
Top-level options¶
Top-level options accessible directly on Configuration.
config.aliases¶
URL alias definitions for path shortcuts.
Dictionary mapping alias names to target paths/URLs. Aliases are used with angle brackets in URLs: <ALIAS_NAME>/path/to/file.
Example: aliases: DATASETS: /data/datasets MODELS: s3://bucket/models
Config key:
aliasesEnvironment variable:
TLC_ALIAS_([A-Z][A-Z0-9_]*)Python attribute:
config.aliasesDefault:
{}
config.api_key¶
API key for cloud/SaaS authentication.
Config key:
api-keyEnvironment variable:
TLC_API_KEYCLI argument:
--api-keyPython attribute:
config.api_keyDefault:
''Serialized to config file: no (credentials / runtime-only state)
config.display_progress¶
Whether to display progress bars.
Config key:
display-progressEnvironment variable:
TLC_DISPLAY_PROGRESSCLI argument:
--display-progressPython attribute:
config.display_progressDefault:
True
config.license¶
Specify license or license file.
The option can either be the license key or point to a local file containing the license key. Required for on-prem deployments.
Config key:
licenseEnvironment variable:
TLC_LICENSECLI argument:
--licensePython attribute:
config.licenseDefault:
''Serialized to config file: no (credentials / runtime-only state)
config.project_root_url¶
Location for reading and writing 3LC project data.
This option is mandatory and must point to a location with write access. Supports local paths and remote URLs (s3://, gs://, az://). Environment variables and ~ are expanded. The location will be created if needed.
Config key:
project-root-urlEnvironment variable:
TLC_PROJECT_ROOT_URLLegacy aliases (honored with a deprecation warning):
TLC_CONFIG_PROJECT_ROOT_URL
CLI argument:
--project-root-urlPython attribute:
config.project_root_urlDefault: computed at runtime
Required: yes
config.scan_urls¶
Locations to scan for 3LC objects.
Each entry can be a plain URL string (defaults to layout: project) or a dict with explicit attributes:
scan-urls: # Plain string — scanned as a project tree - s3://bucket/projects - /local/projects
# Dict with explicit layout
- url: /local/loose-objects
layout: flat
# Full control
- url: /data/tables-only
layout: flat
object_type: table
Supported layout values: “project” (recursive project scan), “flat” (single directory). Supported object_type values: “table”, “run” (omit to scan for all types).
The TLC_SCAN_URLS environment variable accepts a comma-separated list of URL strings.
Live propagation. Mutations to scan-urls (via Configuration.append /
Configuration.remove / file reload / env reload) write through to
ConfigStore under its RLock. IndexingTable instances constructed
with share_configuration=True (the default for the three subclass
instance() factories) run reconcile_with_configuration() at the top
of every scan cycle; when nothing has changed the reconcile is a cheap pair
of dict comprehensions with two no-op diff loops. Callers wanting
synchronous propagation can call indexer.reconcile_with_configuration()
directly. Mutations are safe from any thread under ConfigStore’s
RLock.
Config key:
scan-urlsEnvironment variable:
TLC_SCAN_URLSLegacy aliases (honored with a deprecation warning):
TLC_CONFIG_PROJECT_SCAN_URLS
Python attribute:
config.scan_urlsDefault:
[]
Logging (config.logging.*)¶
Options governing the 3LC logger.
config.logging.file¶
Log file path for the 3LC logger.
The directory will be created if it does not exist. Environment variables and ~ are expanded. Must be a local filesystem path (remote URLs not allowed).
Config key:
logging.fileEnvironment variable:
TLC_LOG_FILELegacy aliases (honored with a deprecation warning):
TLC_LOGFILE
CLI argument:
--log-filePython attribute:
config.logging.fileDefault: computed at runtime
config.logging.level¶
Log level for the 3LC logger.
Standard Python logging levels:
DEBUG: Detailed diagnostic information
INFO: Confirmation that things are working
WARNING: Unexpected events (default)
ERROR: Serious problems
CRITICAL: Program may not continue
Config key:
logging.levelEnvironment variable:
TLC_LOG_LEVELLegacy aliases (honored with a deprecation warning):
TLC_LOGLEVEL
CLI argument:
--log-levelPython attribute:
config.logging.levelDefault:
'WARNING'Choices:
'DEBUG','INFO','WARNING','ERROR','CRITICAL'
Indexing (config.indexing.*)¶
Options governing the indexer scan cadence and timestamp debouncing.
config.indexing.debounce_backoff_max_level¶
Maximum backoff level for timestamp debouncing.
Controls the upper limit of the exponential backoff for timestamp writes. Zero means no backoff for debouncing.
Config key:
indexing.debounce-backoff-max-levelEnvironment variable:
TLC_INDEXING_DEBOUNCE_BACKOFF_MAX_LEVELLegacy aliases (honored with a deprecation warning):
TLC_INDEXING_TIMESTAMP_DEBOUNCE_BACKOFF_MAX_LEVEL
Python attribute:
config.indexing.debounce_backoff_max_levelDefault:
0
config.indexing.debounce_backoff_multiplier¶
Multiplier for timestamp debounce backoff.
Controls how aggressively the debounce interval increases when multiple writes occur within the current interval.
Config key:
indexing.debounce-backoff-multiplierEnvironment variable:
TLC_INDEXING_DEBOUNCE_BACKOFF_MULTIPLIERLegacy aliases (honored with a deprecation warning):
TLC_INDEXING_TIMESTAMP_DEBOUNCE_BACKOFF_MULTIPLIER
Python attribute:
config.indexing.debounce_backoff_multiplierDefault:
1.2
config.indexing.debounce_backoff_threshold¶
Threshold for timestamp debouncing.
Controls the threshold for the exponential backoff for timestamp writes. The threshold is the number of writes that must occur within the debounce interval before the backoff is applied.
Config key:
indexing.debounce-backoff-thresholdEnvironment variable:
TLC_INDEXING_DEBOUNCE_BACKOFF_THRESHOLDLegacy aliases (honored with a deprecation warning):
TLC_INDEXING_TIMESTAMP_DEBOUNCE_BACKOFF_THRESHOLD
Python attribute:
config.indexing.debounce_backoff_thresholdDefault:
2
config.indexing.debounce_interval¶
Initial debounce interval for timestamp-file writing.
Controls the initial delay (in seconds) before writing timestamp files. This is part of a dynamic debounce system that adapts to write frequency.
Config key:
indexing.debounce-intervalEnvironment variable:
TLC_INDEXING_DEBOUNCE_INTERVALLegacy aliases (honored with a deprecation warning):
TLC_INDEXING_TIMESTAMP_DEBOUNCE_INTERVAL
Python attribute:
config.indexing.debounce_intervalDefault:
2.0
config.indexing.scan_interval¶
The interval between indexer scans for new objects.
This option governs the overall responsiveness of the indexing system. The setting specifies how frequently (in seconds) the indexer will check for new or modified objects in the configured scan locations.
Config key:
indexing.scan-intervalEnvironment variable:
TLC_INDEXING_SCAN_INTERVALPython attribute:
config.indexing.scan_intervalDefault:
10.0
Extensions (config.extensions.*)¶
Lists of external classes loaded at service startup (URL adapters, sample types, exporters).
config.extensions.exporters¶
Custom exporters to load on startup.
A list of dictionaries specifying custom exporter classes to load. Each dictionary should contain:
module: The fully qualified module name
class: The exporter class name
kwargs (optional): Constructor arguments
force (optional): If true, override an existing format
Config key:
extensions.exportersPython attribute:
config.extensions.exportersDefault:
[]
config.extensions.sample_types¶
Custom sample types to load on startup.
A list of dictionaries specifying custom sample type classes to load. Each dictionary should contain:
module: The fully qualified module name
class: The sample type class name
name (optional): Registration name (defaults to the class name)
force (optional): If true, override an existing sample type with the same name
Config key:
extensions.sample-typesPython attribute:
config.extensions.sample_typesDefault:
[]
config.extensions.url_adapters¶
Custom URL adapters to load on startup.
A list of dictionaries specifying custom URL adapter classes to load. Each dictionary should contain:
module: The fully qualified module name
class: The adapter class name
kwargs (optional): Constructor arguments
Example:
extensions: url-adapters: - module: my.custom.adapters class: MyAdapter kwargs: some_arg: value
Config key:
extensions.url-adaptersPython attribute:
config.extensions.url_adaptersDefault:
[]
Object Service (config.service.*)¶
Options for the Object Service server.
config.service.auth_secret¶
Shared secret for Dashboard/Object Service HMAC authentication.
Used by an on-prem Object Service to verify HMAC-signed requests from the Dashboard.
Not required when using an API key (which uses JWT authentication instead).
Config key:
service.auth-secretEnvironment variable:
TLC_OBJECT_SERVICE_AUTH_SECRETCLI argument:
--auth-secretPython attribute:
config.service.auth_secretDefault:
''Serialized to config file: no (credentials / runtime-only state)
config.service.cache.size¶
Maximum size in bytes for the in-memory object cache.
Setting the value to 0 will disable in-memory caching. Default: 1073741824 (1 GB)
Config key:
service.cache.sizeCLI argument:
--cache-sizePython attribute:
config.service.cache.sizeDefault:
1073741824
config.service.cache.timeout¶
Cache item time-to-live in seconds.
Setting the value to 0 will disable cache eviction based on time. Default: 3600 (1 hour)
Config key:
service.cache.timeoutCLI argument:
--cache-timeoutPython attribute:
config.service.cache.timeoutDefault:
3600
config.service.disable_external_media_urls¶
Disable external self-authenticated media URLs.
By default the service may resolve media URLs (images, videos, audio) used by the dashboard into external self-authenticated URLs (e.g. S3 presigned, GCS signed, Azure SAS) so the browser can fetch directly from cloud storage. When this option is set, all such media URLs are instead served through this service via a token-authenticated proxy endpoint.
This is useful when the machine running the service can access the cloud storage but the machine(s) used to run the dashboard webapp cannot or should not do so.
Config key:
service.disable-external-media-urlsEnvironment variable:
TLC_SERVICE_DISABLE_EXTERNAL_MEDIA_URLSCLI argument:
--disable-external-media-urlsPython attribute:
config.service.disable_external_media_urlsDefault:
False
config.service.host¶
Host address for the Object Service server.
Config key:
service.hostEnvironment variable:
TLC_SERVICE_HOSTCLI argument:
--hostPython attribute:
config.service.hostDefault:
'127.0.0.1'
config.service.port¶
Port for the Object Service server.
Config key:
service.portEnvironment variable:
TLC_SERVICE_PORTCLI argument:
--portPython attribute:
config.service.portDefault:
5015
config.service.watch_folders¶
Enable the watch service to monitor folders for external changes.
When enabled, the watch service monitors configured local folders and automatically updates timestamp files when changes are detected. Useful for monitoring changes made by processes outside of 3LC.
WARNING: Avoid monitoring mounted folders (FUSE mounts, cloud storage mounts) as they may cause performance issues or unexpected behavior.
Config key:
service.watch-foldersCLI argument:
--watch-local-foldersPython attribute:
config.service.watch_foldersDefault:
False