Pod configuration reference

Updated on June 30, 2025

To configure a Prose Pod, you can use the /etc/prose/prose.toml configuration file (in TOML format).

Each field can also be overwritten using environment variables with the PROSE_ prefix and path segments separated by __. For example, you might change the Prose Pod API’s maximum log level by setting PROSE_LOG__LEVEL=debug.

General settings

Key	Kind	Description	Default
`branding`	BrandingConfig	Where you configure static data like your company name.	See below
`notifiers`	NotifiersConfig	Where you set how notifications are sent (e.g. when sending invitations).	See below
`log`	LogConfig	Log configuration for the Prose Pod API.	See below
`pod`	PodConfig	Configuration for the Prose Pod itself.	See below
`server`	ServerConfig	Server configuration.	See below
`dashboard`	DashboardConfig	Dashboard configuration.	See below

BrandingConfig

Key	Kind	Description	Default
`company_name`	`String`	Name of your company. Will be used in places like invitation emails.	-
`api_app_name`	`String`	Name used in some places to refer to your Prose Pod API (e.g. “All data will be erased from `{company_name}`’s `{api_app_name}` databases.”). You shouldn’t have a reason to change it, but it’s there.	`"Prose Pod API"`

NotifiersConfig

Key	Kind	Description	Default
`email`	EmailNotifierConfig	Email notifications + SMTP configuration.	-

EmailNotifierConfig

Key	Kind	Description	Default
`pod_address`	`String` (email address)	Pod email address (e.g. `"prose@{smtp_host}"`).	`"prose@{server.domain}"`
`smtp_host`	`String`	SMTP host.	-
`smtp_port`	`u16`	SMTP port.	`587`
`smtp_username`	`String` (optional)	SMTP username.	-
`smtp_password`	`String` (optional)	SMTP password.	-
`smtp_encrypt`	`bool`	Require SMTP encryption. If `false`, will still use encryption but only if available.	`true`

LogConfig

Key	Kind	Description	Default
`level`	`LogLevel`	Maximum log level (`trace`, `debug`, `info`, `warn`, `error`).	`info`
`format`	`LogFormat`	Log format (`full`, `compact`, `json`, `pretty`). See tracing_subscriber::fmt for more details.	`pretty` in debug, `json` in release
`timer`	`LogTimer`	Timer format (`none`, `time`, `uptime`).	`uptime` in debug, `time` in release
`with_ansi`	`bool`	Enable ANSI color codes.	`true` in debug, `false` in release
`with_file`	`bool`	Include file path in logs.	`true` in debug, `false` in release
`with_level`	`bool`	Include log level.	`true`
`with_target`	`bool`	Include Rust target module.	`true`
`with_thread_ids`	`bool`	Include thread IDs.	`false`
`with_line_number`	`bool`	Include line numbers.	`true` in debug, `false` in release
`with_span_events`	`bool`	Include span events.	`false`
`with_thread_names`	`bool`	Include thread names.	`true` in debug, `false` in release

PodConfig

Key	Kind	Description	Default
`address`	PodAddress	Public network address of the server that runs the Prose Pod.	See below

PodAddress

Public network address of the server that runs the Prose Pod.

Key	Kind	Description	Default
`domain`	`String` (optional)*	Public domain name of the Prose Pod.	`"prose.{server.domain}"`
`ipv4`	IPv4 (optional)*	Static IPv4 of the Prose Pod.	-
`ipv6`	IPv6 (optional)*	Static IPv6 of the Prose Pod.	-

(*) At least one of domain, ipv4 and ipv6 must be set.

ServerConfig

