UnrealEngine/Engine/Source/Programs/Horde/Docs/Deployment/ServerSettings.md

Horde > Deployment > Server > Server.json

Server.json

All Horde-specific settings are stored in a root object called Horde. Other .NET functionality may be configured using properties in the root of this file.

Name	Description
runModes	RunMode[] Modes that the server should run in. Runmodes can be used in a multi-server deployment to limit the operations that a particular instance will try to perform.
dataDir	string Override the data directory used by Horde. Defaults to C:\ProgramData\HordeServer on Windows, {AppDir}/Data on other platforms.
installed	boolean Whether the server is running in 'installed' mode. In this mode, on Windows, the default data directory will use the common application data folder (C:\ProgramData\Epic\Horde), and configuration data will be read from here and the registry. This setting is overridden to false for local builds from appsettings.Local.json.
httpPort	integer Main port for serving HTTP.
httpsPort	integer Port for serving HTTP with TLS enabled. Disabled by default.
http2Port	integer Dedicated port for serving only HTTP/2.
mongoConnectionString	string Connection string for the Mongo database
databaseConnectionString	string MongoDB connection string
mongoDatabaseName	string MongoDB database name
databaseName	string
mongoPublicCertificate	string Optional certificate to trust in order to access the database (eg. AWS public cert for TLS)
databasePublicCert	string
mongoReadOnlyMode	boolean Access the database in read-only mode (avoids creating indices or updating content) Useful for debugging a local instance of HordeServer against a production database.
databaseReadOnlyMode	boolean
mongoMigrationsEnabled	boolean Whether database schema migrations are enabled
mongoMigrationsAutoUpgrade	boolean Whether database schema should automatically be applied Only recommended for dev or test environments
shutdownMemoryThreshold	integer Shutdown the current server process if memory usage reaches this threshold (specified in MB) Usually set to 80-90% of available memory to avoid CLR heap using all of it. If a memory leak was to occur, it's usually better to restart the process rather than to let the GC work harder and harder trying to recoup memory. Should only be used when multiple server processes are running behind a load balancer and one can be safely restarted automatically by the underlying process handler (Docker, Kubernetes, AWS ECS, Supervisor etc). The shutdown behaves similar to receiving a SIGTERM and will wait for outstanding requests to finish.
serverPrivateCert	string Optional PFX certificate to use for encrypting agent SSL traffic. This can be a self-signed certificate, as long as it's trusted by agents.
authMethod	AuthMethod Type of authentication (e.g anonymous, OIDC, built-in Horde accounts) If "Horde" auth mode is used, be sure to configure "ServerUrl" as well.
oidcProfileName	string Optional profile name to report through the /api/v1/server/auth endpoint. Allows sharing auth tokens between providers configured through the same profile name in OidcToken.exe config files.
oidcAuthority	string OpenID Connect (OIDC) authority URL (required when OIDC is enabled)
oidcAudience	string Audience for validating externally issued tokens (required when OIDC is enabled)
oidcClientId	string Client ID for the OIDC authority (required when OIDC is enabled)
oidcClientSecret	string Client secret for authenticating with the OIDC provider. Note: If you need authentication support in Unreal Build Tool or Unreal Game Sync, configure your OIDC client as a public client (using PKCE flow without a client secret) instead of a confidential client. These tools utilize the EpicGames.OIDC library which only supports public clients with authorization code flow + PKCE.
oidcSigninRedirect	string Optional redirect url provided to OIDC login
oidcLocalRedirectUrls	string[] Optional redirect url provided to OIDC login for external tools (typically to a local server) Default value is the local web server started during signin by EpicGames.OIDC library
oidcDebugMode	boolean Debug mode for OIDC which logs reasons for why JWT tokens fail to authenticate Also turns off HTTPS requirement for OIDC metadata fetching. NOT FOR PRODUCTION USE!
oidcRequestedScopes	string[] OpenID Connect scopes to request when signing in
oidcClaimNameMapping	string[] List of fields in /userinfo endpoint to try map to the standard name claim (see System.Security.Claims.ClaimTypes.Name)
oidcClaimEmailMapping	string[] List of fields in /userinfo endpoint to try map to the standard email claim (see System.Security.Claims.ClaimTypes.Email)
oidcClaimHordeUserMapping	string[] List of fields in /userinfo endpoint to try map to the Horde user claim (see HordeClaimTypes.User)
oidcClaimHordePerforceUserMapping	string[] List of fields in /userinfo endpoint to try map to the Horde Perforce user claim (see HordeClaimTypes.PerforceUser)
oidcApiRequestedScopes	string[] API scopes to request when acquiring OIDC access tokens
oidcAddDefaultScopesAndMappings	boolean Add common scopes and mappings to above OIDC config fields Provided as a workaround since .NET config will only merge array entries when combining multiple config sources. Due to this unwanted behavior, having hard-coded defaults makes such fields unchangeable. See https://github.com/dotnet/runtime/issues/36569
serverUrl	string Base URL this Horde server is accessible from For example https://horde.mystudio.com. If not set, a default is used based on current hostname. It's important this URL matches where users and agents access the server as it's used for signing auth tokens etc. Must be configured manually when running behind a reverse proxy or load balancer
jwtIssuer	string Name of the issuer in bearer tokens from the server
jwtExpiryTimeHours	integer Length of time before JWT tokens expire, in hours
adminClaimType	string The claim type for administrators
adminClaimValue	string Value of the claim type for administrators
corsEnabled	boolean Whether to enable Cors, generally for development purposes
corsOrigin	string Allowed Cors origin
enableDebugEndpoints	boolean Whether to enable debug/administrative REST API endpoints
enableNewAgentsByDefault	boolean Whether to automatically enable new agents by default. If false, new agents must manually be enabled before they can take on work.
schedulePollingInterval	string Interval between rebuilding the schedule queue with a DB query.
noResourceBackOffTime	string Interval between polling for new jobs
initiateJobBackOffTime	string Interval between attempting to assign agents to take on jobs
unknownErrorBackOffTime	string Interval between scheduling jobs when an unknown error occurs
redisConnectionString	string Config for connecting to Redis server(s). Setting it to null will disable Redis use and connection See format at https://stackexchange.github.io/StackExchange.Redis/Configuration.html
redisConnectionConfig	string
redisReadOnlyMode	boolean Whether to disable writes to Redis.
logServiceWriteCacheType	string Overridden settings for storage backends. Useful for running against a production server with custom backends.
logJsonToStdOut	boolean Whether to log json to stdout
logSessionRequests	boolean Whether to log requests to the UpdateSession and QueryServerState RPC endpoints
scheduleTimeZone	string Timezone for evaluating schedules
dashboardUrl	string The URl to use for generating links back to the dashboard.
helpEmailAddress	string Help email address that users can contact with issues
helpSlackChannel	string Help slack channel that users can use for issues
globalThreadPoolMinSize	integer Set the minimum size of the global thread pool This value has been found in need of tweaking to avoid timeouts with the Redis client during bursts of traffic. Default is 16 for .NET Core CLR. The correct value is dependent on the traffic the Horde Server is receiving. For Epic's internal deployment, this is set to 40.
withDatadog	boolean Whether to enable Datadog integration for tracing
configPath	string Path to the root config file. Relative to the server.json file by default.
forceConfigUpdateOnStartup	boolean Forces configuration data to be read and updated as part of appplication startup, rather than on a schedule. Useful when running locally.
openBrowser	boolean Whether to open a browser on startup
featureFlags	FeatureFlagSettings Experimental features to enable on the server.
openTelemetry	OpenTelemetrySettings Options for OpenTelemetry
plugins	ServerPluginsConfig Configuration for plugins

