Skip to main content

Configuration

Hugr can be configured using environment variables. This page describes all available configuration options for the hugr server.

Server Configuration​

General Settings​

  • BIND - Network interface and port (default: :15000)

    BIND=":15000"

    If you want to bind only to localhost, use 127.0.0.1:15000 instead of :15000

  • SERVICE_BIND - Metrics and health check endpoint (default: empty)

    SERVICE_BIND=":15001"

  • ADMIN_UI - Enable GraphiQL interface (default: true)

    ADMIN_UI=true

    When disabled, the GraphiQL interface will not be available, but the GraphQL API will still function

  • DEBUG - SQL query logging (default: false)

    DEBUG=false

  • ALLOW_PARALLEL - Parallel query execution (default: true)

    ALLOW_PARALLEL=true

  • MAX_PARALLEL_QUERIES - Query concurrency limit (default: 0/unlimited)

    MAX_PARALLEL_QUERIES=10

  • MAX_DEPTH - GraphQL hierarchy depth (default: 7)

    MAX_DEPTH=7

TLS Configuration​

Enable HTTPS by providing TLS certificate and key file paths. When both are set, the server serves HTTPS instead of HTTP. When neither is set, the server uses plain HTTP (default).

  • TLS_CERT_FILE - Path to PEM-encoded TLS certificate file (default: empty/disabled)

    TLS_CERT_FILE=/etc/ssl/certs/hugr.crt

  • TLS_KEY_FILE - Path to PEM-encoded TLS private key file (default: empty/disabled)

    TLS_KEY_FILE=/etc/ssl/private/hugr.key

Both variables must be set together. Setting only one will cause the server to exit with an error. The server validates the certificate and key at startup and will fail fast with a descriptive error if the files are missing, unreadable, or mismatched.

HTTPS example:

TLS_CERT_FILE=/etc/ssl/certs/hugr.crt \
TLS_KEY_FILE=/etc/ssl/private/hugr.key \
BIND=:443 \
./server

Docker with TLS:

docker run -d \
  -v /path/to/certs:/certs:ro \
  -e TLS_CERT_FILE=/certs/server.crt \
  -e TLS_KEY_FILE=/certs/server.key \
  -e BIND=:443 \
  -p 443:443 \
  ghcr.io/hugr-lab/server

Self-signed certificates for development:

make certs

This generates a self-signed certificate and key in .local/certs/ valid for localhost and 127.0.0.1 (365 days).

note

The sidecar service endpoint (health checks and metrics on SERVICE_BIND) always uses plain HTTP regardless of TLS configuration. This is by design, as health and metrics endpoints typically serve internal infrastructure traffic.

DuckDB Engine Configuration​

  • DB_TIMEZONE - Default server timezone (IANA name)

    DB_TIMEZONE=Europe/Moscow

    Sets the default timezone for all DuckDB connections. When a client does not send a timezone header, this timezone is used for TIMESTAMPTZ display. If not set, falls back to the system timezone (typically UTC in containers). Clients can override this per-request using the X-Hugr-Timezone HTTP header.

  • DB_HOME_DIRECTORY - Credential persistence path

    DB_HOME_DIRECTORY=/path/to/credentials

    This is where DuckDB stores credentials for remote data sources (e.g., S3, Azure, GCS). Typically left empty to use in-memory DuckDB

  • DB_PATH - Management database file location

    DB_PATH=/path/to/management.db

  • DB_MAX_OPEN_CONNS / DB_MAX_IDLE_CONNS - Connection pooling

    DB_MAX_OPEN_CONNS=10
    DB_MAX_IDLE_CONNS=5

  • DB_ALLOWED_DIRECTORIES / DB_ALLOWED_PATHS - Filesystem restrictions

    DB_ALLOWED_DIRECTORIES=/data,/workspace
    DB_ALLOWED_PATHS=/data/file1.csv,/data/file2.parquet

  • DB_MAX_MEMORY - Memory limit (default: 80% system RAM)

    DB_MAX_MEMORY=4GB

    Setting this too high may cause out-of-memory errors; too low will reduce query performance

  • DB_TEMP_DIRECTORY - Temporary storage location

    DB_TEMP_DIRECTORY=/tmp/duckdb

  • DB_WORKER_THREADS - Worker thread count (default: CPU cores)

    DB_WORKER_THREADS=4

  • DB_PG_CONNECTION_LIMIT - PostgreSQL connections (default: 64)

    DB_PG_CONNECTION_LIMIT=64

    Used for each PostgreSQL data source to pool connections to the concrete data source

  • DB_PG_PAGES_PER_TASK - PostgreSQL pages per task for parallel scans (default: 0)

    DB_PG_PAGES_PER_TASK=1000

  • DB_ENABLE_LOGGING - Enable DuckDB internal logging (default: false)

    DB_ENABLE_LOGGING=true

