Configuration Parameters

Full Configuration File

# LocalVectorDB Server Configuration v1.0
[database]
root_dir = "/var/www/localvectordb_server/.lvdb"  # Recommend absolute paths in production environment
timeout = 300
connection_pool_size = 10
enable_gpu = false
enable_fts = true
chunk_size = 500
chunk_overlap = 1
chunking_method = "lines"

# Faiss index settings
faiss_index_type = "IndexFlatL2"       # Can be one of: IndexFlatL2, IndexFlatIP, IndexHNSWFlat, IndexLSH
# faiss_index_hnsw_flat_neighbors = 0  # Only used for IndexHNSWFlat, set the number of neighbors for the graph
# faiss_index_lsh_bits = 1536          # Only used for IndexLSH Typically set to twice the embedding dimension
# mmap_index = false                   # Read-only: memory-map the index so many workers share one page-cached copy

[database.default_metadata_schema]
file_path = { type = "text", indexed = true, required = false }
created_at = { type = "date", indexed = true, required = false }
last_modified = { type = "date", indexed = true, required = false }
mimetype = { type = "text", indexed = true, required = false }
tags = { type = "json", indexed = false, required = false }
# You can define the type directly if you don't need indexing and the field is not required
file_size_bytes = "integer"


[embedding]
provider = "ollama"
model = "nomic-embed-text"
batch_size = 64
timeout = 30
max_retries = 3

[server]
debug = false
environment = "development"
host = "127.0.0.1"
port = 8000
log_level = "INFO"
log_format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
file_upload_enabled = true   # enables the /api/v1/databases/<db-name>/upload route
max_request_size = 104857600
enable_rate_limiting = false
rate_limit = "100 per minute"
rate_limit_storage_uri = "memory://"

proxy_enabled = true
# REQUIRED when proxy_enabled = true: list of trusted proxy IPs / CIDR blocks
# allowed to set forwarded headers. Validation fails if this is empty.
trusted_proxies = ["10.0.0.0/8", "127.0.0.1"]

cache_enabled = true
cache_ignore_errors = true
cache_timeout = 300
cache_type = "RedisCache"

[server.cache_settings]  # These parameters are passed to the cache constructor. See https://cachelib.readthedocs.io/en/stable/
host = "localhost"
port = 6379
db = 0
password = "$REDIS_PASSWORD"   # '$' prefix indicates to load the environment variable
key_prefix = "my-db-prefix-"   # Allows you to run multiple servers using single redis db.

# IMPORTANT: if ``proxy_enabled = true``, you must set the proxy settings AND trusted_proxies.
# The specific values depend on your server set-up. Set the number of proxies forwarding each header.
# When behind a reverse proxy (nginx, etc.), configure trusted_hosts, trusted_proxies, and proxy settings.
[server.proxy_settings]
x_for = 1
x_proto = 1
x_host = 1
x_prefix = 1

[server.security]
# API settings
require_api_key = true
key_database_path = "/path/to/api_keys.db"    # If not provided, located in ``{database.root_dir}/api_keys.db``
# Recommended to set keys to expire
default_key_expiry_days = 90
api_key_header = "Authorization"
auto_prune_expired_keys = false
key_audit_logging = true
auth_log_level = "INFO"
warn_expiring_days = 7

# Filter connections by hostname for best practices.
trusted_hosts = ["your-website.com", "*.subdomain.example.com", "localhost"]

# CORS settings
cors_enabled = true
# IMPORTANT: if CORS is enabled, you need to set the allowed origins!
cors_allowed_origins = ["http://localhost:8000", "https://your-website.com"]
cors_allowed_methods = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
# If you changed the default Authorization header, make sure to put it here too
cors_allowed_headers = ["Content-Type", "Authorization"]
cors_max_age = 86400

[extraction]
# Hardened defaults for untrusted uploads; relax only for trusted content.
allow_remote_fetch = false           # Fetch remote assets referenced by a document (SSRF risk)
allowed_hosts = []                   # Host allowlist applied when allow_remote_fetch = true
strip_dangerous_elements = true      # HTML: strip scripts and event handlers
attachment_mode = "skip"             # How embedded attachments/assets are handled

Note

The configuration file shown above is a representative example of a configuration that might be used in a production environment. You will need to modify this for your server! Do not copy and paste and use without modifications, as it almost certainly won’t work.

Database Settings