RunMode (Enum)

Type of run mode this process should use. Each carry different types of workloads. More than one mode can be active. But not all modes are not guaranteed to be compatible with each other and will raise an error if combined in such a way.

Name	Description
None	Default no-op value (ASP.NET config will default to this for enums that cannot be parsed)
Server	Handle and respond to incoming external requests, such as HTTP REST and gRPC calls. These requests are time-sensitive and short-lived, typically less than 5 secs. If processes handling requests are unavailable, it will be very visible for users.
Worker	Run non-request facing workloads. Such as background services, processing queues, running work based on timers etc. Short periods of downtime or high CPU usage due to bursts are fine for this mode. No user requests will be impacted directly. If auto-scaling is used, a much more aggressive policy can be applied (tighter process packing, higher avg CPU usage).

AuthMethod (Enum)

Authentication method used for logging users in

Name	Description
Anonymous	No authentication enabled. Only for demo and testing purposes.
Okta	OpenID Connect authentication, tailored for Okta
OpenIdConnect	Generic OpenID Connect authentication, recommended for most
Horde	Authenticate using username and password credentials stored in Horde OpenID Connect (OIDC) is first and foremost recommended. But if you have a small installation (less than ~10 users) or lacking an OIDC provider, this is an option.

FeatureFlagSettings

