Skip to main content

General

Configuration File Reference

Complete reference for 'Proxus-config.toml' keys and their environment variable overrides.

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 and Kubernetes deployments.

lightbulb
Variable Mapping Rule

To override a TOML key with an environment variable:

  1. Use the TOML section name and key, joined with a double underscore (__).
  2. Preserve the original casing from the TOML file.
  3. For nested sections, separate every level with __.
  4. Examples:
    • [NATS] BrokerUrl → NATS__BrokerUrl
    • [Database] ConnectionString → Database__ConnectionString
    • [Security.Password] MinLength → Security__Password__MinLength
    • [[WEBAPI.Authentication.Jwt]] first entry's Issuer → WEBAPI__Authentication__Jwt__0__Issuer

The double underscore is the .NET convention for the configuration hierarchy separator (:), because POSIX shells do not accept : in environment variable names.

Notation Notes

  • Empty value still wins. NATS__BrokerUrl="" overrides the TOML value with an empty string. To fall back to the TOML value, remove the variable entirely instead of setting it to "".
  • TOML keys with hyphens. Some keys (for example Service__UI-Port) contain hyphens. POSIX shells reject hyphens in export X=Y syntax, so these names work only inside Docker Compose environment: lists, Kubernetes manifest env: arrays, or via inline env "Service__UI-Port=8080" ./Proxus.Server.
  • Array sections. TOML [[Section.Sub]] arrays are indexed numerically. The first entry's Key becomes Section__Sub__0__Key, the second Section__Sub__1__Key, and so on.
  • Command-line still wins. Startup arguments such as ./Proxus.Server --GatewayID=1 override both environment variables and TOML.

Core Service Settings

Controls the [Service] section. Defines the identity and network ports for the microservices.

TOML KeyEnvironment VariableTypeDescription
NameService__NameStringThe instance name visible in logs/cluster.
UI-PortService__UI-PortStringHTTP port for the Management Console.
UI-HTTPS-PortService__UI-HTTPS-PortStringHTTPS port for the Management Console.
UI-AddressService__UI-AddressStringBind address for UI (e.g., 0.0.0.0).
WEBApi-PortService__WEBApi-PortStringHTTP port for the REST API.
WEBApi-HTTPS-PortService__WEBApi-HTTPS-PortStringHTTPS port for the REST API.
WEBApi-AddressService__WEBApi-AddressStringBind address for API.
Server-PortService__Server-PortStringMain gRPC port for internal comms.
Server-HTTPS-PortService__Server-HTTPS-PortStringSecure gRPC port.
Server-AddressService__Server-AddressStringBind address for Server.
Certificate source-UI-managedHTTPS certificates are selected in Administration → Certificate Store. Proxus-config.toml now defines ports, while certificate material is managed from the UI.

Databases

Proxus uses a hybrid storage model (Relational + Time-Series). Controls the [Database] and [ClickHouse] sections.

General Database Settings

Controls the [Database] section.

TOML KeyEnvironment VariableTypeDescription
ConnectionStringDatabase__ConnectionStringStringPostgreSQL connection string (Users, Config).
TelemetryDBDatabase__TelemetryDBStringTelemetry backend: clickhouse or timescale.
InsertStrategyDatabase__InsertStrategyStringBulk (Recommended) or Single.
BulkInsertIntervalDatabase__BulkInsertIntervalIntBuffer flush interval in ms (Default: 1000).
MaxConcurrentInsertsDatabase__MaxConcurrentInsertsIntMax parallel write operations.
EnableDataStoreCacheDatabase__EnableDataStoreCacheBoolEnable Level-2 caching for system tables.
TablesExcludedFromCacheDatabase__TablesExcludedFromCache__0, …__1, …ArrayTables to never cache. Each array entry is set with its index (e.g., Database__TablesExcludedFromCache__0=Log).
DeviceRawDataRetentionPolicyDatabase__DeviceRawDataRetentionPolicyStringRetention period for raw data (e.g., 7d, 1y). 0s = disabled.

ClickHouse Tuning

Controls the [ClickHouse] section.

