Settings

Concept: The HTTP API surface →

Platform-wide settings, loaded from settings.json5 in the metadata root.

The file itself is entirely optional — every field has a default.

An unknown key at any level of the file, a misspelt setting name for example, is rejected when the file loads instead of being ignored.

Properties

Property	Type	Required/Default	Constraints	Meaning
tempUrlExpirySeconds	integer (uint64)	Optional (default: 300)	minimum 0	How long a setup or password-reset link stays valid, in seconds.
tokenExpiryMinutes	integer (uint64)	Optional (default: 60)	minimum 0	How long an issued JWT session token stays valid, in minutes.
api	ApiSettings object	Optional (default: {"cors":{"allowedOrigins":[]}})		Settings for the platform’s HTTP API surface.
surfaces	SurfacesSettings object	Optional (default: {})		Settings for the experience surfaces the server serves from disk.

tempUrlExpirySeconds

How long a setup or password-reset link stays valid, in seconds. Default: 300 (5 minutes).

tokenExpiryMinutes

How long an issued JWT session token stays valid, in minutes. Default: 60.

api

Settings for the platform’s HTTP API surface.

Absent by default — an absent block means every sub-setting takes its own default (an empty CORS allow-list, in particular).

surfaces

Settings for the experience surfaces the server serves from disk.

Absent by default — an absent block means no module surface is mounted.

ApiSettings

Settings for the platform’s HTTP API surface.

Property	Type	Required/Default	Constraints	Meaning
cors	CorsSettings object	Optional (default: {"allowedOrigins":[]})		Cross-origin resource sharing (CORS) policy for the HTTP API.

CorsSettings

Cross-origin resource sharing (CORS) policy for the platform’s HTTP API.

Read once at startup; a settings.json5 edit needs a server restart to take effect. An empty allow-list — the default — means the server emits no CORS response header of any kind. A non-empty list installs a policy that echoes back only a matching request’s own origin, never a wildcard.

Property	Type	Required/Default	Constraints	Meaning
allowedOrigins	array of string	Optional (default: [])		Browser origins permitted to make cross-origin requests to the API.

allowedOrigins

Browser origins permitted to make cross-origin requests to the API.

Matching is exact on scheme, host, and port. Every origin requires https://, except loopback hosts (localhost or localhost., a host ending in .localhost or .localhost., an IPv4 address in 127.0.0.0/8, or the IPv6 literal [::1]), which may use http://. Write the host the way a browser sends it: an IP address in its canonical form (127.0.0.1, [::1]), a domain name in ASCII (punycode for an internationalized name). A wildcard (*), the literal null, a path, a query string or fragment, userinfo, a wildcard subdomain, an explicit default port, a port with a leading zero, a host containing a character no browser sends in a host (such as a space, \, %, or |), an empty host label, a host label that starts or ends with a hyphen, an IP address not in canonical form, and a duplicate entry are all rejected when the file loads. Defaults to an empty list.

SurfacesSettings

Settings for the experience surfaces the server serves from disk.

Property	Type	Required/Default	Constraints	Meaning
directory	string	Optional		The directory module surfaces are served from.

directory

The directory module surfaces are served from. A module that declares a surface has its built files under <directory>/<moduleKey>/<assets>/, where assets is the surface’s own assets property, and the surface is mounted only while its entry file exists there.

A relative path is resolved against the metadata directory, where settings.json5 lives; it is the form that works unchanged under hf dev and in production. Read once at startup; a change needs a restart. Absent means no module surface is mounted; the surfaces built into the server are unaffected. A configured directory that does not exist stops the server at startup. A server older than this setting rejects a settings.json5 that sets it.

Example

{}