Parameter	Type	Default	Description
root_dir	str	"./.lvdb"	Root directory for storing database files and data.
timeout	int	300	Timeout for database operations, in seconds.
connection_pool_size	int	10	Number of simultaneous database connections allowed (connection pool size).
enable_gpu	bool	false	Whether to enable GPU acceleration for database operations (if supported).
enable_fts	bool	true	Whether to enable Full-Text Search (FTS) capabilities.
faiss_index_type	str	IndexFlatL2	The type of faiss index to use: IndexFlatL2 (exact L2 distance), IndexFlatIP (exact inner product), IndexHNSWFlat (graph-based approximate-nearest neighbors, fast), IndexLSH (binary hashing)
faiss_index_hnsw_flat_neighbors	int	null	The number of neighbors for the IndexHNSWFlat index. Ignored if using a different index.
faiss_index_lsh_bits	int	null	The number of bits to use for the binary hashing, defaults to 2x the number of embedding dimensions if not provided and using IndexLSH, ignored otherwise.
mmap_index	bool	false	Memory-map the FAISS index (IO_FLAG_MMAP) instead of loading a private, RAM-resident copy. Lets many read-only workers share one page-cached copy of the index for read fan-out. A memory-mapped database is read-only and refuses writes, so set this only on reader processes and route all writes to a single writer process with mmap_index = false.
chunk_size	int	500	Default size (in tokens or lines, depending on chunking_method) for document chunking.
chunk_overlap	int	1	Number of tokens/lines to overlap between chunks.
chunking_method	str	"lines"	Method for splitting documents into chunks (e.g., "lines").
default_metadata_schema	Dictionary (table) or null	null	Default metadata schema as a table of field names to MetadataField definitions (type, indexed, required) for new databases.

Embedding Settings

Parameter	Type	Default	Description
provider	str	"ollama"	Embedding provider to use (e.g., "ollama", "openai").
model	str	"nomic-embed-text"	Embedding model name to use with the provider.
base_url	str or null	null	Base URL for the embedding provider’s API (if required).
api_key	str or null	null	API key for the embedding provider (required for some providers, e.g., OpenAI).
batch_size	int	64	Number of items to embed per API request (batch size).
timeout	int	30	Timeout for embedding API requests, in seconds.
max_retries	int	3	Maximum number of retries for embedding API requests.
config	Dictionary (table) or null	null	Additional provider-specific configuration options.

Server Settings

Note

Parameters from require_api_key onward in the table below (authentication, key management, trusted_hosts, and CORS settings) live under the [server.security] table, not [server]. The remaining parameters (debug … trusted_proxies) live under [server]. Use the dot-notation paths accordingly, e.g. server.security.require_api_key and server.host.

