Environment Variables

Complete reference for Actyze environment variables.

Core Configuration

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL connection string
Actyze_LICENSE_KEY	Yes	-	Your Actyze license key
JWT_SECRET	Yes	-	Secret for JWT token signing
PORT	No	8080	API server port
NODE_ENV	No	production	Environment mode

AI Provider Configuration

Actyze uses a unified configuration for all AI providers via LiteLLM.

Common Variables

Variable	Required	Default	Description
EXTERNAL_LLM_MODEL	Yes	-	Model name (e.g., claude-sonnet-4-20250514, gpt-4o)
EXTERNAL_LLM_ENABLED	No	true	Enable external LLM (enabled by default)
EXTERNAL_LLM_MODE	No	auto	Mode: auto, standard, or openai-compatible
EXTERNAL_LLM_MAX_TOKENS	No	4096	Maximum tokens in response
EXTERNAL_LLM_TEMPERATURE	No	0.1	Temperature (0.0-1.0)

Provider-Specific API Keys

Set ONE of these based on your provider:

Provider	Variable	Example Model
Anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-20250514
OpenAI	OPENAI_API_KEY	gpt-4o
Google Gemini	GEMINI_API_KEY	gemini/gemini-pro
Groq	GROQ_API_KEY	groq/llama-3.3-70b-versatile
Perplexity	PERPLEXITY_API_KEY	perplexity/sonar-reasoning-pro
AWS Bedrock	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	bedrock/anthropic.claude-v2

Enterprise Gateway (Optional)

For custom AI gateways or proxies:

Variable	Required	Description
EXTERNAL_LLM_MODE	Yes	Set to openai-compatible
EXTERNAL_LLM_BASE_URL	Yes	Gateway URL
EXTERNAL_LLM_API_KEY	Yes	Gateway auth token
EXTERNAL_LLM_AUTH_TYPE	No	Auth type (bearer or x-api-key)
EXTERNAL_LLM_EXTRA_HEADERS	No	Additional headers (JSON string)

License Server

Variable	Required	Default	Description
Actyze_LICENSE_SERVER	No	https://license.actyze.com	License validation server
LICENSE_CHECK_INTERVAL	No	24h	How often to validate

Trino Configuration

Variable	Required	Default	Description
TRINO_HOST	Yes	localhost	Trino server hostname
TRINO_PORT	No	8080	Trino server port
TRINO_USER	Yes	admin	Trino username
TRINO_PASSWORD	No	-	Trino password (for authenticated instances)
TRINO_CATALOG	No	-	Default catalog
TRINO_SCHEMA	No	-	Default schema
TRINO_SSL	No	false	Enable SSL/TLS connection
TRINO_SSL_VERIFY	No	true	Verify SSL certificates (set to false for self-signed)
TRINO_QUERY_TIMEOUT_SECONDS	No	300	Hard upper limit on Trino query execution time (seconds)
EXCLUDED_CATALOGS	No	-	Comma-separated list of catalogs to exclude

Timeout Configuration

Variable	Default	Description
EXECUTE_TIMEOUT_SECONDS	120	Primary timeout variable. Controls both the Trino SQL execution timeout and the frontend HTTP request timeout (set to this value + 30s). Increase for slow enterprise Trino clusters.
DEFAULT_TIMEOUT_SECONDS	120	Overall NL→SQL pipeline timeout covering schema recommendations and LLM generation.
EXTERNAL_LLM_TIMEOUT	120	LLM API call timeout (Bedrock, Anthropic, OpenAI, etc.).

Why does EXECUTE_TIMEOUT_SECONDS affect the frontend?
The browser's Axios HTTP timeout is EXECUTE_TIMEOUT_SECONDS + 30 seconds. This prevents the UI from reporting a network error when a Trino query takes longer than the browser's default 30s timeout but the backend is still processing it successfully.

External Trino with Problematic Catalogs

When using external Trino instances, some catalogs may have backend connectivity issues. Use EXCLUDED_CATALOGS to skip these catalogs:

# Exclude catalogs with connection problems
EXCLUDED_CATALOGS=och,problematic_catalog

This prevents the schema service from crashing when external catalogs have issues you cannot control.

Database

Variable	Description	Default
DB_MAX_CONNECTIONS	Max pool size	20
DB_IDLE_TIMEOUT	Idle timeout	10m
QUERY_TIMEOUT	Query timeout	30s

Security

Variable	Description
TLS_ENABLED	Enable TLS
CORS_ORIGINS	Allowed CORS origins
RATE_LIMIT_REQUESTS	Requests per window
RATE_LIMIT_WINDOW	Time window

Logging

Variable	Options	Default
LOG_LEVEL	debug, info, warn, error	info
LOG_FORMAT	json, text	json