Key	Kind	Description	Default
`domain`	`String`	Domain name of the messaging server. This is what will appear in user IDs (`user@domain`). Once set, it cannot be changed.	-
`log_level`	`String`	Maximum log level of the Prose Pod Server (`"debug"`, `"info"`, `"warn"`, `"error"`).	`"info"`
`defaults`	ServerDefaultsConfig	Server configuration defaults. Will be used unless you override them using the Dashboard or Prose Pod API.	See below
`oauth2_registration_key`	`String`	OAuth 2.0 registration key.	Random 256-byte key
`oauth2_access_token_ttl`	`u32` (seconds)	OAuth 2.0 access token TTL.	`10800` (3 hours)
`http_port`	`u16`	HTTP port.*	`5280`
`local_hostname`	`String`	Local hostname.*	`"prose-pod-server"`
`local_hostname_admin`	`String`	Admin local hostname.*	`"prose-pod-server-admin"`

(*) Things will likely break if you change this.

ServerDefaultsConfig

Key	Kind	Description	Default
`message_archive_enabled`	`bool`	Activate or deactivate message archiving.	`true`
`message_archive_retention`	Duration	Message archive retention period.	`infinite`
`file_upload_allowed`	`bool`	Activate or deactivate file upload and sharing.	`true`
`file_storage_retention`	Duration	File storage retention period.	`infinite`
`tls_profile`	`String`	TLS profile configuration (`"modern"`, `"intermediate"`, `"old"`). See https://wiki.mozilla.org/Security/Server_Side_TLS.	`"modern"`
`federation_enabled`	`bool`	Enabling federation will allow other servers to connect to your. This lets users from other Prose Workspaces connect with users in this Workspace. For more safety, whitelist friendly servers.	`false`
`federation_whitelist_enabled`	`bool`	Whether or not to enable server whitelisting. Caution: If a whitelist is set but disabled, your server will still federate with the entire XMPP network.	`false`
`federation_friendly_servers`	`Vec<String>`	If a whitelist is defined, then other servers will not be allowed to connect to this server, except whitelisted ones. It is recommended to whitelist servers you typically work with, i.e. other teams.	`[]`
`push_notification_with_body`	`bool`	Whether or not to send the real message body to the remote pubsub node. Without end-to-end encryption, enabling this may expose your message contents to your client developers and OS vendor. Not recommended.	`true`
`push_notification_with_sender`	`bool`	Whether or not to send the real message sender to the remote pubsub node. Enabling this may expose your contacts to your client developers and OS vendor. Not recommended.	`true`

DashboardConfig

Key	Kind	Description	Default
`url`	URI	Bashboard URL.	`"https://admin.{pod.address.domain}"`

Advanced settings

You shouldn’t have to touch those, but if you really need them they exist. Know that you might break your Prose Pod by changing those, we don’t guarantee anything.

Key	Kind	Description	Default
`api`	ApiConfig	Prose Pod API configuration.	See below
`bootstrap`	BootstrapConfig	Bootstrap configuration.	See below
`auth`	AuthConfig	Authentication & authorization configuration.	See below
`prosody_ext`	ProsodyExtConfig	Prosody extension configuration.	See below
`prosody`	`HashMap<String, ProsodyHostConfig>`	A map of `ProsodyHostConfig`s by Prosody `VirtualHost` or `Component` domain. The special `"global"` key applies to the global Prosody configuration (top level).	`[:]`
`service_accounts`	ServiceAccountsConfig	Service account configuration.	See below

ApiConfig

Key	Kind	Description	Default
`databases`	DatabasesConfig	Where you can configure internal Prose Pod API databases.	See below
`address`	IPv4 / IPv6	IP address to serve API on*.	`"0.0.0.0"`
`port`	`u16`	Port to serve the API on*.	`8080`
`default_response_timeout`	Duration	Timeout after which all requests are cancelled.	`PT10S`
`default_retry_interval`	Duration	Default interval between retries (e.g. when running network checks).	`PT5S`

(*) Things will likely break if you change this.

DatabasesConfig

Key	Kind	Description	Default
`main`	DatabaseConfig	Main database configuration.	See below

DatabaseConfig

