The Core Server's behavior is controlled by the Proxus-config.toml file. Every setting in this file can be overridden using Environment Variables, which is the preferred method for Docker deployments.
lightbulb
Variable Mapping Rule
To override a TOML key using an environment variable:
- Convert the hierarchy to UPPERCASE.
- Replace dots (
.) with underscores (_). - Example:
Security.Password.MinLength->SECURITY_PASSWORD_MINLENGTH.
Core Service Settings
Controls the [Service] section. Defines the identity and network ports for the microservices.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| Name | SERVICE_NAME | String | The instance name visible in logs/cluster. |
| UI-Port | SERVICE_UI_PORT | String | HTTP port for the Management Console. |
| UI-HTTPS-Port | SERVICE_UI_HTTPS_PORT | String | HTTPS port for the Management Console. |
| UI-Address | SERVICE_UI_ADDRESS | String | Bind address for UI (e.g., 0.0.0.0). |
| WEBApi-Port | SERVICE_WEBAPI_PORT | String | HTTP port for the REST API. |
| WEBApi-HTTPS-Port | SERVICE_WEBAPI_HTTPS_PORT | String | HTTPS port for the REST API. |
| WEBApi-Address | SERVICE_WEBAPI_ADDRESS | String | Bind address for API. |
| Server-Port | SERVICE_SERVER_PORT | String | Main gRPC port for internal comms. |
| Server-HTTPS-Port | SERVICE_SERVER_HTTPS_PORT | String | Secure gRPC port. |
| Server-Address | SERVICE_SERVER_ADDRESS | String | Bind address for Server. |
| SSL-Certificate-Name | SERVICE_SSL_CERTIFICATE_NAME | String | TLS certificate file name for HTTPS services (PFX/PKCS#12 or PEM/CRT/CER). |
| SSL-Certificate-Password | SERVICE_SSL_CERTIFICATE_PASSWORD | String | Password for the certificate or encrypted PEM key (if required). |
| SSL-Certificate-Key-Name | SERVICE_SSL_CERTIFICATE_KEY_NAME | String | Private key file name for PEM deployments (e.g., example.key). |
Databases
Proxus uses a hybrid storage model (Relational + Time-Series). Controls the [Database] and [ClickHouse] sections.
General Database Settings
Controls the [Database] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| SystemConnectionString | DATABASE_CONNECTIONSTRING | String | PostgreSQL connection string (Users, Config). |
| TelemetryConnectionString | DATABASE_TELEMETRYCONNECTIONSTRING | String | Connection string for Time-Series DB. |
| TelemetryDB | DATABASE_TELEMETRYDB | String | Deprecated. Telemetry storage uses ClickHouse. |
| InsertStrategy | DATABASE_INSERTSTRATEGY | String | Bulk (Recommended) or Single. |
| BulkInsertInterval | DATABASE_BULKINSERTINTERVAL | Int | Buffer flush interval in ms (Default: 1000). |
| MaxConcurrentInserts | DATABASE_MAXCONCURRENTINSERTS | Int | Max parallel write operations. |
| EnableDataStoreCache | DATABASE_ENABLEDATASTORECACHE | Bool | Enable Level-2 caching for system tables. |
| TablesExcludedFromCache | DATABASE_TABLESEXCLUDEDFROMCACHE | Array | Tables to never cache (e.g., Logs). |
| DeviceRawDataRetentionPolicy | DATABASE_DEVICERAWDATARETENTIONPOLICY | String | Retention policy name for raw |
| data. |
ClickHouse Tuning
Controls the [ClickHouse] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| ClickHouseHost | CLICKHOUSE_CLICKHOUSEHOST | String | Hostname of the ClickHouse server. |
| ClickHousePort | CLICKHOUSE_CLICKHOUSEPORT | Int | Native TCP port (Default: 9000). |
| ClickHouseMySqlPort | CLICKHOUSE_CLICKHOUSEMYSQLPORT | Int | MySQL emulation port (Default: 3306). |
| ClickHouseDatabase | CLICKHOUSE_CLICKHOUSEDATABASE | String | Database name (Default: default). |
| ClickHouseUsername | CLICKHOUSE_CLICKHOUSEUSERNAME | String | Auth username. |
| ClickHousePassword | CLICKHOUSE_CLICKHOUSEPASSWORD | String | Auth password. |
| ClickHouseWriteIntervalSeconds | CLICKHOUSE_CLICKHOUSEWRITEINTERVALSECONDS | Int | Batch write frequency. |
| ClickHouseTTLExpression | CLICKHOUSE_CLICKHOUSETTLEXPRESSION | String | TTL SQL expression (e.g., toIntervalMonth(3)). |
| ClickHouseLogTTLExpression | CLICKHOUSE_CLICKHOUSELOGTTLEXPRESSION | String | TTL expression for logs (e.g. INTERVAL 45 DAY). |
Messaging Backbone
Controls the [NATS] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| BrokerUrl | NATS_BROKERURL | String | Broker connection URL (e.g., nats://localhost:4222). |
| BrokerUser | NATS_BROKERUSER | String | Cluster username. |
| BrokerPassword | NATS_BROKERPASSWORD | String | Cluster password. |
Security & Authentication
Global Security
Controls the [Security] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| Lockout.Enabled | SECURITY_LOCKOUT_ENABLED | Bool | Enable account lockout on failure. |
| Lockout.MaxFailedAccessAttempts | SECURITY_LOCKOUT_MAXFAILEDACCESSATTEMPTS | Int | Max attempts before lockout. |
| Lockout.DefaultLockoutTimeSpan | SECURITY_LOCKOUT_DEFAULTLOCKOUTTIMESPAN | Int | Lockout duration in seconds. |
Password Policy
Controls the [Security.Password] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| MinLength | SECURITY_PASSWORD_MINLENGTH | Int | Minimum characters. |
| MaxLength | SECURITY_PASSWORD_MAXLENGTH | Int | Maximum characters. |
| RequireUppercase | SECURITY_PASSWORD_REQUIREUPPERCASE | Int | Count of uppercase chars required. |
| RequireLowercase | SECURITY_PASSWORD_REQUIRELOWERCASE | Int | Count of lowercase chars required. |
| RequireDigits | SECURITY_PASSWORD_REQUIREDIGITS | Int | Count of digits required. |
| RequireSpecialCharacters | SECURITY_PASSWORD_REQUIRESPECIALCHARACTERS | Int | Count of symbols required. |
| AllowedSpecialCharacters | SECURITY_PASSWORD_ALLOWEDSPECIALCHARACTERS | Array | List of valid symbols (e.g., |
!@#$%). | |||
| PasswordHistory | SECURITY_PASSWORD_PASSWORDHISTORY | Int | Number of past passwords to remember. |
| PasswordExpirationDays | SECURITY_PASSWORD_PASSWORDEXPIRATIONDAYS | Int | Days before password expires. |
| PasswordExpirationWarningDays | SECURITY_PASSWORD_PASSWORDEXPIRATIONWARNINGDAYS | Int | Days to warn before |
| expiration. | |||
| PreventCommonPasswords | SECURITY_PASSWORD_PREVENTCOMMONPASSWORDS | Bool | Block dictionary words. |
| PreventKeyboardPatterns | SECURITY_PASSWORD_PREVENTKEYBOARDPATTERNS | Bool | Block patterns like qwerty or |
12345. | |||
| PreventRepeatedCharacters | SECURITY_PASSWORD_PREVENTREPEATEDCHARACTERS | Bool | Block aaaaa. |
| MaxRepeatedCharacters | SECURITY_PASSWORD_MAXREPEATEDCHARACTERS | Int | Max consecutive repeats. |
| RequireChangeOnFirstLogin | SECURITY_PASSWORD_REQUIRECHANGEONFIRSTLOGIN | Bool | Force change for new users. |
| TempPasswordExpirationHours | SECURITY_PASSWORD_TEMPPASSWORDEXPIRATIONHOURS | Int | Validity of temp passwords (hours). |
JWT & WebAPI
Controls the [Jwt] and [WEBAPI.Authentication.Jwt] sections.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| Issuer | JWT_ISSUER | String | Token Issuer claim. |
| Audience | JWT_AUDIENCE | String | Token Audience claim. |
| Key | JWT_KEY | String | 256-bit Signing Key. |
| Issuer (API) | WEBAPI_AUTHENTICATION_JWT__0__ISSUER | String | API specific issuer. |
| Audience (API) | WEBAPI_AUTHENTICATION_JWT__0__AUDIENCE | String | API specific audience. |
| IssuerSigningKey | WEBAPI_AUTHENTICATION_JWT__0__ISSUERSIGNINGKEY | String | API specific signing key. |
| TokenExpireTime | WEBAPI_AUTHENTICATION_JWT__0__TOKENEXPIRETIME | String | Token validity duration. |
Unified Namespace
Controls the [UNS] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| UNSEnabled | UNS_UNSENABLED | Bool | Enable UNS Contextualization. |
| UNSGroupId | UNS_UNSGROUPID | String | Root Group ID (Sparkplug). |
| UNSVersion | UNS_UNSVERSION | String | UNS Specification Version. |
| UNSDefaultEnterprise | UNS_UNSDEFAULTENTERPRISE | String | Default root node name. |
| UNSDefaultSite | UNS_UNSDEFAULTSITE | String | Default site name. |
| UNSDefaultArea | UNS_UNSDEFAULTAREA | String | Default area name. |
| UNSRetainMessages | UNS_UNSRETAINMESSAGES | Bool | Set MQTT Retain flag on publish. |
| UNSUseSparkplugB | UNS_UNSUSESPARKPLUGB | Bool | Enable SparkplugB payload format. |
| UNSEdgeNodeId | UNS_UNSEDGENODEID | String | Edge Node Identifier. |
| UNSEdgeNodeUsername | UNS_UNSEDGENODEUSERNAME | String | Sparkplug connection user. |
| UNSEdgeNodePassword | UNS_UNSEDGENODEPASSWORD | String | Sparkplug connection password. |
UNS Optimizations
Controls the [UNS.Optimizations] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| TelemetryThinPayload | UNS_OPTIMIZATIONS_TELEMETRYTHINPAYLOAD | Bool | Remove "context" object from telemetry payloads. |
| SummaryIncludeContext | UNS_OPTIMIZATIONS_SUMMARYINCLUDECONTEXT | Bool | Include ISA-95 context in _summary messages. |
| SummaryIntervalMs | UNS_OPTIMIZATIONS_SUMMARYINTERVALMS | Int | Min publish interval for _summary (ms). |
| LastSeenIntervalMs | UNS_OPTIMIZATIONS_LASTSEENINTERVALMS | Int | Min publish interval for _lastSeen (ms). |
| StatusOnChangeOnly | UNS_OPTIMIZATIONS_STATUSONCHANGEONLY | Bool | Publish _status only when value changes. |
| SummaryOnlyOnChange | UNS_OPTIMIZATIONS_SUMMARYONLYONCHANGE | Bool | Publish _summary only when hash changes. |
Integrations
Controls the [MQTTBroker], [MQTTAPI], and [HttpServer] sections.
Embedded MQTT Broker
Controls the [MQTTBroker] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| Enabled | MQTTBROKER_ENABLED | Bool | Enable internal broker. |
| MQTTBrokerPort | MQTTBROKER_MQTTBROKERPORT | Int | Listening port. |
| AllowAnonymous | MQTTBROKER_ALLOWANONYMOUS | Bool | Allow auth-less connections. |
| MasterToken | MQTTBROKER_MASTERTOKEN | String | Superuser token. |
| BrokerHostAddress | MQTTBROKER_BROKERHOSTADDRESS | String | Bind address. |
| EnableMQTTHooks | MQTTBROKER_ENABLEMQTTHOOKS | Bool | Enable internal hooks. |
External MQTT Client
Controls the [MQTTAPI] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| MQTTServer | MQTTAPI_MQTTSERVER | String | External Broker Address. |
| MQTTPort | MQTTAPI_MQTTPORT | Int | External Broker Port. |
| MQTTUser | MQTTAPI_MQTTUSER | String | Username. |
| MQTTPassword | MQTTAPI_MQTTPASSWORD | String | Password. |
| MQTTVersion | MQTTAPI_MQTTVERSION | String | Protocol Version (3.1.1, 5.0). |
| MQTTConnectionTimeOut | MQTTAPI_MQTTCONNECTIONTIMEOUT | Int | Connection timeout (ms). |
| MQTTKeepAlivePeriod | MQTTAPI_MQTTKEEPALIVEPERIOD | Int | Keep Alive (sec). |
| MQTTCleanSession | MQTTAPI_MQTTCLEANSESSION | Bool | Clean Session flag. |
| MQTTQos | MQTTAPI_MQTTQOS | Int | Default QoS (0, 1, 2). |
| MQTTRetain | MQTTAPI_MQTTRETAIN | Bool | Default Retain flag. |
HTTP Server
Controls the [HttpServer] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| Enabled | HTTPSERVER_ENABLED | Bool | Enable HTTP Ingestion endpoint. |
| Port | HTTPSERVER_PORT | Int | Listening port. |
| MaxConcurrentConnections | HTTPSERVER_MAXCONCURRENTCONNECTIONS | Int | Max connections. |
| MaxRequestBodySize | HTTPSERVER_MAXREQUESTBODYSIZE | Long | Max payload size in bytes. |
| KeepAliveTimeout | HTTPSERVER_KEEPALIVETIMEOUT | Int | Keep-alive timeout. |
| MaxKeepAliveRequests | HTTPSERVER_MAXKEEPALIVEREQUESTS | Int | Max requests per connection. |
| RequestHeadersTimeout | HTTPSERVER_REQUESTHEADERSTIMEOUT | Int | Header read timeout. |
| EnableHttps | HTTPSERVER_ENABLEHTTPS | Bool | Enable TLS. |
| SslCertificatePath | HTTPSERVER_SSLCERTIFICATEPATH | String | Path to PFX/PKCS#12 certificate. |
| SslCertificatePassword | HTTPSERVER_SSLCERTIFICATEPASSWORD | String | Certificate password. |
| RateLimitPermitLimit | HTTPSERVER_RATELIMITPERMITLIMIT | Int | Requests per window. |
| RateLimitWindowSeconds | HTTPSERVER_RATELIMITWINDOWSECONDS | Int | Rate limit window size. |
| EnableCompression | HTTPSERVER_ENABLECOMPRESSION | Bool | Enable GZIP/Brotli. |
Cluster & Actors
Controls the [Cluster] and [ProtoActor] sections.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| GrpcInterfaceBinding | CLUSTER_GRPCINTERFACEBINDING | String | IP to bind for cluster traffic. |
| ClusterProvider | CLUSTER_CLUSTERPROVIDER | String | Provider type (e.g. Kubernetes, Consul). |
| IdentityLookupStrategy | CLUSTER_IDENTITYLOOKUPSTRATEGY | String | Strategy for finding actors. |
| HeartbeatExpiration | CLUSTER_HEARTBEATEXPIRATION | Int | Cluster heartbeat timeout. |
| ActorRequestTimeout | CLUSTER_ACTORREQUESTTIMEOUT | Int | Default timeout for actor calls. |
| ActorActivationTimeout | CLUSTER_ACTORACTIVATIONTIMEOUT | Int | Timeout for spawning actors. |
| GossipRequestTimeout | CLUSTER_GOSSIPREQUESTTIMEOUT | Int | Gossip protocol timeout. |
| DeveloperLogging | PROTOACTOR_DEVELOPERLOGGING | Bool | Verbose actor logging. |
| SubscribersStorageType | PROTOACTOR_PUBSUB_SUBSCRIBERSSTORAGETYPE | String | PubSub backend (Redis, |
InMemory). | |||
| RedisConnectionString | PROTOACTOR_PUBSUB_REDISCONNECTIONSTRING | String | Redis connection string. |
| RedisMaxConcurrency | PROTOACTOR_PUBSUB_REDISMAXCONCURRENCY | Int | Redis concurrency limit. |
User Functions
Controls the [UserFunctions] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| ExceptionThresholdPerFunction | USERFUNCTIONS_EXCEPTIONTHRESHOLDPERFUNCTION | Int | Max crashes before undeploy |
| (Default: 10). | |||
| UseAutoDisposeInjector | USERFUNCTIONS_USEAUTODISPOSEINJECTOR | Bool | Auto-inject Dispose calls. |
| UseAutoTryCatchInjector | USERFUNCTIONS_USEAUTOTRYCATCHINJECTOR | Bool | Auto-inject Try/Catch blocks. |
| LogProxusCompilerGeneratedCode | USERFUNCTIONS_LOGPROXUSCOMPILERGENERATEDCODE | Bool | Debug generated C# code. |
| LogLevelPolicy | USERFUNCTIONS_LOGLEVELPOLICY | Array | Log rate limits (e.g., Error: 10 1h). |
Observability & Maintenance
Logging & Tracing
Controls the [Logging], [Tracing], [Metrics], and [Otlp] sections.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| Loglevel | LOGGING_LOGLEVEL | Int | 0=Trace, 1=Debug, 2=Info, ... |
| LogRetentionTime | LOGGING_LOGRETENTIONTIME | Int | Retention days for text logs. |
| LogToFile | LOGGING_LOGTOFILE | Bool | Write logs to disk. |
| LogSqlQueries | LOGGING_LOGSQLQUERIES | Bool | Log generated SQL (Verbose!). |
| Enable (Tracing) | TRACING_ENABLE | Bool | Enable OpenTelemetry Tracing. |
| Enable (Metrics) | METRICS_ENABLE | Bool | Enable OpenTelemetry Metrics. |
| Prometheus | METRICS_PROMETHEUS | Bool | Expose /metrics endpoint. |
| Endpoint (OTLP) | OTLP_ENDPOINT | String | OTLP Collector URL. |
| MetricsIntervalMilliseconds | OTLP_METRICSINTERVALMILLISECONDS | Int | Export interval. |
Data Settings
Controls the [Data] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| MaxDeviceDataLoad | DATA_MAXDEVICEDATALOAD | Int | Max records to fetch for UI charts. |
| DeviceDataTimeRange | DATA_DEVICEDATATIMERANGE | String | Default UI time range. |
| LogsTimeRange | DATA_LOGSTIMERANGE | String | Default Logs time range (e.g. "1d"). |
| DeviceMetricsTransmissionInterval | DATA_DEVICEMETRICSTRANSMISSIONINTERVAL | Int | Health metrics push interval. |
Miscellaneous
Edge Gateway
Controls the [EdgeGateway] section.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| EdgeMode | EDGEGATEWAY_EDGEMODE | String | Proxus (Core) or Edge (Agent). |
| Integration | EDGEGATEWAY_INTEGRATION | String | Integration mode. |
| GatewayName | EDGEGATEWAY_GATEWAYNAME | String | Logical name of the gateway. |
| GatewayID | EDGEGATEWAY_GATEWAYID | String | Numeric ID (Core is always 1). |
| EdgeMetricsTransmissionInterval | EDGEGATEWAY_EDGEMETRICSTRANSMISSIONINTERVAL | Int | Edge health push interval. |
UI & Themes
Controls the [UI] and [DevExpress...] sections.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| ForceSkiaRendering | UI_FORCESKIARENDERING | Bool | Force SkiaSharp for charts. |
| EnableDashboardExportRestrictedMode | UI_ENABLEDASHBOARDEXPORTRESTRICTEDMODE | Bool | Restrict export formats. |
| Languages | DEVEXPRESS_EXPRESSAPP_LANGUAGES | String | Supported UI languages. |
| ShowLanguageSwitcher | DEVEXPRESS_EXPRESSAPP_SHOWLANGUAGESWITCHER | Bool | Show/Hide language menu. |
| DefaultItemName | DEVEXPRESS_EXPRESSAPP_THEMESWITCHER_DEFAULTITEMNAME | String | Default Theme (e.g. Purple). |
| ShowSizeModeSwitcher | DEVEXPRESS_EXPRESSAPP_THEMESWITCHER_SHOWSIZEMODESWITCHER | Bool | Show Compact/Touch |
| toggle. |
Model Context Protocol
Controls the [MCP] section. AI Agent interface and security permissions.
| TOML Key | Environment Variable | Type | Description |
|---|---|---|---|
| Enabled | MCP_ENABLED | Bool | Enable MCP server functionality. |
| AllowedMethods | MCP_ALLOWEDMETHODS | String | Allowed HTTP verbs (e.g. "GET,POST"). |
| BlockDelete | MCP_BLOCKDELETE | Bool | Block all DELETE operations regardless of user permissions. |
| BlockBulkOperations | MCP_BLOCKBULKOPERATIONS | Bool | Prevent modification of multiple entities in one request. |
| AdminOnly | MCP_ADMINONLY | Bool | Restrict access to Administrators group only. |
| RateLimitEnabled | MCP_RATELIMITENABLED | Bool | Enable request rate limiting. |
| RateLimitRequestsPerMinute | MCP_RATELIMITREQUESTSPERMINUTE | Int | Max requests per user/minute. |
| AuditLogging | MCP_AUDITLOGGING | Bool | Log all operations to audit trail. |
| IPWhitelist | MCP_IPWHITELIST | Array | Allowed IP addresses/CIDR blocks. Empty = Allow All. |
| MaxConcurrentSessionsPerUser | MCP_MAXCONCURRENTSESSIONSPERUSER | Int | Max active sessions (0 = Unlimited). |
| AlertOnSuspiciousActivity | MCP_ALERTONSUSPICIOUSACTIVITY | Bool | Trigger alerts on anomaly detection. |
| DebugLogging | MCP_DEBUGLOGGING | Bool | Verbose console logging for diagnostics. |
Host Environment
| Variable Name | Description |
|---|---|
| DYLD_FALLBACK_LIBRARY_PATH | System library path override (Crucial for macOS/Linux native interop). |
| DEVELOPMENT_ALLOWEDHOSTS | Comma-separated list of allowed host headers. |
| CULTURE_NAME | Force .NET Culture (e.g. tr-TR). |
| KESTREL_ENDPOINTDEFAULTS_PROTOCOLS | HTTP Protocol versions (Http1, Http2). |