Schema Cache Configuration​

  • SCHEMA_CACHE_MAX_ENTRIES - Maximum number of compiled schema entries to cache (default: 0/disabled)

    SCHEMA_CACHE_MAX_ENTRIES=100

  • SCHEMA_CACHE_TTL - Time-to-live for cached schema entries (default: 0s/no expiration)

    SCHEMA_CACHE_TTL=5m

Core Database Configuration​

The core database stores hugr metadata including data sources, catalogs, and schema definitions. Also stores roles and permissions, and managed API keys if enabled.

  • CORE_DB_PATH - DuckDB file or PostgreSQL DSN

    # DuckDB file
    CORE_DB_PATH=/data/core.db

    # PostgreSQL connection
    CORE_DB_PATH=postgres://user:password@host:5432/database

    For cluster deployments, PostgreSQL is required; DuckDB can only be used in read-only mode

  • CORE_DB_READONLY - Read-only mode flag

    CORE_DB_READONLY=false

S3 Storage Configuration​

For DuckDB core database that is placed in S3 object storage:

  • CORE_DB_S3_ENDPOINT - S3 endpoint for cloud storage

    CORE_DB_S3_ENDPOINT=https://s3.amazonaws.com

  • CORE_DB_S3_REGION - AWS region

    CORE_DB_S3_REGION=us-east-1

  • CORE_DB_S3_KEY / CORE_DB_S3_SECRET - AWS credentials

    CORE_DB_S3_KEY=AKIAIOSFODNN7EXAMPLE
    CORE_DB_S3_SECRET=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  • CORE_DB_S3_USE_SSL - SSL enforcement

    CORE_DB_S3_USE_SSL=true

MCP Configuration​

  • MCP_ENABLED - Enable the Model Context Protocol endpoint at /mcp (default: false)

    MCP_ENABLED=true

  • EMBEDDER_URL - URL of an OpenAI-compatible embeddings API for semantic search in MCP

    EMBEDDER_URL=http://localhost:11434/v1/embeddings

  • EMBEDDER_VECTOR_SIZE - Dimension of embedding vectors produced by the embedder

    EMBEDDER_VECTOR_SIZE=384

CORS Settings​

Configure Cross-Origin Resource Sharing (CORS) for web applications. Also required for embedding AdminUI (GraphiQL) provided by hugr nodes as iframe:

  • CORS_ALLOWED_ORIGINS - Permitted domains (comma-separated)

    CORS_ALLOWED_ORIGINS=http://localhost:3000,https://app.example.com

  • CORS_ALLOWED_METHODS - HTTP verbs (default: GET, POST, PUT, DELETE, OPTIONS)

    CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS

  • CORS_ALLOWED_HEADERS - Request headers

    CORS_ALLOWED_HEADERS=Content-Type,Authorization

Authentication​

  • ALLOWED_ANONYMOUS - Anonymous access (default: true)

    ALLOWED_ANONYMOUS=true

  • ANONYMOUS_ROLE - Default role (default: "anonymous")

    ANONYMOUS_ROLE=anonymous

  • SECRET_KEY - API authentication key

    SECRET_KEY=your-secret-key-here

  • AUTH_CONFIG_FILE - Configuration file path (JSON/YAML)

    AUTH_CONFIG_FILE=/config/auth.yaml

  • ALLOWED_MANAGED_API_KEYS - GraphQL API key management

    ALLOWED_MANAGED_API_KEYS=true

Cache Configuration​

See the Caching section for detailed cache configuration options.

Cluster Configuration​

  • CLUSTER_ENABLED - Enable cluster mode (default: false)

    CLUSTER_ENABLED=true

  • CLUSTER_ROLE - Node role: management or worker (default: empty/standalone)

    CLUSTER_ROLE=worker

  • CLUSTER_NODE_NAME - Unique name for this node in the cluster

    CLUSTER_NODE_NAME=worker-1

  • CLUSTER_NODE_URL - URL where this node is reachable by the management node

    CLUSTER_NODE_URL=http://worker-1:15000

  • CLUSTER_SECRET - Shared secret for cluster authentication (must match across all nodes)

    CLUSTER_SECRET=your-cluster-secret

  • CLUSTER_HEARTBEAT - Interval between heartbeat signals (default: 30s)

    CLUSTER_HEARTBEAT=30s

  • CLUSTER_GHOST_TTL - Time after which an unresponsive node is considered dead (default: 2m)

    CLUSTER_GHOST_TTL=2m

  • CLUSTER_POLL_INTERVAL - Interval for workers to poll schema version from management (default: 30s)

    CLUSTER_POLL_INTERVAL=30s

