> For the complete documentation index, see [llms.txt](https://docs.seawise.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seawise.io/client/configuration.md).

# Configuration

## Choose a network setup

The client needs to reach your apps. Pick the setup that matches how your apps already run. It decides what you type in the **Host** field when you add an app.

| Setup                                           | Best for                                                               | Host to enter for an app      |
| ----------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------- |
| [Host network](#host-network)                   | Linux, apps installed directly or publishing ports                     | `localhost` / `127.0.0.1`     |
| [Shared Docker network](#shared-docker-network) | \*arr and homelab stacks in Docker Compose                             | Container name, e.g. `sonarr` |
| [Port mapping](#port-mapping)                   | Docker Desktop on Mac / Windows, or when you can't use host networking | `host.docker.internal`        |

Apps on **other devices** on your LAN work in every setup: enter the device's IP, such as `192.168.1.50`.

### Host network

The client shares the host's network, so `localhost` means the machine itself and the web UI is on port 8082 of the host.

```yaml
services:
  seawise:
    image: ghcr.io/seawise-io/seawise-client:latest
    container_name: seawise
    restart: unless-stopped
    network_mode: host
    environment:
      - SEAWISE_HOST_NETWORK=true
    volumes:
      - seawise-data:/config

volumes:
  seawise-data:
```

Add apps as `127.0.0.1` plus the port, for example `127.0.0.1:8096`.

Host networking only works on Linux. On Docker Desktop, use [port mapping](#port-mapping).

### Shared Docker network

If Sonarr, Radarr, Overseerr, Jellyfin, and friends already share a Compose network, put the client on it. Then you add apps by **container name**, the same name you already use in Prowlarr, your download client settings, or a reverse proxy config.

```yaml
services:
  seawise:
    image: ghcr.io/seawise-io/seawise-client:latest
    container_name: seawise
    restart: unless-stopped
    ports:
      - "8082:8082"
    volumes:
      - seawise-data:/config
    networks:
      - media_network

networks:
  media_network:
    external: true    # the network your media stack already uses

volumes:
  seawise-data:
```

Add apps as `sonarr` port `8989`, `overseerr` port `5055`, `jellyfin` port `8096`, and so on. Use the port the app listens on **inside** its container.

> **Apps behind a VPN container (Gluetun):** an app that uses `network_mode: service:gluetun` shares Gluetun's network. Enter `gluetun` as the host, with the app's port. For example qBittorrent is `gluetun:8080`, not `qbittorrent:8080`.

### Port mapping

The client runs on Docker's default network and publishes its web UI port. To reach apps on the same machine, use `host.docker.internal`.

```yaml
services:
  seawise:
    image: ghcr.io/seawise-io/seawise-client:latest
    container_name: seawise
    restart: unless-stopped
    ports:
      - "8082:8082"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - seawise-data:/config

volumes:
  seawise-data:
```

Add apps as `host.docker.internal` plus the port the app publishes on the host.

Docker Desktop provides `host.docker.internal` automatically. On Linux, the `extra_hosts` line (or `--add-host=host.docker.internal:host-gateway` with `docker run`) is required.

> **Don't use `localhost` in this setup.** Inside a container on Docker's default network, `localhost` is the client container itself, so the app won't load. Use `host.docker.internal`, a container name, or a LAN IP.

Start the client with:

```bash
docker compose up -d
```

## Environment variables

Most people don't need any of these.

| Variable                | Default   | What it does                                                                                                                                      |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEAWISE_PORT`          | `8082`    | Port for the client web UI                                                                                                                        |
| `SEAWISE_BIND_ADDR`     | `0.0.0.0` | Address the web UI listens on. Set `127.0.0.1` to allow only local access.                                                                        |
| `SEAWISE_HOST_NETWORK`  | not set   | Set to `true` when using host networking. Turns off the "localhost inside Docker" warning in the logs.                                            |
| `SEAWISE_TLS`           | not set   | Set to `auto` to serve the web UI over HTTPS with a self-signed certificate                                                                       |
| `SEAWISE_TRUST_PROXY`   | `false`   | Set to `true` if the web UI sits behind your own reverse proxy, so failed-login delays apply per visitor                                          |
| `SEAWISE_ALLOWED_HOSTS` | not set   | Extra hostnames allowed to open the web UI, comma separated, e.g. `seawise.home.lan`. IP addresses, `localhost`, and `*.local` names always work. |
| `SEAWISE_LOG_LEVEL`     | `info`    | `debug`, `info`, `warn`, or `error`                                                                                                               |
| `PUID` / `PGID`         | `1000`    | User and group the client runs as, for file ownership in `/config`. Running as root (`0`) is not allowed.                                         |

To change the web UI port with port mapping, change both sides:

```yaml
ports:
  - "9090:9090"
environment:
  - SEAWISE_PORT=9090
```

## Health checks

The client exposes two endpoints on its web UI port, handy for uptime monitors:

| Endpoint   | Returns                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------- |
| `/healthz` | `200` while the client is running                                                        |
| `/readyz`  | `200` when the client is connected to your account and the tunnel is up, otherwise `503` |

The image also has a built-in Docker `HEALTHCHECK`, so `docker ps` shows `healthy` or `unhealthy`.

## Platform notes

**Unraid**: Docker tab → **Add Container**. Repository `ghcr.io/seawise-io/seawise-client:latest`, network type **Host** (or a custom network shared with your apps), and a path mapping from `/mnt/user/appdata/seawise` to `/config`. If you use Host, add the variable `SEAWISE_HOST_NETWORK=true`.

**Synology**: Container Manager → **Project** → **Create**, and paste one of the Compose files above. Map `/config` to a folder such as `/volume1/docker/seawise`.

**TrueNAS SCALE**: Apps → **Discover Apps** → **Custom App**. Use the image above, mount a dataset at `/config`, and either enable host networking or publish port `8082`.

**Raspberry Pi**: use a 64-bit OS (Raspberry Pi OS 64-bit or Ubuntu). The Linux command works as is.