Feature flags to aid rollout of new features. Once a feature is running in its intended state and is stable, the flag should be removed. A name and date of when the flag was created is noted next to it to help encourage this behavior. Try having them be just a flag, a boolean.

OpenTelemetrySettings

OpenTelemetry configuration for collection and sending of traces and metrics.

Name	Description
enabled	boolean Whether OpenTelemetry exporting is enabled
serviceName	string Service name
serviceNamespace	string Service namespace
serviceVersion	string Service version
enableDatadogCompatibility	boolean Whether to enrich and format telemetry to fit presentation in Datadog
attributes	string -> string Extra attributes to set
enableConsoleExporter	boolean Whether to enable the console exporter (for debugging purposes)
protocolExporters	string -> OpenTelemetryProtocolExporterSettings Protocol exporters (key is a unique and arbitrary name)

OpenTelemetryProtocolExporterSettings

Configuration for an OpenTelemetry exporter

Name	Description
endpoint	string Endpoint URL. Usually differs depending on protocol used.
protocol	string Protocol for the exporter ('grpc' or 'httpprotobuf')

ServerPluginsConfig

Name	Description
analytics	AnalyticsServerConfig Configuration for the analytics plugin
build	BuildServerConfig Configuration for the build plugin
compute	ComputeServerConfig Configuration for the compute plugin
ddc	PluginServerConfig Configuration for the ddc plugin
experimental	ExperimentalServerConfig Configuration for the experimental plugin
secrets	PluginServerConfig Configuration for the secrets plugin
storage	StorageServerConfig Configuration for the storage plugin
symbols	PluginServerConfig Configuration for the symbols plugin
tools	ToolsServerConfig Configuration for the tools plugin

AnalyticsServerConfig

Server configuration for the analytics system

Name	Description
sinks	TelemetrySinkConfig Settings for the various telemetry sinks
enabled	boolean Whether the plugin should be enabled or not

TelemetrySinkConfig

Telemetry sinks

Name	Description
epic	EpicTelemetryConfig Settings for the Epic telemetry sink
mongo	MongoTelemetryConfig Settings for the MongoDB telemetry sink

EpicTelemetryConfig

Configuration for the telemetry sink

Name	Description
url	string Base URL for the telemetry server
appId	string Application name to send in the event messages
enabled	boolean Whether to enable this sink

MongoTelemetryConfig

Configuration for the telemetry sink

Name	Description
retainDays	number Number of days worth of telmetry events to keep
enabled	boolean Whether to enable this sink

BuildServerConfig

Static configuration for the build plugin

