Skip to content

Environment Variables

Variable Default Description
PEGAPROX_PORT 5000 Server port
PEGAPROX_HOST 0.0.0.0 Bind address
PEGAPROX_DEBUG false Enable debug mode
PEGAPROX_API_RATE_LIMIT 1200 Max API requests per window
PEGAPROX_API_RATE_WINDOW 60 Rate limit window (seconds)
PEGAPROX_SSH_MAX_CONCURRENT 25 Max concurrent SSH sessions
PEGAPROX_ALLOWED_ORIGINS (none) Comma-separated CORS origins
PEGAPROX_WORKERS max(32, CPU×16) Concurrent request-handler greenlet pool. Auto-scales with CPU (e.g. 4-core → 64, 8-core → 128, 32-core → 512). Each live SSE/WebSocket stream holds a slot for its lifetime, so the floor was raised. Override only to set a tighter cap.
PEGAPROX_NO_GEVENT (unset) Set to "1" to disable Gevent
PEGAPROX_MAX_REQUEST_SIZE 10MB Max API request size
PEGAPROX_MAX_UPLOAD_SIZE 4GB Max file upload size
PEGAPROX_HTTP_PORT 80 HTTP port for redirect to HTTPS
PEGAPROX_CIPHER_MEMORY_SECURITY auto SQLCipher page-cache mlock(). auto (default) detects rootless containers / low RLIMIT_MEMLOCK and disables; on forces; off suppresses. At-rest encryption unaffected. See Docker → Kubernetes section for details.
PEGAPROX_LOG_LEVEL (unset → INFO) Root + app logger level (DEBUG / INFO / WARNING / ERROR). Set DEBUG to surface the per-node status poll line.
PEGAPROX_FILE_LOG_LEVEL DEBUG Level for the per-cluster logs/<id>.log FileHandler.
PEGAPROX_DISABLE_FILE_LOG (unset) Set to 1 to skip the per-cluster log file entirely (useful when shipping straight to journald + SIEM).

Example Production Configuration

# /etc/default/pegaprox
PEGAPROX_PORT=5000
PEGAPROX_API_RATE_LIMIT=2400
PEGAPROX_SSH_MAX_CONCURRENT=50

Additional Environment Variables

Variable Default Description
PEGAPROX_BEHIND_PROXY false Enable reverse proxy mode. Trusts X-Forwarded-For from allowed proxies.
PEGAPROX_TRUSTED_PROXIES none Comma-separated proxy IPs/CIDRs for X-Forwarded-For trust.
PEGAPROX_SERVER auto Force server backend: gevent, flask, or auto.
PEGAPROX_URL http://127.0.0.1:5000 Self-URL for VNC/SSH console WebSocket callbacks.

Correction: MAX_UPLOAD_SIZE is 100 GB (not 4 GB). API_RATE_LIMIT was increased from 600 to 1200 in Jan 2026 (600 caused spurious 429 errors on large clusters).

Directories

Variable Default Description
PEGAPROX_CONFIG_DIR config (in the install folder) Where the database, settings, TLS certificate and branding live. From 1.3.
PEGAPROX_LOG_DIR logs (in the install folder) Where the per-cluster log files are written. From 1.3.
PEGAPROX_PLUGINS_DIR plugins (in the install folder) Where the plugins are loaded from. The Docker image sets it to /app/config/plugins, in the config volume, so each plugin's settings outlast a new image. From 1.4.0, see Plugin System.

Security and service

Variable Default Description
PEGAPROX_SSH_STRICT_HOST_KEYS off Set to 1 to reject SSH hosts whose key is not already known, instead of trusting a key on first use. Also applies to the ESXi transfers that run on the Proxmox nodes.
PEGAPROX_DISABLE_AUTO_ENCRYPT off Set to 1 to keep an unencrypted database instead of converting it to an encrypted one.
PEGAPROX_PLAIN_BACKUP_RETENTION_S 3600 How long the unencrypted copy made while encrypting the database is kept, in seconds. A start after that shreds it; 0 shreds it on the next start.
PEGAPROX_KEY_FILE (unset) Path to the database key file. Checked before the default locations /etc/pegaprox/secret.key and ~/.config/pegaprox/secret.key. The file must be readable by its owner only (0600, or 0640 for the service group).
PEGAPROX_ALLOW_PLAINTEXT off When TLS is enabled but no usable certificate is found, PegaProx refuses to start. Set to 1 to serve plain HTTP on that port anyway (TLS clients then fail against it).
PEGAPROX_SUPERVISED off Set to 1 when a supervisor starts PegaProx again after it exits (for example a container restart policy). A restart, update or HA role change then exits the process instead of restarting it in place.

Timeouts and limits

Variable Default Description
PEGAPROX_HANDSHAKE_TIMEOUT 30 Seconds a client has to finish the TLS handshake.
PEGAPROX_HEADER_TIMEOUT 30 Seconds a client has to send the request headers.
PEGAPROX_BODY_TIMEOUT 30 Seconds a request that is not signed in yet has to deliver its body. Signed-in uploads (ISO and templates) take as long as they need. From 1.3.
PEGAPROX_SEND_TIMEOUT 60 Seconds a client may stall while receiving an answer.
PEGAPROX_KEEPALIVE_TIMEOUT 75 Seconds an idle keep-alive connection is kept open. 0 keeps it open indefinitely.
PEGAPROX_VNC_CONNECT_TIMEOUT 15 Seconds to wait for the Proxmox VNC proxy when a console opens. Raise it behind slow inspection middleboxes.
PEGAPROX_VMWARE_CONNECT_TIMEOUT 8 Seconds to wait when connecting to an ESXi host.
PEGAPROX_SSH_OUTPUT_MB 8 Most output (MB) PegaProx reads from one SSH command on a node.
PEGAPROX_SYSLOG_QUEUE_MB 64 Memory budget (MB) of the integrated syslog receiver's queue.
PEGAPROX_SYSLOG_TCP_MAX 1024 Most concurrent TCP connections to the syslog receiver.
PEGAPROX_METRICS_RETENTION_DAYS 30 Days of metrics history kept for reports and insights.
PEGAPROX_THREADPOOL_SIZE 50 Size of the thread pool used for DNS lookups and database reads.
PEGAPROX_NOFILE system hard limit (65536 if unlimited) Open-file limit PegaProx asks for at start.
PEGAPROX_PW_HASH_CONCURRENCY 8 How many password hashes are computed at once (sign-ins).