Visual Layer Documentation: Visual Intelligence, At Scale

Visual Layer uses two configuration mechanisms for self-hosted deployments: a JSON configuration file for application settings and feature flags, and an environment file for Docker Compose variables. Environment variables can override either source.

Configuration Hierarchy

Settings are applied in the following order, where later sources override earlier ones:

defaults.json — Built-in defaults (do not edit)
config.json — Your custom configuration
Environment variables — Override any JSON setting

Configuration File (`config.json`)

The config.json file is located at .vl/config.json inside your Visual Layer installation directory. This file controls application behavior, feature flags, and pipeline settings. Include only the settings you want to change — any setting not present in config.json uses its default value from defaults.json. To customize your deployment, create or edit .vl/config.json:

{
  "ADD_MEDIA_ENABLED": true,
  "DATASET_INGESTION_ONPREM_UI_ENABLED": true,
  "DATASET_CREATION_V2": false,
  "S3_VL_INGESTION_SERVICE_PROFILE": "",
  "ENRICHMENT_PREVIEW_SERVICE_ENABLED": true,
  "ENRICHMENT_INLINE_FLOW_ENABLED": true,
  "PREPROCESS_ENABLED": true,
  "FILE_FILTER_TREE_INCLUDE_FILES": true,
  "SERVE_ORIGINAL_VIDEO": true,
  "ENRICHMENT_DKMC2_ENABLED": true,
  "FRAME_EXTRACTION_RESIZE_HEIGHT": 720
}

After modifying config.json, restart Visual Layer services for changes to take effect:

./stop.sh && ./start.sh

Feature Flags

The following feature flags control which capabilities are available in your deployment.

Setting	Type	Default	Description
`ADD_MEDIA_ENABLED`	boolean	`true`	Allow adding new media to existing datasets without a full reindex.
`DATASET_INGESTION_ONPREM_UI_ENABLED`	boolean	`false`	Enable dataset creation from the web interface. When disabled, datasets can only be created via the CLI profiler tool.
`DATASET_CREATION_V2`	boolean	`false`	Enable the updated dataset creation workflow with a step-by-step wizard.
`ENRICHMENT_PREVIEW_SERVICE_ENABLED`	boolean	`false`	Allow previewing enrichment model results on a sample before running on the full dataset.
`ENRICHMENT_INLINE_FLOW_ENABLED`	boolean	`false`	Run enrichment models within the same pipeline process instead of requiring a separate step.
`PREPROCESS_ENABLED`	boolean	`false`	Enable preprocessing (image resizing, frame extraction, cleaning) before indexing.
`ENRICHMENT_DKMC2_ENABLED`	boolean	`false`	Enable DKMC2 (Deep K-Means Clustering v2), which generates multiple embedding vectors per image for fine-grained instance retrieval.

Storage and Media Settings

These settings control how media files are stored, processed, and displayed.

Setting	Type	Default	Description
`S3_VL_INGESTION_SERVICE_PROFILE`	string	`""`	AWS credentials profile name for S3-based ingestion. Leave empty to use the default credential chain.
`FILE_FILTER_TREE_INCLUDE_FILES`	boolean	`true`	Show individual files in the file filter tree. Disabling this improves performance for datasets with many files.
`SERVE_ORIGINAL_VIDEO`	boolean	`false`	Serve videos from their original location instead of copying to the CDN directory. Reduces disk usage but requires original files to remain accessible.
`FRAME_EXTRACTION_RESIZE_HEIGHT`	integer	`0`	Target height in pixels for video frame extraction. `0` preserves original resolution. Common values: `576`, `720`.

General Settings

Additional settings for authentication, dataset limits, and data quality.

Setting	Type	Default	Description
`DISABLE_AUTH`	boolean	`false`	Disable authentication. Typically set to `true` for single-user deployments.
`MAX_NUM_OF_IMAGES`	integer	`100000000`	Maximum number of images allowed per dataset.
`CLEAN_THRESHOLD`	float	`-1`	Similarity threshold for near-duplicate detection. Images above this threshold are flagged as near-duplicates. `-1` uses the automatic threshold.
`LOG_LEVEL`	string	`INFO`	Controls logging verbosity. Accepted values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. At `DEBUG`, additional internal processing messages are logged including detailed diagnostics.
`SWAP_RGB_CHANNELS_FOR_TIFF_HEIC`	boolean	`false`	Correct color rendering for TIFF and HEIC images where red and blue channels appear reversed.

Environment File (`.env`)

The .env file is located at the root of the Visual Layer installation directory. Docker Compose reads this file when starting services. It controls hardware profile, image versions, and deployment options. A typical .env file:

REPO=visuallayer
IMAGE_PREFIX=onprem-
VL_VERSION=latest
VL_MODEL_VERSION=7.0
PG_VERSION=16
VL_PG_VERSION=latest
HARDWARE=cpu
HOST_OS=Linux
MODEL_PACK_FROM_IMAGE=false

Key `.env` Variables

The following variables control the deployment environment.

Variable	Description	Example Values
`HARDWARE`	Hardware profile for the deployment.	`cpu`, `gpu`
`VL_VERSION`	Visual Layer application version.	`latest`, `2.33.3-rc7`
`VL_MODEL_VERSION`	Version of bundled ML models.	`7.0`
`HOST_OS`	Host operating system.	`Linux`, `Darwin`
`MODEL_PACK_FROM_IMAGE`	Load models from Docker image instead of downloading.	`true`, `false`

You can also add config.json settings as environment variables in the .env file. Environment variables take precedence over JSON configuration:

LOG_LEVEL=10
SERVE_ORIGINAL_VIDEO=true

After modifying .env, restart the services for changes to take effect:

./stop.sh && ./start.sh

Environment Variable Overrides

Any config.json setting can also be set as an environment variable exported in the shell before starting Visual Layer. Environment variables always take the highest precedence.

export LOG_LEVEL='10'
export SERVE_ORIGINAL_VIDEO=true

Installation

Install and start Visual Layer on your infrastructure.

S3 Configuration

Configure S3 storage for self-hosted deployments.

System Requirements

Hardware and software prerequisites for self-hosted deployments.

Useful Scripts

Maintenance and administration scripts for self-hosted environments.

Installation and Configuration

Usage

Administration

Troubleshooting

General Settings

Configuration Hierarchy

Configuration File (`config.json`)

Feature Flags

Storage and Media Settings

General Settings

Environment File (`.env`)

Key `.env` Variables

Environment Variable Overrides

Installation

S3 Configuration

System Requirements

Useful Scripts

​Configuration Hierarchy

​Configuration File (config.json)

​Feature Flags

​Storage and Media Settings

​General Settings

​Environment File (.env)

​Key .env Variables

​Environment Variable Overrides

​Related Resources

Installation

S3 Configuration

System Requirements

Useful Scripts

Configuration Hierarchy

Configuration File (`config.json`)

Feature Flags

Storage and Media Settings

General Settings

Environment File (`.env`)

Key `.env` Variables

Environment Variable Overrides

Related Resources