Parameter	Type	Default	Description
debug	bool	false	Whether to run the server in debug mode (enables verbose error output).
environment	str	"development"	Server environment (e.g., "development", "production").
host	str	"127.0.0.1"	Host address to bind the server to.
port	int	8000	Port number to bind the server to.
log_level	str	"INFO"	Logging level ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL").
log_format	str	'%(asctime)s - %(name)s - %(levelname)s - %(message)s'	Format string for log messages.
file_upload_enabled	bool	false	Whether to allow file uploads via the /api/v1/databases/<db-name>/upload route.
max_request_size	int	104857600 (100 MB)	Maximum allowed size for incoming requests, in bytes.
enable_rate_limiting	bool	false	Whether to enable API rate limiting.
rate_limit	str	"100 per minute"	Rate limit rule (e.g., requests per time period).
rate_limit_storage_uri	str	"memory://"	Storage backend URI for rate limiting (e.g., "memory://", "redis://...").
cache_enabled	bool	false	Whether to enable server-side caching.
cache_ignore_errors	bool	true	If true, cache errors are ignored rather than causing failures.
cache_timeout	int	300	Default cache timeout, in seconds.
cache_key_prefix	str	"lvdb_cache_"	Prefix for all cache keys.
cache_type	string	"SimpleCache"	Type of cache backend to use, one of: "SimpleCache", "RedisCache", "FileSystemCache", "MemcachedCache", "UWSGICache", "DynamoDbCache", "MongoDbCache"
cache_settings	dict or null	null	Additional configuration for the cache backend (e.g. Redis cache config settings). Set as a TOML table under [server.cache_settings]. See https://cachelib.readthedocs.io/en/stable/ Deprecated in favour of the typed backend keys below.
redis_host / redis_port / redis_db	str / int / int	"localhost" / 6379 / 0	Redis connection settings (used when cache_type = "RedisCache").
redis_password	str or null	null	Redis password, if required.
redis_url	str or null	null	Full Redis URL; when set, overrides the individual redis_* settings.
redis_socket_timeout / redis_socket_connect_timeout	float or null	null	Redis socket read / connect timeouts in seconds.
filesystem_cache_dir	str or null	null	Directory for FileSystemCache entries.
filesystem_cache_threshold	int	500	Maximum number of items FileSystemCache keeps before pruning.
memcached_servers	list of str	["127.0.0.1:11211"]	Memcached server addresses (used when cache_type = "MemcachedCache").
memcached_username / memcached_password	str or null	null	Memcached SASL credentials, if required.
use_single_cache	bool	false	Reuse the general cache for the multi-worker database registry instead of configuring a separate db_registry backend.
proxy_enabled	bool	false	Whether to enable proxy support (for use behind reverse proxies).
proxy_settings	dict or null	null	Proxy configuration settings. Required if proxy_enabled is true. Must be a dict with: x_for, x_proto, x_host, x_prefix, set to the number of proxies forwarding the X-Forwarded- headers. Set as a TOML table under [server.proxy_settings].
trusted_proxies	list of str	[]	List of trusted proxy IP addresses or CIDR blocks allowed to set forwarded headers. Required (non-empty) when proxy_enabled is true — configuration validation fails otherwise. Set under [server].
require_api_key	bool	false	Whether API key authentication is required for access.
api_key_header	str	"Authorization"	HTTP header used to transmit the API key.
trusted_hosts	list of str or null	null	List of trusted hostnames or IP addresses for incoming requests.
key_database_path	str or null	null	Path to the API key database file (null = in the database.root_dir folder as api_keys.db).
default_key_expiry_days	int or null	null	Default number of days before API keys expire (null = no expiration).
auto_prune_expired_keys	bool	false	Whether to automatically remove expired API keys.
key_audit_logging	bool	true	Whether to log API key usage for audit purposes.
auth_log_level	str	"INFO"	Logging level for authentication events.
warn_expiring_days	int	7	Number of days before key expiry to issue warnings.
cors_enabled	bool	true	Whether to enable Cross-Origin Resource Sharing (CORS).
cors_allowed_origins	str or list of str	"*"	Allowed origins for CORS ("*", or a list of origins).
cors_allowed_methods	list of str	["GET", "POST", "PUT", "DELETE", "OPTIONS"]	Allowed HTTP methods for CORS.
cors_allowed_headers	list of str	["Content-Type", "Authorization"]	Allowed HTTP headers for CORS.
cors_max_age	int	86400	Maximum time (in seconds) for browsers to cache CORS preflight responses.
security_headers_enabled	bool	true	Master switch for the security-header / CSP middleware. When false, none of the headers below are applied.
force_https	bool	false	Redirect HTTP requests to HTTPS and mark cookies secure.
strict_transport_security	bool	true	Send the Strict-Transport-Security (HSTS) header.
strict_transport_security_max_age	int	31536000	max-age (seconds) for the HSTS header.
content_security_policy	dict	see below	Content-Security-Policy directives as a mapping of directive to source expression (default allows 'self' plus inline scripts/styles). Set as a TOML table under [server.security.content_security_policy].
content_type_nosniff	bool	true	Send X-Content-Type-Options: nosniff.
x_frame_options	str	"DENY"	Value for the X-Frame-Options header.
x_xss_protection	bool	true	Send the legacy X-XSS-Protection header.
referrer_policy	str	"strict-origin-when-cross-origin"	Value for the Referrer-Policy header.

Extraction Settings

These live under the [extraction] table and control how uploaded files are converted to Markdown (via all2md). Defaults are hardened for untrusted uploads. See File Extraction System for the full security model.

Parameter	Type	Default	Description
allow_remote_fetch	bool	false	Allow fetching remote assets referenced by a document. Leaving this off avoids an SSRF surface.
allowed_hosts	list of str or null	null	Host allowlist applied when allow_remote_fetch is enabled (null = all hosts).
strip_dangerous_elements	bool	true	HTML only: strip <script> tags and inline event handlers.
attachment_mode	str	"skip"	How embedded attachments/assets are handled during extraction.

Note

All configuration parameters can also be set via environment variables with the LVDB_ prefix, using uppercase and underscores, e.g., LVDB_SERVER_DEBUG, LVDB_DATABASE_ROOT_DIR, LVDB_EXTRACTION_ALLOW_REMOTE_FETCH, etc.