Key	Kind	Description	Default
`url`	URI	Database URL.	`"sqlite:///var/lib/prose-pod-api/database.sqlite"`
`min_connections`	`u32` (optional)	Minimum number of connections.	`None`
`max_connections`	`usize`	Maximum number of connections.	Parallelism capacity * 4
`connect_timeout`	`u64` (seconds)	Connection acquiring timeout.	`5`
`idle_timeout`	`u64` (optional)	Idle connection timeout.	`None`
`sqlx_logging`	`bool`	Enable sqlx logging.	`false`

BootstrapConfig

Key	Kind	Description	Default
`prose_pod_api_xmpp_password`	`String`	Bootstrap XMPP password for the Prose Pod API service account.**	`"bootstrap"`

(**) The first thing the Prose Pod API does when starting up is changing this password to a very strong random password, so you shouldn’t have a reason to change it (see Provide a default bootstrap password · Issue #246 · prose-im/prose-pod-api).

AuthConfig

Key	Kind	Description	Default
`token_ttl`	Duration	How long sessions are valid for (how often members need to log into the Dashboard again). Note that this only affects the Dashboard, not Prose apps.	`"PT3H"` (3 hours)
`password_reset_token_ttl`	Duration	How long password reset links are valid for.	`"PT15M"` (15 minutes)
`oauth2_registration_key`	`String`	OAuth 2.0 registration key.	Random 256-byte key

ProsodyExtConfig

Key	Kind	Description	Default
`additional_modules_enabled`	`Vec<String>`	Additional Prosody modules to enable.**	`[]`
`config_file_path`	`String`	Path to the Prosody configuration file.*	`"/etc/prosody/prosody.cfg.lua"`

(*) Things will likely break if you change this.

(**) Those modules will be enabled globally after every other configuration has been applied (apart from dynamic overrides, which are always applied last).

ProsodyHostConfig

Prosody settings to apply for one host (VirtualHost, Component or global).

Key	Kind	Description	Default
`defaults`	ProsodySettings (optional)	Defaults (overriden by config stored in the API database).	-
`overrides`	ProsodySettings (optional)	Overrides (applied no matter what).	-

ServiceAccountsConfig

Key	Kind	Description	Default
`prose_workspace`	ServiceAccountConfig	XMPP account of your Prose Workspace itself. It is used to store your Workspace name, accent color and other information in a way that makes it available via the XMPP protocol.	`{ xmpp_node: "prose-workspace" }`
`prose_pod_api`	ServiceAccountConfig	XMPP account used by the Prose Pod API itself.*	`{ xmpp_node: "prose-pod-api" }`

(*) Things will likely break if you change this.

ServiceAccountConfig

Key	Kind	Description	Default
`xmpp_node`	`String`	Local part of the JID used by this service account (see RFC 6120 - Extensible Messaging and Presence Protocol (XMPP): Core, section 1.4). The domain part will be your Server’s domain (i.e. `"{xmpp_node}@{server_domain}"`.	-

Debug settings

As the name suggest, you should only use those settings temporarily. They might expose user data or things like that. You have been warned.

Key	Kind	Description	Default
`debug_use_at_your_own_risk`	DebugConfig	Debug configuration.	See below

DebugConfig

Key	Kind	Description	Default
`log_config_at_startup`	`bool`	Log the parsed Prose Pod API configuration at startup.	`true` in debug, `false` in release
`detailed_error_responses`	`bool`	Enable detailed error responses (adds detailed messages and debug information).	`true` in debug, `false` in release
`c2s_unencrypted`	`bool`	Allow unencrypted client-to-server connections.	`false`
`skip_startup_actions`	`Vec<String>`	Startup actions to skip (by module name).	`[]`

Custom types

Duration

A duration in ISO 8601 format (e.g. "PT10S", "PT5M", "P2Y"…).

ProsodySettings

Prosody settings. See Configuring Prosody – Prosody IM.

Not all keys are supported, see prose-pod-api/src/prosody-config/src/prosody_config/mod.rs. If you miss support for a key, tell us and we’ll add it in a future release!