All settings accept both CLI flags (--bichon-http-port) and environment variables (BICHON_HTTP_PORT). CLI flags take precedence over environment variables.
Required Settings
| Variable | CLI Flag | Description |
|---|---|---|
BICHON_ROOT_DIR | --bichon-root-dir | Required. Absolute path for all persistent data |
BICHON_ENCRYPT_PASSWORD | --bichon-encrypt-password | Password used to encrypt stored credentials (IMAP passwords, OAuth tokens) |
BICHON_ENCRYPT_PASSWORD_FILE | --bichon-encrypt-password-file | Alternative: read the encryption password from a file |
Set one of these in production. If neither is supplied, the binary falls back to a built-in placeholder, so stored credentials are effectively protected by a publicly known key. Set exactly one of the two options; do not set both.
BICHON_ROOT_DIRis the only setting the parser itself requires.
Server & Networking
| Variable | Default | Description |
|---|---|---|
BICHON_HTTP_PORT | 15630 | HTTP server port |
BICHON_BIND_IP | 0.0.0.0 | IP address to bind to (IPv4 or IPv6) |
BICHON_PUBLIC_URL | http://localhost:15630 | Public-facing URL used in OAuth redirects and docs |
BICHON_BASE_URL | / | Base path for WebUI when behind a reverse proxy (e.g. /bichon) |
BICHON_WEBUI_TOKEN_EXPIRATION_HOURS | 168 | Access token lifetime in hours (default 7 days) |
BICHON_HTTP_COMPRESSION_ENABLED | true | Enable gzip/brotli/zstd response compression |
Logging
| Variable | Default | Description |
|---|---|---|
BICHON_LOG_LEVEL | info | Log level: trace, debug, info, warn, error |
BICHON_ANSI_LOGS | true | Colorized terminal output |
BICHON_JSON_LOGS | false | JSON-formatted logs for log aggregators |
BICHON_LOG_TO_FILE | false | Persist logs to files under root dir |
BICHON_MAX_SERVER_LOG_FILES | 5 | Max log files to retain |
CORS
| Variable | Default | Description |
|---|---|---|
BICHON_CORS_ORIGINS | (allow all) | Comma-separated list of allowed origins |
BICHON_CORS_MAX_AGE | 86400 | Cache duration for CORS preflight in seconds |
Warning: If
BICHON_CORS_ORIGINSis not set, all origins are allowed. If you set it, only exact matches pass. Wildcards (*) are not supported. Do not add trailing slashes. When using Docker, avoid wrapping the value in quotes.
TLS & HTTPS
| Variable | Default | Description |
|---|---|---|
BICHON_ENABLE_REST_HTTPS | false | Serve the API over HTTPS (requires valid certificate) |
SMTP Server
| Variable | Default | Description |
|---|---|---|
BICHON_ENABLE_SMTP | false | Enable the embedded SMTP receiver |
BICHON_SMTP_PORT | 2525 | SMTP listening port |
BICHON_SMTP_ENCRYPTION | starttls | Encryption mode: none, starttls, or tls |
BICHON_SMTP_AUTH_REQUIRED | true | Require authentication for SMTP connections |
BICHON_TLS_KEY_PATH | — | Absolute path to the SMTP TLS private key |
BICHON_TLS_CERT_PATH | — | Absolute path to the SMTP TLS certificate chain |
Delivery is accepted only for NoSync accounts; every other account type is refused at RCPT TO. See Embedded SMTP Receiver for authentication, limits, and reply codes. On Pro/Enterprise the same listener also receives SMTP journaling copies, which are configured at runtime rather than through these variables.
OIDC Single Sign-On
Pro edition. See Single Sign-On for the login flow and endpoints.
| Variable | Default | Description |
|---|---|---|
BICHON_OIDC_ENABLED | false | Enable OIDC login |
BICHON_OIDC_ISSUER_URL | — | Issuer URL (e.g. https://keycloak.example.com/realms/myorg) |
BICHON_OIDC_CLIENT_ID | — | Client ID registered with the identity provider |
BICHON_OIDC_CLIENT_SECRET | — | Client secret registered with the identity provider |
BICHON_OIDC_REDIRECT_URI | — | Callback URL registered with the provider (normally https://<host>/api/auth/oidc/callback) |
All five must be set before OIDC login works. There is no WebUI page for these settings.
LDAP / Active Directory
Enterprise edition. See Single Sign-On for the bind flow and JIT provisioning.
| Variable | Default | Description |
|---|---|---|
BICHON_LDAP_ENABLED | false | Enable LDAP bind-based sign-in |
BICHON_LDAP_URL | — | ldap://host:389 or ldaps://host:636 |
BICHON_LDAP_BIND_DN | — | Service-account DN used for the initial search bind |
BICHON_LDAP_BIND_PASSWORD | — | Service-account password |
BICHON_LDAP_BASE_DN | — | Search base DN |
BICHON_LDAP_USER_FILTER | (&(objectClass=person)(sAMAccountName={username})) | User search filter; {username} is replaced |
BICHON_LDAP_SCOPE | subtree | onelevel or subtree |
BICHON_LDAP_USERNAME_ATTRIBUTE | sAMAccountName | Attribute read as the local username |
BICHON_LDAP_SSO_ID_ATTRIBUTE | distinguishedName | Attribute stored as the user's SSO id |
BICHON_LDAP_STARTTLS | false | StartTLS on ldap:// connections |
BICHON_LDAP_NO_TLS_VERIFY | false | Disable certificate verification (private CA only) |
BICHON_LDAP_TIMEOUT_SECS | 10 | LDAP operation timeout in seconds |
Upload Limits
| Variable | Default | Description |
|---|---|---|
BICHON_UPLOAD_BODY_LIMIT_MB | 1100 | Maximum HTTP request body size for uploads (MB) |
BICHON_WEB_MBOX_UPLOAD_LIMIT_MB | 1024 | Maximum per-file MBOX upload size in the WebUI (MB) |
BICHON_WEB_PST_UPLOAD_LIMIT_MB | 2048 | Maximum per-file PST upload size in the WebUI (MB) |
Individual EML files are always capped at 100 MB regardless of these settings.
Pro & Enterprise Settings
These variables are read by bichon-pro-server; the Community binary ignores them.
| Variable | Default | Description |
|---|---|---|
BICHON_ENABLE_IMAP | false | Enable the built-in read-only IMAP server |
BICHON_IMAP_PORT | 10143 | Plain/STARTTLS IMAP port |
BICHON_IMAPS_PORT | 10993 | Implicit-TLS IMAP port |
BICHON_IMAP_ENCRYPTION | none | none, starttls, or tls |
BICHON_ENABLE_MCP | false | Enable the MCP server for AI assistants |
BICHON_AUDIT_RETENTION_DAYS | 0 | Audit-log retention (0 = keep indefinitely) |
BICHON_AUDIT_DETAIL_THRESHOLD | 100 | Batch size at which per-item audit detail moves to a file |
BICHON_BACKUP_DB_SIZE_WARN_MB | 512 | Warn when a backed-up SQLite database exceeds this size |
BICHON_INTEGRITY_SCHEDULE_HOURS | 24 | Hours between scheduled integrity checks (0 disables) |
BICHON_INTEGRITY_RETENTION_DAYS | 90 | Integrity-report retention (0 disables cleanup) |
BICHON_INTEGRITY_MAX_CONCURRENCY | 4 | Parallel integrity workers (0 = unbounded) |
BICHON_INTEGRITY_CLEANUP_INTERVAL_HOURS | 24 | Hours between report-cleanup sweeps |
BICHON_INTEGRITY_FAILURE_DETAIL_MAX | 200 | Failure details kept inline per report |
BICHON_INTEGRITY_FAILURE_FILE_MAX | 1000 | Failure-detail rows kept in the external file |
BICHON_TSP_URL | — | RFC 3161 TSA endpoint (Enterprise); empty disables scheduled anchoring |
BICHON_TSP_INTERVAL_HOURS | 24 | Hours between anchoring cycles |
BICHON_TSP_TSA_CERT | — | Pinned TSA certificate (PEM/DER) used to verify tokens |
BICHON_EXTRACT_FILE_SIZE_LIMIT | 10485760 | Maximum attachment size from which text is extracted, in bytes |
BICHON_EXTRACT_TEXT_LIMIT | 4194304 | Maximum extracted text per attachment, in bytes |
Audit retention, the integrity schedule, and the anchoring interval can also be overridden at runtime from the WebUI via /api/v1/compliance/config; runtime values win over these defaults. See Audit Log & Integrity.
Storage Paths
| Variable | Default | Description |
|---|---|---|
BICHON_INDEX_DIR | {root}/bichon-indices | Tantivy full-text index directory |
BICHON_DATA_DIR | {root}/bichon-storage | bichon-blob storage directory |
Tip: Place
BICHON_INDEX_DIRon fast SSD storage for responsive search, andBICHON_DATA_DIRon high-capacity HDD for cost-effective blob storage.
Important: Bichon does NOT support writing data directly to a network file system (NFS, CIFS/SMB, etc.). All directories must reside on a local file system; otherwise, data corruption may occur.
Performance Tuning
| Variable | Default | Description |
|---|---|---|
BICHON_SYNC_CONCURRENCY | num_cpus × 2 | Max concurrent account sync tasks |
BICHON_IMAP_TIMEOUT_SECONDS | 90 | IMAP socket read timeout in seconds (0 disables it); keep it above the longest expected server silence |