Source: https://help.spamfoo.com/guides/configure Last updated: 2026-10-27 *** # Configure SpamFoo Client SpamFoo Client reads some settings from environment variables, command-line options, a settings file, and a few files in its data directory when it starts. This page lists those settings and their defaults. Settings you change on **System > Settings** in the admin console, or with the settings API, are listed in [Read and Change Settings](https://help.spamfoo.com/api/settings#setting-keys). > **Note:** If you use SmarterMail, it does most of this configuration for you, including the license, folders, and updates. See [Set Up SmarterMail](https://help.spamfoo.com/integrations/smartermail/setup). ## How Settings Are Applied - **Environment variables, command-line options, and the settings file:** read when SpamFoo Client starts. Restart SpamFoo Client after you change one. - **The license key file and the proxy secret file:** changes are picked up while SpamFoo Client runs in some cases. See [License Key](https://help.spamfoo.com/guides/configure#license-key) and [Proxy Secret](https://help.spamfoo.com/guides/configure#proxy-secret). - **Settings page and settings API:** changes apply right away. Saving the Settings page saves every value shown on it, not just the one you changed. See [Read and Change Settings](https://help.spamfoo.com/api/settings#change-settings). When the same setting is set in more than one place, SpamFoo Client uses the first one it finds in this order: 1. A value saved on the Settings page or with the settings API 2. An environment variable 3. A line in the [settings file](https://help.spamfoo.com/guides/configure#settings-file) 4. A command-line option, or a file in the `etc` folder of the data directory 5. The default There are two exceptions: - The `--mode`, `--port`, and `--conf` command-line options win over their environment variables and the settings file. - When the `SPAMFOO_GPU` environment variable is set, it overrides the **GPU Acceleration** switch on the Settings page. If a setting has a value SpamFoo Client can't use, such as an unknown mode or a port that isn't a number, SpamFoo Client prints a line that starts with `FATAL` and stops with exit code 78. See [It Stops With a Settings Error](https://help.spamfoo.com/guides/common-problems#config-error). ## Mode SpamFoo Client runs in one of two modes. The mode is set when it starts, with `SPAMFOO_MODE` or [`--mode`](https://help.spamfoo.com/guides/configure#mode-option). - **Embedded** (the default): the mode SmarterMail uses, and the mode of any install that doesn't set one. - **Standalone:** for SpamFoo Client running on its own. The Linux package uses it, and the Docker and Linux archive steps in [Install SpamFoo Client](https://help.spamfoo.com/guides/install) turn it on. In standalone mode, SpamFoo Client works differently in these ways: - **Proxy secret:** every caller needs the proxy secret, even a program on the same server. Health checks are the only exception. In embedded mode, programs on the same server can classify mail without it. - **Failed sign-ins:** after a certain number of wrong proxy secrets or sign-in links from one IP address within a short time, that address is blocked for several minutes. Its requests get HTTP 429. - **Changing the secret:** a new value in `etc/sf.proxysecret` takes effect within a few seconds, with no restart. See [Change the Secret](https://help.spamfoo.com/guides/roles#change-the-secret). - **License key:** SpamFoo Client starts and waits when there's no key. It picks up a key you add later without a restart. - **Largest message:** the default limit is 64 MB instead of 520 MB. See [Largest Message](https://help.spamfoo.com/guides/configure#largest-message). - **Port and public address:** [Port](https://help.spamfoo.com/guides/configure#port) and [Public URL](https://help.spamfoo.com/guides/configure#public-url) only apply in standalone mode. In embedded mode the port is always 16253. - **Message files:** messages waiting to be scanned are written to the `spool` folder in the data directory, instead of the system's temporary folder. See [Spool Folder](https://help.spamfoo.com/guides/configure#spool-folder). - **File permissions:** on Linux and macOS, SpamFoo Client makes the `etc` folder and the database readable only by the account that runs it. - **Logs:** log lines are also written to the console, so they show up in `journalctl` or `docker logs`. - **Address map:** a mail server can send which mailboxes it has and which addresses deliver to each one. See [Push an Address Map](https://help.spamfoo.com/api/address-map). ## Settings File SpamFoo Client can read startup settings from a file named `spamfoo.conf`. The Linux package creates one at `/etc/spamfoo/spamfoo.conf`. SpamFoo Client uses the first file it finds: 1. The file named by `--conf` or `SPAMFOO_CONF`. SpamFoo Client won't start if that file doesn't exist. 2. `spamfoo.conf` in the data directory (`/data/spamfoo.conf` in Docker). 3. On Linux, `/etc/spamfoo/spamfoo.conf`. Each line sets one environment variable from this page: ``` # Lines that start with # are comments. SPAMFOO_MODE=standalone SPAMFOO_BIND_ADDRESS=127.0.0.1 SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY=4 ``` - Only names that start with `SPAMFOO_` are read. Other lines are ignored with a warning. - A line only applies when the same environment variable isn't already set. - Quotes around a value are removed. If a name appears twice, the last line wins. - Restart SpamFoo Client after you change the file. The same file works as a systemd `EnvironmentFile` or a Docker `--env-file`. The `spamfoo-client` commands read it too, so they use the same data directory, port, and public address as the service. ## Command-Line Options Add command-line options after the program name when you start SpamFoo Client. Write each one with an equals sign, such as `--data-dir=/var/lib/spamfoo`. In paths, `~` means your home folder. ``` ./spamfoo-client --data-dir=/var/lib/spamfoo --models-dir=/var/lib/spamfoo/models ``` The program also has commands for tasks such as adding a license key or making a sign-in link. See [Use SpamFoo Client Commands](https://help.spamfoo.com/guides/commands). #### Data Directory `--data-dir=` The directory that holds the database, license key, proxy secret, personalization data, backups, and logs. See [Data Directory](https://help.spamfoo.com/guides/configure#data-directory). Default: the install folder (`/data` in Docker) #### Models Folder `--models-dir=` The folder where downloaded models are stored. You can also set it with the `SPAMFOO_MODELS` environment variable, which wins over the option. It is only used if the folder already exists. Default: `/trained-models` #### Mode `--mode=` `embedded` or `standalone`. See [Mode](https://help.spamfoo.com/guides/configure#mode). You can also set it with the `SPAMFOO_MODE` environment variable. The option wins if both are set. Default: `embedded` #### Port `--port=` The port SpamFoo Client listens on. Standalone mode only. You can also set it with the `SPAMFOO_PORT` environment variable. The option wins if both are set. Default: 16253 #### Settings File `--conf=` The settings file to read. See [Settings File](https://help.spamfoo.com/guides/configure#settings-file). You can also set it with the `SPAMFOO_CONF` environment variable. The option wins if both are set. Default: `spamfoo.conf` in the data directory, then `/etc/spamfoo/spamfoo.conf` on Linux ## Environment Variables Each setting below shows its environment variable. A few of them, such as the scan queue settings, can also be saved on the Settings page or with the settings API, and a saved value wins. ### Folders #### NVIDIA Libraries Folder `SPAMFOO_RUNTIME` The folder for the NVIDIA libraries that GPU acceleration downloads. Default: `/runtime` #### Spool Folder `SPAMFOO_SPOOL_DIR` The folder where messages are written while they wait to be scanned. Standalone mode only. SpamFoo Client deletes leftover files in it when it starts. In embedded mode, the system's temporary folder is used. Default: `/spool` ### License and Access #### License Key `SPAMFOO_LICENSE_KEY` Your license key. You can also save the key in `etc/sf.key` in the data directory, or with [`spamfoo-client activate`](https://help.spamfoo.com/guides/commands#activate). The environment variable wins if both are set. SpamFoo Client watches `etc/sf.key` and uses a changed key within a few seconds, with no restart. In embedded mode, this works only if SpamFoo Client had a key when it started. Otherwise, restart it after you add the key. #### Proxy Secret `SPAMFOO_PROXY_SECRET` The password you paste to sign in to the admin console. Mail servers and scripts send it with every request. If you choose your own, use at least 32 characters from `A-Z a-z 0-9 - _`, with no spaces before or after it. Letter case matters. You can also save it in `etc/sf.proxysecret` in the data directory. The environment variable wins if both are set. In standalone mode, a new value in the file takes effect within a few seconds. See [Change the Secret](https://help.spamfoo.com/guides/roles#change-the-secret). Default: a random value SpamFoo Client creates and saves in `etc/sf.proxysecret` when it first starts ### Network #### Listen Address `SPAMFOO_BIND_ADDRESS` The network address SpamFoo Client listens on. Use `0.0.0.0` to accept connections from other machines. SpamFoo Client serves HTTP only. Default: `localhost` (`0.0.0.0` in Docker, `127.0.0.1` in the Linux package's settings file) #### Port `SPAMFOO_PORT` The port SpamFoo Client listens on, from 1 to 65535. Standalone mode only. In embedded mode the port is always 16253. You can also set it with the [`--port`](https://help.spamfoo.com/guides/configure#port-option) option, which wins. Default: 16253 #### Public URL `SPAMFOO_PUBLIC_URL` The address people use to reach SpamFoo Client, such as `http://spamfoo.example.com:16253`. Sign-in links start with it. It must start with `http://` or `https://`. Standalone mode only. Without it, a sign-in link made by the dashboard or the API uses the address the request came to, and one made by `spamfoo-client login-link` uses `http://localhost` and the port. > **Warning** Do not open the SpamFoo Client port to the internet. Allow only your mail servers to reach it. ### Updates #### Update Check Interval `SPAMFOO_UPDATE_INTERVAL_HOURS` How often SpamFoo Client checks for new models and program updates, in hours. Default: 6 hours #### Automatic Program Updates `SPAMFOO_DISABLE_BINARY_UPDATE` Whether SpamFoo Client replaces its own program files when a new version is available. Set the variable to `true` to turn this off. Model updates still run. Program updates are always off in a Docker container running in standalone mode and with the Linux package, which you upgrade with its install script. Default: `false` (`true` in Docker and with the Linux package) #### Install Kind `SPAMFOO_INSTALL_KIND` How SpamFoo Client was installed: `package`, `container`, `portable` (an archive), or `sidecar`. Standalone mode only. It decides whether program updates run, and it's shown on your license in your SpamFoo account. Set it only if SpamFoo Client guesses wrong. Default: `container` inside a container, `package` when the program is in `/opt/spamfoo/client`, and `portable` otherwise #### SpamFoo API Timeout `SPAMFOO_TIMEOUT` How long SpamFoo Client waits for SpamFoo's servers to answer, in seconds. Default: 30 seconds ### Scan Queue SpamFoo Client scans a limited number of messages at once. Other messages wait in a queue. There are two queues that share the same slots: - **Spool queue:** messages being delivered right now. These get first claim on the slots. - **Background queue:** requests that only sort mail into Email Classifications, without spam checks. See [Classify Without Spam Checks](https://help.spamfoo.com/api/classify-tabs). #### Max Concurrency `SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY` How many messages are scanned at once, shared by both queues. Each message being scanned can keep one processor core fully busy. See [Concurrency](https://help.spamfoo.com/guides/configure#concurrency). Default: 2 (range 1 to 32) #### Queue Timeout `SPAMFOO_CLASSIFICATION_QUEUE_TIMEOUT_SECONDS` How long a message can wait for a slot before SpamFoo Client returns an error (HTTP 503), in seconds. See [Timeouts](https://help.spamfoo.com/guides/configure#timeouts). Default: 30 seconds #### Spool Queue Timeout `SPAMFOO_SPOOL_TIMEOUT_SECONDS` A separate wait limit for the spool queue, in seconds. Once you save the Settings page, the saved **Queue Timeout** replaces `SPAMFOO_SPOOL_TIMEOUT_SECONDS`. To keep a separate limit after that, set it with the [settings API](https://help.spamfoo.com/api/settings#spool-queue-timeout). Default: same as Queue Timeout #### Background Queue Slots `SPAMFOO_BACKGROUND_MAX_CONCURRENCY` The most slots the background queue can use. It can never take every slot. Default: one less than Max Concurrency, at least 1 #### Background Queue Timeout `SPAMFOO_BACKGROUND_TIMEOUT_SECONDS` A separate wait limit for the background queue, in seconds. Once you save the Settings page, the saved **Queue Timeout** replaces `SPAMFOO_BACKGROUND_TIMEOUT_SECONDS`. To keep a separate limit after that, set it with the [settings API](https://help.spamfoo.com/api/settings#background-queue-timeout). Default: 120 seconds, or Queue Timeout once you save the Settings page ### Request Limits These limits protect the server from very large or very many requests. The defaults are set high so that normal mail is never turned away. #### Largest Message `SPAMFOO_MAX_CLASSIFY_BODY_BYTES` The largest message SpamFoo Client accepts, in bytes. Larger messages get an error (HTTP 413). To protect memory from very large messages, lower it, for example to `33554432` (32 MB). Default: `545259520` (520 MB), or `67108864` (64 MB) in standalone mode #### Messages Held at Once `SPAMFOO_MAX_CLASSIFY_INFLIGHT` The most messages SpamFoo Client holds at once, scanning or waiting. Extra requests get an error (HTTP 503). Default: 1024 #### Intake Wait `SPAMFOO_CLASSIFY_INTAKE_TIMEOUT_MS` How long a request waits for room under **Messages Held at Once**, in milliseconds. Default: 250 milliseconds ### Model Processing #### Model Threads `SPAMFOO_ONNX_THREADS` How many processor threads the models share. Default: about half the processor cores (1 on servers with 2 cores or fewer) #### GPU Acceleration `SPAMFOO_GPU` Set to `true` to always run the text model on an NVIDIA GPU, or `false` to always use the processor. When it's set, it overrides the **GPU Acceleration** switch on the Settings page. See [Turn On GPU Acceleration](https://help.spamfoo.com/guides/gpu-acceleration), which also lists the other GPU variables. ## Change Other Settings Data retention, backups, display, and the other settings not listed here are changed on **System > Settings** in the admin console, or with the settings API. For each one, its place on the Settings page, its settings API key, and its default, see [Read and Change Settings](https://help.spamfoo.com/api/settings#setting-keys). ## Data Directory SpamFoo Client keeps its data in the data directory. This is the install folder unless you set [`--data-dir`](https://help.spamfoo.com/guides/configure#data-directory-location). In Docker it's `/data`, and with the Linux package it's `/var/lib/spamfoo`. The **Storage** card on **System > Status** shows the exact paths. ``` / backups/ Nightly backups correction_archive/ Corrections reported from this server etc/ License key, proxy secret, release channel, installation ID, and encryption keys logs/ Log files personalization/ Each user's rules and learned preferences runtime/ NVIDIA libraries (only with GPU acceleration) spool/ Messages waiting to be scanned (standalone mode only) trained-models/ Downloaded models (downloaded again if missing) admin.db Settings, scan history, and totals address-map.json The address map a mail server pushed domain_age.db Saved domain ages spamfoo.conf Startup settings, if you created this file update-status.json The result of the last install script upgrade (Linux package only) ``` To learn what to back up, see [Update and Back Up](https://help.spamfoo.com/guides/updates#backup). ## Tune Performance The defaults keep processor and memory use low, which suits most mail servers. Change them only if messages wait too long to be scanned or the server is dedicated to email scanning. ### Concurrency [Max Concurrency](https://help.spamfoo.com/guides/configure#max-concurrency) sets how many messages are scanned at once. A higher value lets busy servers keep up, but uses more memory and processor time. On servers with few processor cores, a value of 1 can work better. After a change, watch the **Memory** and **CPU** tiles on **System > Status**. ### Speedup Optimizations [Enable Speedup Optimizations](https://help.spamfoo.com/api/settings#enable-speedup-optimizations) lets SpamFoo Client use more processor and memory to scan each message faster. It's off by default and applies to the next message scanned, with no restart. > **Warning** Turn this on only if the server is dedicated to SpamFoo Client or has a lot of unused processor and memory. It can take processor time and memory that your mail server needs. - **What it does:** the text model gets its own set of threads that can use every processor core, and the model runtime turns on extra optimizations. - **Processor:** while a message is scanned, SpamFoo Client can use every core. On a busy mail server this competes with mail delivery. - **Memory:** the models keep memory between messages instead of releasing it, so memory use goes up and stays up. - **Concurrency:** each message can already use every core, so a high Max Concurrency can make scanning slower. Start at 2. - **GPU servers:** it also changes how GPU memory is managed. Watch memory after you turn it on. To see the effect, compare **Average Scan Time** on the **Mail Health** page before and after. If delivery slows down or memory runs short, turn it off. If the server has an NVIDIA GPU, [GPU acceleration](https://help.spamfoo.com/guides/gpu-acceleration) is usually a better choice: - The text model does the same small math many thousands of times. A GPU is built to do that kind of work all at once. - The work moves off the processor, so scanning and mail delivery stop competing for the same cores. ### Timeouts Your mail server waits a limited time for each scan. **Queue Timeout** only covers the time a message waits for a free slot, and the scan takes more time after that. Set **Queue Timeout** a few seconds below your mail server's limit. Then, when SpamFoo Client is too busy, it returns an error (HTTP 503) that your mail server can handle, instead of the mail server cutting off the request. ## Configure Docker In Docker, pass environment variables with `-e`, or list them in an env file. The image already sets these: - `SPAMFOO_BIND_ADDRESS=0.0.0.0`, so your mail server can reach the container - `SPAMFOO_DISABLE_BINARY_UPDATE=true`, so you update by pulling a new image - The data directory is `/data`, so the models, settings, and history are all stored on the volume The image doesn't set `SPAMFOO_MODE`, so a container runs in embedded mode unless you set it. Pulling a newer image never changes the mode of a container you already run. To use standalone mode, add `SPAMFOO_MODE=standalone`, as in [Install With Docker](https://help.spamfoo.com/guides/install#docker). ``` docker run -d --name spamfoo-client --restart unless-stopped --stop-timeout 30 \ -e SPAMFOO_MODE=standalone --env-file spamfoo.env \ -e SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY=4 \ -p 127.0.0.1:16253:16253 -v spamfoo-data:/data \ spamfoo/spamfoo-client:latest ``` Settings you save on the Settings page or through the settings API are kept in `/data`, so they survive when you replace the container. A `spamfoo.conf` file in `/data` is also read when the container starts. ## Next Steps - Connect your mail server. See [How Integration Works](https://help.spamfoo.com/integrations). - Learn the admin console. See [Use the Admin Console](https://help.spamfoo.com/guides/admin-console). - Plan updates and backups. See [Update and Back Up](https://help.spamfoo.com/guides/updates).