See the Clustered Deployment section for architecture details and deployment examples.

OIDC Integration​

For authentication with OpenID Connect providers:

  • OIDC_ISSUER - Identity provider URL

    OIDC_ISSUER=https://accounts.google.com

  • OIDC_CLIENT_ID - Application identifier

    OIDC_CLIENT_ID=your-client-id

  • OIDC_CLIENT_SECRET - Client secret for OIDC authorization code exchange (default: empty). Required when using the MCP OAuth proxy.

    OIDC_CLIENT_SECRET=your-client-secret

  • OIDC_SCOPES - Scopes to request from the OIDC provider (default: openid profile email)

    OIDC_SCOPES=openid profile email

  • OIDC_REDIRECT_URL - Optional override for the OAuth callback URL. Auto-derived from the request Host header if not set. Useful when Hugr is behind a reverse proxy or tunnel.

    OIDC_REDIRECT_URL=https://hugr.example.com/oauth/callback

  • OIDC_TLS_INSECURE - Certificate verification bypass (not recommended for production)

    OIDC_TLS_INSECURE=false

  • OIDC_COOKIE_NAME - Session cookie identifier

    OIDC_COOKIE_NAME=hugr_session

    Hugr uses this cookie name to extract the token if it is not provided in the Authorization header

  • OIDC_USERNAME_CLAIM / OIDC_USERID_CLAIM / OIDC_ROLE_CLAIM - Token attributes

    OIDC_USERNAME_CLAIM=preferred_username
    OIDC_USERID_CLAIM=sub
    OIDC_ROLE_CLAIM=roles

Hugr Apps (Pluggable Applications)​

Settings for hugr-app heartbeat monitoring. Hugr periodically checks connected applications and suspends unavailable ones.

  • HUGR_APP_HEARTBEAT_INTERVAL - Time between health checks (default: 30s)

    HUGR_APP_HEARTBEAT_INTERVAL=30s

  • HUGR_APP_HEARTBEAT_TIMEOUT - Timeout per health check (default: 10s)

    HUGR_APP_HEARTBEAT_TIMEOUT=10s

  • HUGR_APP_HEARTBEAT_RETRIES - Failed checks before suspending an app (default: 3)

    HUGR_APP_HEARTBEAT_RETRIES=3

See the Hugr Apps section for building pluggable applications.

MCP OAuth Proxy​

When MCP is enabled with OIDC authentication, Hugr can act as a stateless OAuth 2.1 proxy so that MCP clients (Claude Desktop, Cursor, etc.) can authenticate via your OIDC provider. The proxy encrypts all transient state into request parameters — no server-side sessions, works identically in standalone and cluster modes.

The proxy activates automatically when MCP_ENABLED=true, OIDC is configured, and a client secret is available.

  • MCP_OAUTH_CLIENT_ID - Separate OIDC client ID for the MCP OAuth proxy (default: empty, falls back to OIDC_CLIENT_ID)

    MCP_OAUTH_CLIENT_ID=hugr-mcp

  • MCP_OAUTH_CLIENT_SECRET - Separate OIDC client secret for the MCP OAuth proxy (default: empty, falls back to OIDC_CLIENT_SECRET)

    MCP_OAUTH_CLIENT_SECRET=your-mcp-client-secret

Using separate MCP OAuth credentials is recommended — it gives you control over which claims and scopes are returned to MCP clients independently from the main OIDC client.

note

SECRET_KEY must be set when using the MCP OAuth proxy — it is used for AES-256-GCM encryption of OAuth state parameters.

Configuration File Example​

You can create a .env file to configure your hugr deployment:

# Server Configuration
BIND=:15000
ADMIN_UI=true
DEBUG=false
MAX_DEPTH=7

# Core Database
CORE_DB_PATH=/data/core.db

# MCP
MCP_ENABLED=true
EMBEDDER_URL=http://localhost:11434/v1/embeddings
EMBEDDER_VECTOR_SIZE=384

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:3000

# Authentication
ALLOWED_ANONYMOUS=true
ANONYMOUS_ROLE=anonymous

# Cache (L1 - In-Memory)
CACHE_L1_ENABLED=true
CACHE_L1_MAX_SIZE=512

# Cache (L2 - Redis)
CACHE_L2_ENABLED=true
CACHE_L2_BACKEND=redis
CACHE_L2_ADDRESSES=redis:6379

Next Steps​