TOML KeyEnvironment VariableTypeDescription
ClickHouseHostClickHouse__ClickHouseHostStringHostname of the ClickHouse server.
ClickHousePortClickHouse__ClickHousePortIntHTTP interface port (Default: 8123).
ClickHouseMySqlPortClickHouse__ClickHouseMySqlPortIntMySQL wire-protocol port (Default: 9004).
ClickHouseDatabaseClickHouse__ClickHouseDatabaseStringDatabase name (Default: proxus).
ClickHouseUsernameClickHouse__ClickHouseUsernameStringAuth username.
ClickHousePasswordClickHouse__ClickHousePasswordStringAuth password.
ClickHouseWriteIntervalSecondsClickHouse__ClickHouseWriteIntervalSecondsIntBatch write frequency.
ClickHouseTTLExpressionClickHouse__ClickHouseTTLExpressionStringTTL SQL expression (e.g., toIntervalMonth(3)).
ClickHouseLogTTLExpressionClickHouse__ClickHouseLogTTLExpressionStringTTL expression for logs (e.g. INTERVAL 45 DAY).

[NATS]

Controls the [NATS] section.

TOML KeyEnvironment VariableTypeDescription
BrokerUrlNATS__BrokerUrlStringBroker connection URL (e.g., nats://localhost:4222).
BrokerUserNATS__BrokerUserStringCluster username.
BrokerPasswordNATS__BrokerPasswordStringCluster password.

Security & Authentication

Global Security

Controls the [Security] section.

TOML KeyEnvironment VariableTypeDescription
Lockout.EnabledSecurity__Lockout__EnabledBoolEnable account lockout on failure.
Lockout.MaxFailedAccessAttemptsSecurity__Lockout__MaxFailedAccessAttemptsIntMax attempts before lockout.
Lockout.DefaultLockoutTimeSpanSecurity__Lockout__DefaultLockoutTimeSpanIntLockout duration in seconds.

Password Policy

Controls the [Security.Password] section.

TOML KeyEnvironment VariableTypeDescription
MinLengthSecurity__Password__MinLengthIntMinimum characters.
MaxLengthSecurity__Password__MaxLengthIntMaximum characters.
RequireUppercaseSecurity__Password__RequireUppercaseIntCount of uppercase chars required.
RequireLowercaseSecurity__Password__RequireLowercaseIntCount of lowercase chars required.
RequireDigitsSecurity__Password__RequireDigitsIntCount of digits required.
RequireSpecialCharactersSecurity__Password__RequireSpecialCharactersIntCount of symbols required.
AllowedSpecialCharactersSecurity__Password__AllowedSpecialCharactersStringList of valid symbols (e.g., !@#$%).
PasswordHistorySecurity__Password__PasswordHistoryIntNumber of past passwords to remember.
PasswordExpirationDaysSecurity__Password__PasswordExpirationDaysIntDays before password expires.
PasswordExpirationWarningDaysSecurity__Password__PasswordExpirationWarningDaysIntDays to warn before expiration.
PreventCommonPasswordsSecurity__Password__PreventCommonPasswordsBoolBlock dictionary words.
PreventKeyboardPatternsSecurity__Password__PreventKeyboardPatternsBoolBlock patterns like qwerty or 12345.
PreventRepeatedCharactersSecurity__Password__PreventRepeatedCharactersBoolBlock aaaaa.
MaxRepeatedCharactersSecurity__Password__MaxRepeatedCharactersIntMax consecutive repeats.
RequireChangeOnFirstLoginSecurity__Password__RequireChangeOnFirstLoginBoolForce change for new users.
TempPasswordExpirationHoursSecurity__Password__TempPasswordExpirationHoursIntValidity of temp passwords (hours).

JWT & WebAPI

Controls the [Jwt] and [[WEBAPI.Authentication.Jwt]] sections. The latter is a TOML array of tables, so the first entry uses index 0.

TOML KeyEnvironment VariableTypeDescription
IssuerJwt__IssuerStringToken Issuer claim.
AudienceJwt__AudienceStringToken Audience claim.
KeyJwt__KeyString256-bit Signing Key.
Issuer (API)WEBAPI__Authentication__Jwt__0__IssuerStringAPI specific issuer.
Audience (API)WEBAPI__Authentication__Jwt__0__AudienceStringAPI specific audience.
IssuerSigningKeyWEBAPI__Authentication__Jwt__0__IssuerSigningKeyStringAPI specific signing key.
TokenExpireTimeWEBAPI__Authentication__Jwt__0__TokenExpireTimeStringToken validity duration.

Unified Namespace

Controls the [UNS] section.

TOML KeyEnvironment VariableTypeDescription
UNSVersionUNS__UNSVersionStringTopic version prefix for UNS paths (default: v1).
UNSPayloadFormatUNS__UNSPayloadFormatStringPayload format: JSON (default) or SparkplugB.
UNSGroupIdUNS__UNSGroupIdStringSparkplugB Group ID (used when format is SparkplugB).
UNSEdgeNodeIdUNS__UNSEdgeNodeIdStringSparkplugB Edge Node Identifier.
UNSRetainMessagesUNS__UNSRetainMessagesBoolSet MQTT Retain flag on publish.
QoS:TelemetryUNS__QoS__TelemetryStringQoS for telemetry publish (0, 1, 2; default: 0).
QoS:StateUNS__QoS__StateStringQoS for state publish (0, 1, 2; default: 1).
QoS:CommandUNS__QoS__CommandStringQoS for command publish (0, 1, 2; default: 1).

UNS Optimizations

Controls the [UNS.Optimizations] section.

TOML KeyEnvironment VariableTypeDescription
TelemetryThinPayloadUNS__Optimizations__TelemetryThinPayloadBoolRemove "context" object from telemetry payloads.
SummaryIncludeContextUNS__Optimizations__SummaryIncludeContextBoolInclude ISA-95 context in _summary messages.
SummaryIntervalMsUNS__Optimizations__SummaryIntervalMsIntMin publish interval for _summary (ms).
LastSeenIntervalMsUNS__Optimizations__LastSeenIntervalMsIntMin publish interval for _lastSeen (ms).
StatusOnChangeOnlyUNS__Optimizations__StatusOnChangeOnlyBoolPublish _status only when value changes.
SummaryOnlyOnChangeUNS__Optimizations__SummaryOnlyOnChangeBoolPublish _summary only when hash changes.

Fieldbus

Controls the [Fieldbus] section.

TOML KeyEnvironment VariableTypeDescription
UseBatchReadForSupportedProtocolsFieldbus__UseBatchReadForSupportedProtocolsBoolEnable batch reading for supported protocols to reduce network traffic.

Browse

Controls the [Browse] section.

TOML KeyEnvironment VariableTypeDescription
UseEdgeRemoteBrowseBrowse__UseEdgeRemoteBrowseBoolForce hub UI to use edge request/reply browse flow.

Integrations

Controls the [MQTTBroker], [MQTTAPI], and [HttpServer] sections.

Embedded MQTT Broker

Controls the [MQTTBroker] section.

TOML KeyEnvironment VariableTypeDescription
EnabledMQTTBroker__EnabledBoolEnable internal broker.
MQTTBrokerPortMQTTBroker__MQTTBrokerPortIntListening port.
AllowAnonymousMQTTBroker__AllowAnonymousBoolAllow auth-less connections.
MasterTokenMQTTBroker__MasterTokenStringSuperuser token.
BrokerHostAddressMQTTBroker__BrokerHostAddressStringBind address.
EnableMQTTHooksMQTTBroker__EnableMQTTHooksBoolEnable internal hooks.

External MQTT Client

Controls the [MQTTAPI] section.

TOML KeyEnvironment VariableTypeDescription
MQTTServerMQTTAPI__MQTTServerStringExternal Broker Address.
MQTTPortMQTTAPI__MQTTPortIntExternal Broker Port.
MQTTUserMQTTAPI__MQTTUserStringUsername.
MQTTPasswordMQTTAPI__MQTTPasswordStringPassword.
MQTTVersionMQTTAPI__MQTTVersionStringProtocol Version (V310 or V500).
MQTTConnectionTimeOutMQTTAPI__MQTTConnectionTimeOutIntConnection timeout (seconds).
MQTTKeepAlivePeriodMQTTAPI__MQTTKeepAlivePeriodIntKeep Alive (sec).
MQTTCleanSessionMQTTAPI__MQTTCleanSessionBoolClean Session flag.
MQTTQosMQTTAPI__MQTTQosIntDefault QoS (0, 1, 2).
MQTTRetainMQTTAPI__MQTTRetainBoolDefault Retain flag.

HTTP Server

Controls the [HttpServer] section.

TOML KeyEnvironment VariableTypeDescription
EnabledHttpServer__EnabledBoolEnable HTTP Ingestion endpoint.
PortHttpServer__PortIntListening port.
MaxConcurrentConnectionsHttpServer__MaxConcurrentConnectionsIntMax connections.
MaxRequestBodySizeHttpServer__MaxRequestBodySizeLongMax payload size in bytes.
KeepAliveTimeoutHttpServer__KeepAliveTimeoutIntKeep-alive timeout.
MaxKeepAliveRequestsHttpServer__MaxKeepAliveRequestsIntMax requests per connection.
RequestHeadersTimeoutHttpServer__RequestHeadersTimeoutIntHeader read timeout.
EnableHttpsHttpServer__EnableHttpsBoolEnable TLS.
SslCertificateThumbprintHttpServer__SslCertificateThumbprintStringOptional reference to a certificate stored in the Certificate Store. Leave empty to use the default platform certificate.
RateLimitPermitLimitHttpServer__RateLimitPermitLimitIntRequests per window.
RateLimitWindowSecondsHttpServer__RateLimitWindowSecondsIntRate limit window size.
EnableCompressionHttpServer__EnableCompressionBoolEnable GZIP/Brotli.

Actors

TOML KeyEnvironment VariableTypeDescription
DeveloperLoggingProtoActor__DeveloperLoggingBoolVerbose actor logging.
SubscribersStorageTypeProtoActor__PubSub__SubscribersStorageTypeStringPubSub backend (Redis, InMemory).
RedisConnectionStringProtoActor__PubSub__RedisConnectionStringStringRedis connection string.
RedisMaxConcurrencyProtoActor__PubSub__RedisMaxConcurrencyIntRedis concurrency limit.

User Functions

Controls the [UserFunctions] section.

TOML KeyEnvironment VariableTypeDescription
ExceptionThresholdPerFunctionUserFunctions__ExceptionThresholdPerFunctionIntMax crashes before undeploy (Default: 10).
UseAutoDisposeInjectorUserFunctions__UseAutoDisposeInjectorBoolAuto-inject Dispose calls.
UseAutoTryCatchInjectorUserFunctions__UseAutoTryCatchInjectorBoolAuto-inject Try/Catch blocks.
LogProxusCompilerGeneratedCodeUserFunctions__LogProxusCompilerGeneratedCodeBoolDebug generated C# code.
LogLevelPolicyUserFunctions__LogLevelPolicy__0, …__1, …ArrayLog rate limits (e.g., Error:20 1m). Each policy entry uses its index.

Observability & Maintenance

Logging & Tracing

Controls the [Logging], [Tracing], [Metrics], and [Otlp] sections.

TOML KeyEnvironment VariableTypeDescription
LoglevelLogging__LoglevelInt0=Trace, 1=Debug, 2=Info, ...
LogRetentionTimeLogging__LogRetentionTimeIntRetention days for database logs.
LogToFileLogging__LogToFileBoolWrite logs to disk.
LogSqlQueriesLogging__LogSqlQueriesBoolLog generated SQL (Verbose!).
Enable (Tracing)Tracing__EnableBoolEnable OpenTelemetry Tracing.
Enable (Metrics)Metrics__EnableBoolEnable OpenTelemetry Metrics.
Endpoint (OTLP)Otlp__EndpointStringOTLP Collector URL.
MetricsIntervalMillisecondsOtlp__MetricsIntervalMillisecondsIntExport interval.

Data Settings

Controls the [Data] section.

TOML KeyEnvironment VariableTypeDescription
MaxDeviceDataLoadData__MaxDeviceDataLoadIntMax records to fetch for UI charts.
DeviceDataTimeRangeData__DeviceDataTimeRangeStringDefault UI time range.
LogsTimeRangeData__LogsTimeRangeStringDefault Logs time range (e.g. "1d").
DeviceMetricsTransmissionIntervalData__DeviceMetricsTransmissionIntervalIntHealth metrics push interval.

Miscellaneous

Edge Gateway

Controls the [EdgeGateway] section.

TOML KeyEnvironment VariableTypeDescription
EdgeModeEdgeGateway__EdgeModeStringProxus (Core) or Standalone (Agent).
IntegrationEdgeGateway__IntegrationStringIntegration mode.
GatewayNameEdgeGateway__GatewayNameStringLogical name of the gateway.
GatewayIDEdgeGateway__GatewayIDStringNumeric ID (Core is always 1).
EdgeMetricsTransmissionIntervalEdgeGateway__EdgeMetricsTransmissionIntervalIntEdge health push interval.

[UI]

Controls the [UI] section.

TOML KeyEnvironment VariableTypeDescription
ForceSkiaRenderingUI__ForceSkiaRenderingBoolForce Skia rendering for charts.
EnableDashboardExportRestrictedModeUI__EnableDashboardExportRestrictedModeBoolRestrict export formats.
EnableDashboardCustomPaletteUI__EnableDashboardCustomPalette__0, …__1, …ArrayCustom HEX color palette for dashboard charts (e.g., UI__EnableDashboardCustomPalette__0=#3dbb8b).

[DevExpress.ExpressApp]

Controls the [DevExpress.ExpressApp] section.

TOML KeyEnvironment VariableTypeDescription
LanguagesDevExpress__ExpressApp__LanguagesStringSupported UI languages.
ShowLanguageSwitcherDevExpress__ExpressApp__ShowLanguageSwitcherBoolShow or hide the language menu.

[DevExpress.ExpressApp.ThemeSwitcher]

Controls the [DevExpress.ExpressApp.ThemeSwitcher] section.

TOML KeyEnvironment VariableTypeDescription
DefaultItemNameDevExpress__ExpressApp__ThemeSwitcher__DefaultItemNameStringDefault theme.
ShowSizeModeSwitcherDevExpress__ExpressApp__ThemeSwitcher__ShowSizeModeSwitcherBoolShow the compact/touch toggle.

Model Context Protocol

Controls the [MCP] section. AI Agent interface and security permissions.

TOML KeyEnvironment VariableTypeDescription
EnabledMCP__EnabledBoolEnable MCP server functionality.
AllowedMethodsMCP__AllowedMethodsStringAllowed HTTP verbs (e.g. "GET,POST").
BlockDeleteMCP__BlockDeleteBoolBlock all DELETE operations regardless of user permissions.
BlockBulkOperationsMCP__BlockBulkOperationsBoolPrevent modification of multiple entities in one request.
AdminOnlyMCP__AdminOnlyBoolRestrict access to Administrators group only.
RateLimitEnabledMCP__RateLimitEnabledBoolEnable request rate limiting.
RateLimitRequestsPerMinuteMCP__RateLimitRequestsPerMinuteIntMax requests per user/minute.
AuditLoggingMCP__AuditLoggingBoolLog all operations to audit trail.
IPWhitelistMCP__IPWhitelist__0, …__1, …ArrayAllowed IP addresses/CIDR blocks. Empty = Allow All.
MaxConcurrentSessionsPerUserMCP__MaxConcurrentSessionsPerUserIntMax active sessions (0 = Unlimited).
AlertOnSuspiciousActivityMCP__AlertOnSuspiciousActivityBoolTrigger alerts on anomaly detection.
DebugLoggingMCP__DebugLoggingBoolVerbose console logging for diagnostics.

Top-Level Configuration

Controls top-level TOML sections that hold a single key.

TOML KeyEnvironment VariableTypeDescription
[Development] AllowedHostsDevelopment__AllowedHostsStringComma-separated list of allowed host headers.
[Culture] NameCulture__NameStringForce .NET Culture (e.g. tr-TR).
[Kestrel.EndpointDefaults] ProtocolsKestrel__EndpointDefaults__ProtocolsStringHTTP Protocol versions (e.g. Http1AndHttp2, Http2).

Host Environment

These are real OS environment variables consumed by the .NET runtime, not Proxus configuration entries. They are listed here for completeness.

Variable NameDescription
DYLD_FALLBACK_LIBRARY_PATHSystem library path override (Crucial for macOS/Linux native interop).
ASPNETCORE_ENVIRONMENTASP.NET Core hosting environment (e.g. Production, Development).
← Previous
White Labeling
Next →
System Logs