Configuration¶

3LC has several configuration options, which control data discovery, logging, and network configuration.

The full reference, grouped by category, lives on the Configuration Options Reference page — each option lists its YAML key, environment variable, CLI argument and Python attribute side by side. The underlying tlcconfig.options module is the Python-level source of truth for the same metadata.

3LC tries to have as good defaults as possible, however some times you may want to persist a machine global configuration. This can be achieved by using the default configuration file. The configuration file is located in $HOME/.config/3LC/config.yaml on Linux and in %LOCALAPPDATA%\3LC\3LC\config.yaml on Windows. The location can be overridden by the TLC_CONFIG_FILE environment variable.

The 3lc config command group inspects and manages the configuration. The two main verbs are:

  • 3lc config show — print the current effective configuration. Use -f yaml to emit YAML (suitable for redirecting into a config file).

  • 3lc config project-root <URL> — set or update the project root in the user configuration file.

To create or refresh the user configuration file, redirect a YAML dump:

# Write the current effective configuration to the default user config file location
3lc config show -f yaml > "$HOME/.config/3LC/config.yaml"

3lc config show reads the current configuration — including environment variables and any 3lc command-line options supplied alongside — so you can layer overrides on a single invocation:

# Persist the project root in the user configuration file
3lc config project-root /some/location

# Persist an alias by emitting the resolved configuration to the user config file
TLC_ALIAS_CIFAR10_LOCATION="/some/location" 3lc config show -f yaml > "$HOME/.config/3LC/config.yaml"

Other useful subcommands: 3lc config validate (checks the current configuration) and 3lc config path (prints the resolved configuration-file path).

An example configuration file can be seen below.

Example config.yaml
# Location for reading and writing 3LC project data.
project-root-url: /home/build/.local/share/3LC/projects
# Whether to display progress bars.
display-progress: true
service:
# Port for the Object Service server.
  port: 5015
# Host address for the Object Service server.
  host: 127.0.0.1
  cache:
# Maximum size in bytes for the in-memory object cache.
    size: 1073741824
# Cache item time-to-live in seconds.
    timeout: 3600
# Enable the watch service to monitor folders for external changes.
  watch-folders: false
# Disable external self-authenticated media URLs.
  disable-external-media-urls: false
logging:
# Log level for the 3LC logger.
  level: WARNING
# Log file path for the 3LC logger.
  file: /home/build/.local/state/3LC/log/3lc.log
indexing:
# The interval between indexer scans for new objects.
  scan-interval: 10.0
# Initial debounce interval for timestamp-file writing.
  debounce-interval: 2.0
# Threshold for timestamp debouncing.
  debounce-backoff-threshold: 2
# Maximum backoff level for timestamp debouncing.
  debounce-backoff-max-level: 0
# Multiplier for timestamp debounce backoff.
  debounce-backoff-multiplier: 1.2
# Scales transient-class retry cadences in the indexer's failed-URL skip store.
  backoff-multiplier: 1.0

Configuration files¶

Resolution¶

  1. Primary configuration
    The system attempts to load configuration from:

    • The file specified by --config-file

    • The file referenced by the TLC_CONFIG_FILE environment variable

    • A default, platform-dependent configuration file

  2. Project root configuration
    After the primary configuration, if config.3lc.yaml exists in the project root (the location set by project_root_url / TLC_PROJECT_ROOT_URL), it will be loaded and merged with the current configuration.

Disabling configuration file reading

  • If --no-config-file is specified on the command line or TLC_CONFIG_FILE is set to an empty string, no configuration files are considered.

Default/project aliases¶

To make sharing of projects and results easier the system supports a special type of partial configuration file that can be used to persist default values for project aliases. These files must adhere to the following rules:

  • Naming: The files must be named default_aliases.3lc.yaml.

  • Content: The files should contain only the aliases option.

  • Location: The files must be placed inside a project or scan folder:

    • <PROJECT_SCAN_URL>/project-a/default_aliases.3lc.yaml # project aliases

    • <EXTRA_XXX_SCAN_URL>/default_aliases.3lc.yaml # default aliases for single folder

Project alias configuration files are read by the indexing system and will be reloaded when changed.

Overriding configuration options¶

3LC follows the following precedence rules for configuration:

api-call > command-line argument > environment variable > configuration file

Configuration files have the following precedence from highest to lowest:

  1. The user configuration file (the primary configuration described above).

  2. A project-root config.3lc.yaml.

  3. Data-bundled configuration files discovered alongside project data (e.g. default_aliases.3lc.yaml).

Below all of these sits runtime bookkeeping recorded by the indexer (for example, scan URLs derived from discovered project configuration). Such entries lose to every user-authored source and are never written back to configuration files.

The rules above should be straightforward when launching the Object Service from the command line, but it is more complicated when importing the tlc package in a Jupyter notebook (e.g. import tlc). Importing tlc reads the configuration files and environment variables, so set environment variables — or point TLC_CONFIG_FILE at the right file — before the import. After import, options can still be changed programmatically through Configuration; such changes sit at the api-call tier and take precedence over all other sources.