Name	Description
perforce	PerforceConnectionSettings[] Perforce connections for use by the Horde server (not agents)
useLocalPerforceEnv	boolean Whether to use the local Perforce environment
perforceConnectionPoolSize	integer Number of pooled perforce connections to keep
enableConformTasks	boolean Whether to enable the conform task source.
p4SwarmUrl	string Url of P4 Swarm installation
robomergeUrl	string Url of Robomergem installation
commitsViewerUrl	string Url of Commits Viewer
jiraUsername	string The Jira service account user name
jiraApiToken	string The Jira service account API token
jiraUrl	string The Uri for the Jira installation
sharedDeviceCheckoutDays	integer The number of days shared device checkouts are held
deviceProblemCooldownMinutes	integer The number of cooldown minutes for device problems
deviceReportChannel	string Channel to send device reports to
disableSchedules	boolean Whether to run scheduled jobs.
slackToken	string Bot token for interacting with Slack (xoxb-*)
slackSocketToken	string Token for opening a socket to slack (xapp-*)
slackAdminToken	string Admin user token for Slack (xoxp-*). This is only required when using the admin endpoints to invite users.
slackUsers	string Filtered list of slack users to send notifications to. Should be Slack user ids, separated by commas.
slackErrorPrefix	string Prefix to use when reporting errors
slackWarningPrefix	string Prefix to use when reporting warnings
configNotificationChannel	string Channel for sending messages related to config update failures
updateStreamsNotificationChannel	string Channel to send stream notification update failures to
jobNotificationChannel	string Slack channel to send job related notifications to. Multiple channels can be specified, separated by ;
agentNotificationChannel	string Slack channel to send agent related notifications to.
testDataRetainMonths	integer The number of months to retain test data
blockCacheDir	string Directory to store the fine-grained block cache. This caches individual exports embedded in bundles.
blockCacheSize	string Maximum size of the block cache. Accepts standard binary suffixes. Currently only allocates in multiples of 1024mb.
blockCacheSizeBytes	integer Accessor for the block cache size in bytes
commits	CommitSettings Options for the commit service
enabled	boolean Whether the plugin should be enabled or not

PerforceConnectionSettings

Perforce connection information for use by the Horde server (for reading config files, etc...)

Name	Description
id	string Identifier for this server
serverAndPort	string Server and port
credentials	PerforceCredentials Credentials for the server

PerforceCredentials

Credentials for a Perforce user

Name	Description
userName	string The username
password	string Password for the user
ticket	string Login ticket for the user (will be used instead of password if set)

CommitSettings

Options for the commit service

Name	Description
replicateMetadata	boolean Whether to mirror commit metadata to the database
replicateContent	boolean Whether to mirror commit data to storage
bundle	BundleOptions Options for how objects are packed together
chunking	ChunkingOptions Options for how objects are sliced

BundleOptions

Options for configuring a bundle serializer

Name	Description
maxVersion	BundleVersion Maximum version number of bundles to write
maxBlobSize	integer Maximum payload size fo a blob
compressionFormat	BundleCompressionFormat Compression format to use
minCompressionPacketSize	integer Minimum size of a block to be compressed
maxWriteQueueLength	integer Maximum amount of data to store in memory. This includes any background writes as well as bundles being built.

BundleVersion (Enum)

Bundle version number

Name	Description
Initial	Initial version number
ExportAliases	Added the BundleExport.Alias property
RemoveAliases	Back out change to include aliases. Will likely do this through an API rather than baked into the data.
InPlace	Use data structures which support in-place reading and writing.
ImportHashes	Add import hashes to imported nodes
LatestV1	Last version using the V1 pipeline
PacketSequence	Structure bundles as a sequence of self-contained packets (uses V2 code)
Latest	The current version number
LatestV2	Last version using the V2 pipeline
LatestPlusOne	Last item in the enum. Used for

BundleCompressionFormat (Enum)

Indicates the compression format in the bundle

Name	Description
None	Packets are uncompressed
LZ4	LZ4 compression
Gzip	Gzip compression
Oodle	Oodle compression (Selkie)
Brotli	Brotli compression
Zstd	ZStandard compression

ChunkingOptions

Options for creating file nodes

