Source: https://help.spamfoo.com/guides/install
Last updated: 2026-10-27

***

# Install SpamFoo Client

This page shows how to install SpamFoo Client on your mail server or next to it, add your license key, sign in to the dashboard, and check that it works.

> **Note:** If you use SmarterMail, you can skip this page. SmarterMail downloads, sets up, and updates SpamFoo Client for you. See [Set Up SmarterMail](https://help.spamfoo.com/integrations/smartermail/setup). Use this page only if you want SpamFoo Client on its own server. See [Use SpamFoo Client on Another Server](https://help.spamfoo.com/integrations/smartermail/setup#external-client).

## Before You Start

- Check that your server meets the [System Requirements](https://help.spamfoo.com/guides/system-requirements).
- Make sure you can sign in to the server as an administrator (Windows) or as root (Linux).
- Get your license key. [Sign in to your SpamFoo account](https://www.spamfoo.com/account/login), go to **Licenses**, and open your license. Copy the key and save it in a file on the server, such as `/root/spamfoo-key.txt`, or click **Download sf.key**.
- The [Downloads](https://www.spamfoo.com/account/downloads) page in your SpamFoo account has the install commands and the current files for each kind of install. Get every SpamFoo Client download there.

## Choose How to Install

- **[Docker](https://help.spamfoo.com/guides/install#docker):** runs on any Linux host with Docker. Everything SpamFoo Client keeps is stored in one volume.
- **[Archive](https://help.spamfoo.com/guides/install#tarball):** a zip file for Windows, or a tarball for Linux systems the package doesn't support. You set up the service yourself.

The Linux package, the Docker steps, and the Linux archive steps on this page run SpamFoo Client in **standalone mode**, the mode for a SpamFoo Client that runs on its own instead of being started by SmarterMail.

For the difference, see [Mode](https://help.spamfoo.com/guides/configure#mode) in Configure SpamFoo Client.

## Install With Docker

The [Downloads](https://www.spamfoo.com/account/downloads) page in your SpamFoo account shows these steps and the current version. The `spamfoo/spamfoo-client` image runs on Linux hosts with x86_64 processors. Everything SpamFoo Client keeps is stored in one volume mounted at `/data`.

### Start It With Docker Compose

1. In an empty folder, create a file named `spamfoo.env` with your license key, and keep it private:

   ```
   SPAMFOO_LICENSE_KEY=paste-your-license-key-here
   ```

   ```
   chmod 600 spamfoo.env
   ```
2. Save this as `compose.yml` next to it:

   ```
   name: spamfoo
   services:
     spamfoo-client:
       container_name: spamfoo-client
       image: spamfoo/spamfoo-client:latest
       restart: unless-stopped
       stop_grace_period: 30s
       env_file: spamfoo.env
       environment:
         SPAMFOO_MODE: standalone
         SPAMFOO_PUBLIC_URL: http://127.0.0.1:16253
       ports:
         - "127.0.0.1:16253:16253"
       volumes:
         - spamfoo-data:/data
   volumes:
     spamfoo-data: {}
   ```
3. Start it:

   ```
   docker compose up -d
   ```
4. Make a one-time sign-in link, open it, and click **Continue**:

   ```
   docker compose exec spamfoo-client spamfoo-client login-link
   ```

Each part of the compose file matters:

- `SPAMFOO_MODE: standalone` turns on standalone mode. The image doesn't set it, so a container started without it runs the way older versions did.
- `restart: unless-stopped` starts SpamFoo Client again when it stops to recover from some errors.
- `stop_grace_period: 30s` gives SpamFoo Client time to finish the messages it's scanning. Docker's default of 10 seconds is too short.
- The port is published on `127.0.0.1`, so only the Docker host can connect.
- `SPAMFOO_PUBLIC_URL` is the address in sign-in links. Change it if you open the dashboard at another address.

To add the license key later instead of in `spamfoo.env`, save it in a file and run:

```
docker compose exec -T spamfoo-client spamfoo-client activate --stdin < spamfoo-key.txt
```

It takes effect without a restart.

### Start It With docker run

Use the same `spamfoo.env` file without Compose:

```
docker run -d --name spamfoo-client --restart unless-stopped --stop-timeout 30 \
    -e SPAMFOO_MODE=standalone --env-file spamfoo.env \
    -p 127.0.0.1:16253:16253 -v spamfoo-data:/data \
    spamfoo/spamfoo-client:latest
```

Then make a sign-in link with `docker exec spamfoo-client spamfoo-client login-link --url=http://127.0.0.1:16253`.

### Set the Proxy Secret

The proxy secret is the password your mail server sends with every request. If you don't set one, SpamFoo Client creates a random one in `/data/etc/sf.proxysecret` the first time it starts. To choose your own, add `SPAMFOO_PROXY_SECRET=your-secret` to `spamfoo.env` before the first start. See [Proxy Secret](https://help.spamfoo.com/guides/configure#proxy-secret).

### Accept Mail From Other Servers

To let a mail server on another machine reach the container, publish the port on an address that machine can reach, such as `"16253:16253"` in the compose file or `-p 16253:16253` with `docker run`. Then allow only your mail servers through the host's firewall.

> **Warning** Do not open the SpamFoo Client port to the internet. Allow only your mail servers to reach it.

### Use a Folder on the Host

The container runs as user ID 10001. If you mount a host folder instead of a named volume, give that user the folder first:

```
sudo mkdir -p /srv/spamfoo
sudo chown -R 10001:10001 /srv/spamfoo
```

Then use `/srv/spamfoo:/data` as the volume.

### Pick an Image Tag

- `latest` is always the newest release.
- A version tag, such as `1.2.3`, stays on that release.
- A major or minor tag, such as `1` or `1.2`, moves to the newest release in that line.

To update, see [Update Docker](https://help.spamfoo.com/guides/updates#update-docker).

## Install From the Archive

Choose your platform.

### Windows

#### Extract and Add Your License Key

1. Download `spamfoo-client-<version>-windows-x64.zip` from the [Downloads](https://www.spamfoo.com/account/downloads) page in your SpamFoo account.
2. Extract the zip archive to the folder you want to install to, such as `C:\SpamFoo`.
3. Create a folder named `etc` inside the install folder.
4. Copy `sf.key` into the `etc` folder, so its path is `C:\SpamFoo\etc\sf.key`.

You can set the `SPAMFOO_LICENSE_KEY` environment variable to your license key instead. If both are set, the environment variable is used.

#### Start SpamFoo Client

1. Open PowerShell as an administrator.
2. Start SpamFoo Client:

   ```
   cd C:\SpamFoo
   .\spamfoo-client.exe
   ```

SpamFoo Client starts and listens at `http://localhost:16253`. It stops when you close the window.

> **Note** When SpamFoo Client installs a program update, it stops and does not start itself again. Start it again after an update. See [Update and Back Up](https://help.spamfoo.com/guides/updates#client-updates).

### Linux

Use the tarball on Linux systems the package doesn't support. Download `spamfoo-client-<version>-linux-x64.tar.gz` from the [Downloads](https://www.spamfoo.com/account/downloads) page in your SpamFoo account, and check that its SHA-256 hash matches the one on that page:

```
sha256sum spamfoo-client-<version>-linux-x64.tar.gz
```

#### Unpack the Files

Create the service user and folders, then unpack the files:

```
sudo useradd --system --home-dir /var/lib/spamfoo --shell /usr/sbin/nologin spamfoo
sudo mkdir -p /opt/spamfoo /var/lib/spamfoo /etc/spamfoo
sudo tar -xzf spamfoo-client-<version>-linux-x64.tar.gz -C /opt/spamfoo
sudo chown -R spamfoo:spamfoo /opt/spamfoo /var/lib/spamfoo
sudo chmod 0750 /var/lib/spamfoo
```

The `spamfoo` user must own `/opt/spamfoo`, because SpamFoo Client updates its own program files there.

#### Create the Settings File

Create `/etc/spamfoo/spamfoo.conf` with these settings. Add any other settings from [Configure SpamFoo Client](https://help.spamfoo.com/guides/configure) the same way.

```
SPAMFOO_MODE=standalone
SPAMFOO_BIND_ADDRESS=127.0.0.1
```

Then let the service user read it:

```
sudo chown root:spamfoo /etc/spamfoo/spamfoo.conf
sudo chmod 0640 /etc/spamfoo/spamfoo.conf
```

#### Add Your License Key

```
sudo /opt/spamfoo/spamfoo-client activate --data-dir=/var/lib/spamfoo --file=/root/spamfoo-key.txt
```

#### Run as a systemd Service

1. Create the file `/etc/systemd/system/spamfoo-client.service` with this content:

   ```
   [Unit]
   Description=SpamFoo Client
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   Type=simple
   User=spamfoo
   Group=spamfoo
   EnvironmentFile=-/etc/spamfoo/spamfoo.conf
   ExecStartPre=/bin/sh -c 'while [ -e /opt/spamfoo/updates/update.lock ]; do sleep 1; done'
   ExecStart=/opt/spamfoo/spamfoo-client run --mode=standalone --data-dir=/var/lib/spamfoo
   WorkingDirectory=/var/lib/spamfoo
   Restart=always
   RestartSec=5s
   RestartPreventExitStatus=78
   TimeoutStopSec=30
   KillMode=process
   
   [Install]
   WantedBy=multi-user.target
   ```
2. Turn on and start the service:

   ```
   sudo systemctl daemon-reload
   sudo systemctl enable --now spamfoo-client
   ```
3. Make a one-time sign-in link, open it, and click **Continue**:

   ```
   sudo /opt/spamfoo/spamfoo-client login-link --data-dir=/var/lib/spamfoo
   ```

Some lines in the service file matter:

- `Restart=always` starts SpamFoo Client again after it stops to install an update.
- `KillMode=process` lets the update finish after SpamFoo Client stops.
- `ExecStartPre` waits until an update has finished replacing the program files.
- `RestartPreventExitStatus=78` stops systemd from restarting SpamFoo Client over and over when a setting is wrong. See [It Stops With a Settings Error](https://help.spamfoo.com/guides/common-problems#config-error).

## Check the Install

SpamFoo Client downloads its models the first time it starts with a license key. This can take a few minutes.

1. On the server, check that SpamFoo Client is ready to classify mail:

   ```
   curl http://localhost:16253/health/ready
   ```

   The answer is `{"status":"ready","contract":1}` when it's ready. Until then, it lists the reasons, such as `models_loading` or `not_activated` (no license key). See [Check Health](https://help.spamfoo.com/api/health#ready). With the Linux package or Docker, you can run `spamfoo-client status` instead.
2. Sign in to the dashboard with a sign-in link, as shown above, or open `http://localhost:16253/admin/` and paste the proxy secret.
3. Go to **System > Status**.
4. Check that the status line at the top says **API connected**.
5. Check that the **License** card shows your plan with the status **Active**.
6. Check that the **Versions** card lists a version for the client and for each model.

The proxy secret is a random password SpamFoo Client creates the first time it starts, unless you set `SPAMFOO_PROXY_SECRET`. Find it here:

| Install | Proxy Secret |
| --- | --- |
| Linux package or Linux archive | `/var/lib/spamfoo/etc/sf.proxysecret` |
| Docker | The value you set in `SPAMFOO_PROXY_SECRET`. If you didn't set one, run `docker compose exec spamfoo-client cat /data/etc/sf.proxysecret`. |
| Windows | `C:\SpamFoo\etc\sf.proxysecret` |

If the dashboard doesn't load, check that SpamFoo Client is running and look at the log files in the `logs` folder of the data directory. See [Fix Common Problems](https://help.spamfoo.com/guides/common-problems) and [Monitor Logs and Health](https://help.spamfoo.com/guides/monitoring).

## Next Steps

1. Review the settings in [Configure SpamFoo Client](https://help.spamfoo.com/guides/configure).
2. Connect your mail server. See [How Integration Works](https://help.spamfoo.com/integrations).
3. Send a test message and find it in the admin console. See [Use the Admin Console](https://help.spamfoo.com/guides/admin-console).