Runtime Settings Reference

What Runtime Settings Are

Runtime settings are hot-reload settings stored in PostgreSQL. They are mainly for changing product policy while the service is running. They are different from YAML/env/CLI startup configuration:

Type	Storage	Hot reload	Suitable for
Startup configuration	YAML, env, secret files, CLI flags	No; usually requires restart	Ports, database, Redis, secrets, TLS, data_dir, cache enablement
Runtime settings	PostgreSQL settings table	Yes; replicas sync through LISTEN/NOTIFY	Registration, room creation, permission defaults, proxy switches, CORS, chat retention

Caution

Do not put startup secrets, database URLs, Redis URLs, listener ports, or slice-cache enablement into runtime settings. Those belong to startup configuration.

CLI Usage

synctv settings list
synctv settings get user
synctv settings update user --set enablePasswordSignup=true

If the command supports grouped --set form:

synctv settings update email --set whitelistEnabled=true --set whitelistDomains=example.com

Check the current binary with synctv settings --help.

Sync and Consistency

Runtime settings are written to PostgreSQL and propagated to other replicas through PostgreSQL LISTEN/NOTIFY.

Semantics:

• Each setting key has a registered typed provider.
• Writes are type-checked and value-validated before persistence.
• Cross-key invariants use transactional validation, for example room policy is validated in a single transaction.
• If a replica misses notifications, it refreshes from a full snapshot.

Keys

Server

Key	Type	Default	Validation	Meaning
server.allowRoomCreation	bool	true	bool	Whether users can create rooms
server.maxRoomsPerUser	i64	10	1..=1000	Maximum rooms per user
server.maxMembersPerRoom	i64	100	1..=10000	Maximum members per room
server.maxChatMessages	u64	500	<=10000; 0 means unlimited	Service-level public chat message cap policy; cleanup uses chat.maxMessagesPerRoom

Permissions

Key	Type	Default	Meaning
permissions.adminDefaultPermissions	Permission-name array	Built-in admin permission set	Global default permissions for room admin
permissions.memberDefaultPermissions	Permission-name array	Built-in member permission set	Global default permissions for room member
permissions.guestDefaultPermissions	Permission-name array	[]	Global default permissions for room guest; only view_member_list, view_chat_history, and use_webrtc are accepted

These settings are stored as JSON arrays of stable permission names, for example:

["send_chat", "create_media_resource", "view_media_resources", "view_member_list"]

permissions.guestDefaultPermissions has a dedicated guest ceiling. It rejects view_media_resources, send_chat, media-resource, playback-control, and administration permissions. Valid example:

["view_member_list", "view_chat_history", "use_webrtc"]

See Rooms, Permissions, and Preferences for permission names, role defaults, and room override rules.

Room

Key	Type	Default	Validation	Meaning
room.disableCreateRoom	bool	false	bool	Disable room creation
room.createRoomNeedReview	bool	false	bool	Require review for room creation
room.passwordPolicy	enum string	optional	optional, required, forbidden	Room password policy

User

Key	Type	Default	Meaning
user.enablePasswordSignup	bool	false	Allow local password signup, including OPAQUE registration and direct password transport registration
user.passwordSignupNeedReview	bool	false	Require review for password signup
user.enableEmailSignup	bool	false	Allow email registration where confirmation sets local password credentials
user.emailSignupNeedReview	bool	false	Require review for email signup
user.enableWebauthnSignup	bool	false	Allow WebAuthn/passkey as the initial account registration method; authenticated passkey binding is not signup
user.webauthnSignupNeedReview	bool	false	Require review for WebAuthn signup; the review queue stores the pending passkey and approval creates the account with its WebAuthn credential
user.enableGuest	bool	true	Allow guest capability

All registration modes are disabled by default. Production deployments should enable only the intended entry points and configure review independently for each mode.

OAuth2

Key	Type	Default	Meaning
oauth2.providers	JSON array	[]	OAuth2/OIDC provider instance registry. Each element is an OAuth2ProviderSettings ProtoJSON object

oauth2.providers is the OAuth2 configuration entry point. instanceName may contain only ASCII letters, digits, _, and -, and must be at most 64 bytes. Each element uses one provider oneof field such as github or oidc:

[
  {
    "instanceName": "github",
    "enableSignup": true,
    "signupNeedReview": false,
    "github": {
      "clientId": "github-client-id",
      "clientSecret": "github-client-secret",
      "redirectUrl": "https://app.example.com/oauth2/callback"
    }
  },
  {
    "instanceName": "corp_oidc",
    "enableSignup": false,
    "signupNeedReview": false,
    "oidc": {
      "clientId": "synctv",
      "clientSecret": "oidc-client-secret",
      "issuer": "https://idp.example.com",
      "redirectUrl": "https://app.example.com/oauth2/callback"
    }
  }
]

A missing provider instance means that login entry point is unavailable. Missing or false enableSignup blocks first-time OAuth2 account creation while existing linked OAuth2 logins continue to work. signupNeedReview=true stores first-time OAuth2 signup in the user registration review queue; approval creates the local account and OAuth2 binding.

User-level 2FA and notification preferences are user preferences, not runtime settings. Provider instance bindings are stored on provider credentials created during provider login. See Rooms, Permissions, and Preferences.

Proxy

Key	Type	Default	Meaning
proxy.movieProxy	bool	true	Allow media proxy paths
proxy.liveProxy	bool	true	Allow livestream proxy paths

These are business proxy policy switches, not startup setting proxy_slice_cache.enabled. Slice-cache enablement is startup-only.

RTMP

Key	Type	Default	Meaning
rtmp.customPublishHost	string	""	Custom publish host returned to stream publishers
rtmp.tsDisguisedAsPng	bool	false	Disguise TS segments as PNG paths or responses

Email

Key	Type	Default	Meaning
email.whitelistEnabled	bool	false	Enable email allowlist
email.whitelistDomains	string	""	Email allowlist content as comma-separated domains or email addresses

When email.whitelistEnabled=true but email.whitelistDomains is empty, no email domain is rejected. Matching is enforced only when the allowlist has entries.

SMTP host, password, and sender configuration remain startup settings. See Email and OAuth2.

WebRTC

Key	Type	Default	Meaning
webrtc.externalIceServers	JSON/string structure	two Google STUN entries	External ICE servers returned to native clients

Default value:

[
  { "urls": ["stun:stun.l.google.com:19302"] },
  { "urls": ["stun:stun1.l.google.com:19302"] }
]

Built-in STUN listener configuration is startup configuration. See WebRTC Configuration.

Chat

Key	Type	Default	Validation	Meaning
chat.maxMessagesPerRoom	u64	500	<=100000; 0 means unlimited	Maximum retained chat messages per room
chat.maxPinnedMessagesPerRoom	u64	20	<=1000	Maximum retained pinned chat messages per room
chat.messageRetentionDays	i64 days	90	1..=3650	Maximum chat message retention age

CORS

Key	Type	Default	Meaning
cors.allowedOrigins	JSON/string structure	[]	Runtime CORS allowed origins for proxy-related paths

Main service startup CORS is server.cors_allowed_origins. Runtime CORS is for policy that can change while the service runs.

Examples

Enable password signup

synctv settings update user --set enablePasswordSignup=true

Review password signup

synctv settings update user --set passwordSignupNeedReview=true

Limit room count

synctv settings update server --set maxRoomsPerUser=20

Chat retention

synctv settings update chat --set maxMessagesPerRoom=1000 --set messageRetentionDays=180

Configure OAuth2

synctv settings update oauth2 --set providers='[
  {
    "instanceName": "github",
    "enableSignup": true,
    "signupNeedReview": false,
    "github": {
      "clientId": "github-client-id",
      "clientSecret": "github-client-secret",
      "redirectUrl": "https://app.example.com/oauth2/callback"
    }
  }
]'

Before Changing Values

Confirm Hot-Reload Scope

Ports, secrets, database, Redis, TLS, and cache enablement are startup configuration, not runtime settings.

Read Current Value

Run synctv settings get <key> before changing a value and keep it for rollback.

Watch Replicas

Multi-replica sync depends on PostgreSQL notifications; observe all replicas after changes.

Record Reason

Keep reasons for registration, room creation, proxy, and permission-default policy changes.