Client Configuration

Both the TUI (conclave-cli) and GUI (conclave-gui) read configuration from:

1. $CONCLAVE_CONFIG_DIR/config.toml
2. $XDG_CONFIG_HOME/conclave/config.toml (typically ~/.config/conclave/config.toml)

All fields have sensible defaults and can be omitted. The client works without a config file.

Command-Line Arguments

Running conclave-cli with no subcommand launches the interactive TUI. Running conclave-gui launches the graphical interface.

Configuration Fields

Custom Headers

The [custom_headers] section allows sending arbitrary HTTP headers with every request. This is useful for authenticating with a reverse proxy in front of the Conclave server, which can help prevent active probing of the server.

[custom_headers]
Authorization = "Basic dXNlcjpwYXNz"

Headers are sent on all requests including SSE connections. Conclave’s own Authorization: Bearer token for session auth is set per-request and takes precedence over any Authorization header in [custom_headers].

Path prefix

If the reverse proxy serves Conclave under a path prefix, include the prefix in the server URL at login time. For example, if the proxy maps /myapp/ to the Conclave server:

/login https://example.com/myapp username

The client builds all API URLs from the server URL, so paths like /myapp/api/v1/... work automatically. No additional client configuration is needed.

Theme Customization

The GUI supports theme customization via the [theme] section. All fields are optional — unset fields keep the built-in defaults. Colors use #rrggbb hex format.

Preset themes are available in assets/themes/. Copy the [theme] section from a preset into your config file to use it.

Available presets: conclave, ferra, greyscale, navy.

Full Reference

# Local data directory.
# Default: $CONCLAVE_DATA_DIR, or $XDG_DATA_HOME/conclave
#   (typically ~/.local/share/conclave)
#data_dir = "/home/user/.local/share/conclave"

# Accept invalid TLS certificates (e.g., self-signed). Default: false.
# Only enable this for development or testing environments.
#accept_invalid_certs = false

# Show verification indicators for verified users and fully-verified rooms.
# Default: false (hides verified indicators to reduce visual clutter).
#show_verified_indicator = false

# TUI-only: notification method for new messages.
# Possible values: "Native" (default), "Bell", "Both", "None".
#notifications = "Native"

# Proxy URL for all HTTP traffic.
# Supports http://, https://, socks5://, and socks5h:// schemes.
# When unset, standard proxy env vars (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY)
# are respected.
#proxy_url = "socks5://127.0.0.1:1080"

# Path to a PEM file containing custom CA certificates to trust in addition
# to the system root certificates. May contain multiple PEM certificates.
#ca_cert_path = "/path/to/custom-ca.pem"

# HTTP header name for session authentication. Default: "Authorization".
# When set to a custom value (e.g., "X-Conclave-Token"), the client sends
# the raw token without the "Bearer " prefix, freeing "Authorization" for
# reverse proxy auth. Must match the server's auth_header setting.
#auth_header = "Authorization"

# Arbitrary HTTP headers sent with every request. Useful for authenticating
# with a reverse proxy to prevent active probing of the Conclave server.
#[custom_headers]
#Authorization = "Basic dXNlcjpwYXNz"
#X-Custom-Token = "my-secret"

# GUI theme overrides. All fields are optional; unset fields keep the
# built-in defaults. Colors use "#rrggbb" hex format.
# Theme presets are available in the assets/themes/ directory.
#[theme]
#background = "#2B292D"
#surface = "#242226"
#surface_bright = "#323034"
#title_bar = "#1E1C20"
#input_area = "#1E1C20"
#primary = "#FECDB2"
#text = "#FECDB2"
#text_secondary = "#AB8A79"
#text_muted = "#685650"
#error = "#E06B75"
#on_error = "#FFFFFF"
#warning = "#FFA07A"
#on_warning = "#2B292D"
#success = "#B1B695"
#border = "#4F474D"
#scrollbar = "#323034"
#selection = "#453D41"

Data Directory Layout

After logging in, the client stores data under data_dir:

~/.local/share/conclave/
  conclave.lock             # Exclusive file lock (prevents multiple instances)
  session.toml              # Server URL, auth token, user ID
  users/<username>/
    mls.db                  # MLS key material (SQLite)
    message_history.db      # Message store and TOFU fingerprints (SQLite)

Only one Conclave client instance can run at a time per data directory. Launching a second instance will fail with an error. The lock is released automatically when the process exits.