Name	Description
leafOptions	LeafChunkedDataNodeOptions Options for creating leaf nodes
interiorOptions	InteriorChunkedDataNodeOptions Options for creating interior nodes

LeafChunkedDataNodeOptions

Options for creating a specific type of file nodes

Name	Description
minSize	integer Minimum chunk size
maxSize	integer Maximum chunk size. Chunks will be split on this boundary if another match is not found.
targetSize	integer Target chunk size for content-slicing
windowSize	integer Window size to use when scanning for split points
threshold	integer Accessor for the BuzHash chunking threshold

InteriorChunkedDataNodeOptions

Options for creating interior nodes

Name	Description
minChildCount	integer Minimum number of children in each node
targetChildCount	integer Target number of children in each node
maxChildCount	integer Maximum number of children in each node
sliceThreshold	integer Threshold hash value for splitting interior nodes

ComputeServerConfig

Static configuration for the compute plugin

Name	Description
enableUpgradeTasks	boolean Whether to enable the upgrade task source, always upgrading agents to the latest version
withAws	boolean Whether to enable Amazon Web Services (AWS) specific features
awsRegions	string[] List of AWS regions for Horde to be aware of (e.g. us-east-1 or eu-central-1) Right now, this is only used for replicating CloudWatch metrics to multiple regions
awsAutoScalingQueueUrls	string[] AWS SQS queue URLs where lifecycle events from EC2 auto-scaling are received
fleetManagerV2	FleetManagerType Default fleet manager to use (when not specified by pool)
fleetManagerV2Config	object Config for the fleet manager (serialized JSON)
autoEnrollAgents	boolean Whether to automatically enroll agents in the farm
defaultAgentPoolSizeStrategy	PoolSizeStrategy Default agent pool sizing strategy for pools that doesn't have one explicitly configured
agentPoolScaleOutCooldownSeconds	integer Scale-out cooldown for auto-scaling agent pools (in seconds). Can be overridden by per-pool settings.
agentPoolScaleInCooldownSeconds	integer Scale-in cooldown for auto-scaling agent pools (in seconds). Can be overridden by per-pool settings.
computeTunnelPort	integer Port to listen on for tunneling compute sockets to agents
computeTunnelAddress	string What address (host:port) clients should connect to for compute socket tunneling Port may differ from if Horde server is behind a reverse proxy/firewall
enabled	boolean Whether the plugin should be enabled or not

FleetManagerType (Enum)

Available fleet managers

Name	Description
Default	Default fleet manager
NoOp	No-op fleet manager.
Aws	Fleet manager for handling AWS EC2 instances. Will create and/or terminate instances from scratch.
AwsReuse	Fleet manager for handling AWS EC2 instances. Will start already existing but stopped instances to reuse existing EBS disks.
AwsRecycle	Fleet manager for handling AWS EC2 instances. Will start already existing but stopped instances to reuse existing EBS disks.
AwsAsg	Fleet manager for handling AWS EC2 instances. Uses an EC2 auto-scaling group for controlling the number of running instances.

PoolSizeStrategy (Enum)

Available pool sizing strategies

Name	Description
LeaseUtilization	Strategy based on lease utilization
JobQueue	Strategy based on size of job build queue
NoOp	No-op strategy used as fallback/default behavior
ComputeQueueAwsMetric	A no-op strategy that reports metrics to let an external AWS auto-scaling policy scale the fleet
LeaseUtilizationAwsMetric	A no-op strategy that reports metrics to let an external AWS auto-scaling policy scale the fleet

PluginServerConfig

Base class for plugin server config objects

Name	Description
enabled	boolean Whether the plugin should be enabled or not

ExperimentalServerConfig

Server configuration for the experimental plugin

Name	Description
enabled	boolean Whether the plugin should be enabled or not

StorageServerConfig

Static settings for the storage system

