Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Server Configuration

The server is configured via a TOML file. The server searches for configuration in the following order:

  1. Path specified via --config (or -c) command-line flag.
  2. ./conclave.toml in the current working directory.
  3. /etc/conclave/config.toml.
  4. Built-in defaults (if no config file is found).

All fields have sensible defaults and can be omitted.

Configuration Fields

Network

FieldTypeDefaultDescription
listen_addressstring"0.0.0.0"IP address to bind to.
listen_portinteger8443 (TLS) or 8080 (plain HTTP)Port to listen on. Default depends on whether TLS is configured.

Database

FieldTypeDefaultDescription
database_pathstring"conclave.db"Path to the SQLite database file. Created automatically if it does not exist.

Sessions

FieldTypeDefaultDescription
token_ttl_secondsinteger2592000 (30 days)Session token lifetime in seconds. Token expiry is extended on every authenticated API call (sliding window). Idle sessions expire after this duration.

Invitations

FieldTypeDefaultDescription
invite_ttl_secondsinteger2592000 (30 days)Pending invite lifetime in seconds. Expired invites are cleaned up by the background task.

Message Retention

FieldTypeDefaultDescription
message_retentionstring"-1"Global message retention policy. "-1" disables retention (keep forever). "0" enables delete-after-fetch. Duration format (e.g., "30d") sets maximum message age. See Duration Format.
cleanup_intervalstring"1h"Interval between background cleanup runs. Same duration format.

Registration Control

FieldTypeDefaultDescription
registration_enabledbooleantrueWhether public registration is open. When false, registration requires a valid token.
registration_tokenstring(none)Registration token for invite-only registration. Only checked when registration_enabled is false. Must contain only [a-zA-Z0-9_-].

TLS

FieldTypeDefaultDescription
tls_cert_pathstring(none)Path to the TLS certificate file (PEM format).
tls_key_pathstring(none)Path to the TLS private key file (PEM format).

When both tls_cert_path and tls_key_path are set, the server serves HTTPS directly. When neither is set, the server serves plain HTTP (suitable for running behind a reverse proxy). Setting only one of the two is invalid.

Example Configurations

Minimal (Plain HTTP Behind Reverse Proxy)

listen_address = "127.0.0.1"
listen_port = 8080
database_path = "/var/lib/conclave/conclave.db"

Native TLS

listen_address = "0.0.0.0"
listen_port = 8443
database_path = "/var/lib/conclave/conclave.db"
tls_cert_path = "/etc/conclave/cert.pem"
tls_key_path = "/etc/conclave/key.pem"

Invite-Only with Message Retention

listen_address = "0.0.0.0"
database_path = "/var/lib/conclave/conclave.db"
registration_enabled = false
registration_token = "my-secret-invite-code"
message_retention = "30d"
cleanup_interval = "1h"
tls_cert_path = "/etc/conclave/cert.pem"
tls_key_path = "/etc/conclave/key.pem"

Full Reference

# Network
listen_address = "0.0.0.0"
listen_port = 8443

# Database
database_path = "conclave.db"

# Sessions
token_ttl_seconds = 2592000

# Invitations
invite_ttl_seconds = 2592000

# Message retention
message_retention = "-1"
cleanup_interval = "1h"

# Registration
registration_enabled = true
# registration_token = "your-secret-token"

# TLS
# tls_cert_path = "/path/to/cert.pem"
# tls_key_path = "/path/to/key.pem"

Systemd Service

A production-ready systemd unit file is provided in contrib/conclave-server.service. It runs the server as a dedicated conclave user with security hardening (sandboxed filesystem, restricted system calls, no new privileges).

To install:

sudo cp contrib/conclave-server.service /etc/systemd/system/
sudo useradd -r -s /usr/sbin/nologin conclave
sudo systemctl enable --now conclave-server

Place your config file at /etc/conclave/config.toml. The database is stored in /var/lib/conclave/.