Name	Description
bundleCacheDir	string Directory to use for the coarse-grained backend cache. This caches full bundles downloaded from the upstream object store.
bundleCacheSize	string Maximum size of the storage cache on disk. Accepts standard binary suffixes (kb, mb, gb, tb, etc...)
bundleCacheSizeBytes	integer Accessor for the bundle cache size in bytes
backends	BackendConfig[] Overridden settings for storage backends. Useful for running against a production server with custom backends.
enabled	boolean Whether the plugin should be enabled or not

BackendConfig

Common settings object for different providers

Name	Description
id	string The storage backend ID
base	string Base backend to copy default settings from
secondary	string Specifies another backend to read from if an object is not found in this one. Can be used when migrating data from one backend to another.
type	StorageBackendType
baseDir	string
awsBucketName	string Name of the bucket to use
awsBucketPath	string Base path within the bucket
awsCredentials	AwsCredentialsType Type of credentials to use
awsRole	string ARN of a role to assume
awsProfile	string The AWS profile to read credentials form
awsRegion	string Region to connect to
azureConnectionString	string Connection string for Azure
azureContainerName	string Name of the container
relayServer	string
relayToken	string
gcsBucketName	string Name of the GCS bucket to use
gcsBucketPath	string Base path within the bucket

StorageBackendType (Enum)

Types of storage backend to use

Name	Description
FileSystem	Local filesystem
Aws	AWS S3
Azure	Azure blob store
Gcs	Google Cloud Storage
Memory	In-memory only (for testing)

AwsCredentialsType (Enum)

Credentials to use for AWS

Name	Description
Default	Use default credentials from the AWS SDK
Profile	Read credentials from the profile in the AWS config file
AssumeRole	Assume a particular role. Should specify ARN in
AssumeRoleWebIdentity	Assume a particular role using the current environment variables.

ToolsServerConfig

Server configuration for bundled tools

Name	Description
bundledTools	BundledToolConfig[] Tools bundled along with the server. Data for each tool can be produced using the 'bundle create' command, and should be stored in the Tools directory.
enabled	boolean Whether the plugin should be enabled or not

BundledToolConfig

Configuration for a tool bundled alongsize the server

Name	Description
version	string Version string for the current tool data
refName	string Ref name in the tools directory
dataDir	string Directory containing blob data for this tool. If empty, the tools/{id} folder next to the server will be used.
id	string Unique identifier for the tool
name	string Name of the tool
description	string Description for the tool
category	string Category for the tool. Will cause the tool to be shown in a different tab in the dashboard.
group	string Grouping key for different variations of the same tool. The dashboard will show these together.
platforms	string[] Platforms for this tool. Takes the form of a NET RID (https://learn.microsoft.com/en-us/dotnet/core/rid-catalog).
public	boolean Whether this tool should be exposed for download on a public endpoint without authentication
showInUgs	boolean Whether to show this tool for download in the UGS tools menu
showInDashboard	boolean Whether to show this tool for download in the dashboard
showInToolbox	boolean Whether to show this tool for download in Unreal Toolbox
metadata	string -> string Metadata for this tool
namespaceId	string Default namespace for new deployments of this tool
acl	AclConfig Permissions for the tool

AclConfig

Parameters to update an ACL

Name	Description
entries	AclEntryConfig[] Entries to replace the existing ACL
profiles	AclProfileConfig[] Defines profiles which allow grouping sets of actions into named collections
inherit	boolean Whether to inherit permissions from the parent ACL
exceptions	string[] List of exceptions to the inherited setting

AclEntryConfig

Individual entry in an ACL

Name	Description
claim	AclClaimConfig Name of the user or group
actions	string[] Array of actions to allow
profiles	string[] List of profiles to grant

AclClaimConfig

New claim to create

Name	Description
type	string The claim type
value	string The claim value

AclProfileConfig

Configuration for an ACL profile. This defines a preset group of actions which can be given to a user via an ACL entry.

Name	Description
id	string Identifier for this profile
actions	string[] Actions to include
excludeActions	string[] Actions to exclude from the inherited actions
extends	string[] Other profiles to extend from