# How to Install Homebridge on a Synology NAS (https://docs.homemanager-app.de/guide/install-synology)





A Synology DiskStation works well as a Homebridge host: The NAS runs continuously, usually connects to your router over Ethernet, and saves having a separate server.

This guide covers setup on DiskStations running **DSM 7 (DSM 7.0 through DSM 7.2 and newer)**.

<Cards>
  <Card icon="<HelpCircle />" title="Still deciding on hardware?" description="If you are weighing whether a Synology NAS, a Raspberry Pi, or a Mac fits your setup best, check out our hardware comparison guide." href="/guide/choose-your-system" />
</Cards>

<div className="my-6" />

<Accordions>
  <Accordion title="Still using DSM 6? Here are your options">
    The modern native Homebridge package requires DSM 7 and Node.js 22 from Synology. If your DiskStation still runs DSM 6, you have three options depending on your hardware:

    1. **Upgrade to DSM 7 (Recommended):**\
       Nearly all DiskStations from model year 2013 or 2015 onward support DSM 7. Check in DSM under **Control Panel > Update & Restore** to see if an update is available. Once upgraded, follow the native package guide below.
    2. **Use the Docker package on Plus models (Intel or AMD):**\
       If you run a Plus model and stay on DSM 6, install the **Docker** package from Package Center (the earlier version of Container Manager). Configuration using host networking matches the Docker section below.
    3. **Older entry-level models (without DSM 7 or Docker support):**\
       Units such as the DS213j, DS214se, or DS115j did not receive DSM 7 and lack container support. Current Node.js releases cannot run on this hardware. In this case, a dedicated [Raspberry Pi 4 or 5](/guide/install-raspberry-pi) is the practical alternative.
  </Accordion>
</Accordions>

***

## Which installation method fits your NAS? [#which-installation-method-fits-your-nas]

You have two options on a Synology DiskStation:

* **Native DSM Package (Recommended for most users):**\
  Installs through the DSM Package Center and runs on almost all DiskStations with DSM 7, including the j-, Value-, and Play-series. It requires neither Docker nor terminal experience, runs as a background service, and is maintained directly by the Homebridge project.

* **Container Manager / Docker (For users with an existing container setup):**\
  Available on Plus- and XS-series models with Intel or AMD processors. This route is convenient if you already manage other services using Docker Compose.

***

## Method 1: Installing as a Native DSM Package (Recommended) [#method-1-installing-as-a-native-dsm-package-recommended]

The native package integrates Homebridge directly into DSM and creates a folder on your primary storage volume for configuration and plugin data.

<Steps>
  <Step>
    ### Install Node.js 22 from Package Center [#install-nodejs-22-from-package-center]

    Homebridge relies on a current Node.js runtime, which Synology provides in Package Center:

    1. Open your NAS web desktop in a browser.
    2. Launch **Package Center**.
    3. Search for **Node.js**.
    4. Click **Install** next to the **Node.js v22** package.
  </Step>

  <Step>
    ### Download the Matching Package (.spk) [#download-the-matching-package-spk]

    The Homebridge project provides precompiled packages (`.spk`) tailored to the processor architecture of each Synology series:

    1. Open the project download directory: [synology.homebridge.io](https://synology.homebridge.io).
    2. Download the file that matches your DiskStation architecture:

    | Processor Platform               | Typical DiskStation Models                                        | Package File                   |
    | :------------------------------- | :---------------------------------------------------------------- | :----------------------------- |
    | **x86\_64** (Intel / AMD 64-Bit) | DS224+, DS220+, DS720+, DS920+, DS423+, DS1522+, DS1621+, DS1821+ | `homebridge-x86_64-...spk`     |
    | **rtd1619b** (Realtek armv8)     | DS223, DS223j, DS124, DS423                                       | `homebridge-rtd1619b-...spk`   |
    | **rtd1296** (Realtek armv8)      | DS220j, DS420j, DS218, DS218play, DS118, RS819                    | `homebridge-rtd1296-...spk`    |
    | **armada37xx** (Marvell armv8)   | DS120j, DS119j                                                    | `homebridge-armada37xx-...spk` |
    | **armada38x** (Marvell armv7)    | DS218j, DS419slim, DS216, DS216j, DS116, RS217                    | `homebridge-armada38x-...spk`  |
    | **alpine** (Annapurna armv7)     | DS1817, DS1517, DS416, DS1515, DS715, DS215+                      | `homebridge-alpine-...spk`     |
    | **evansport** (Intel 32-Bit)     | DS214play, DS414play, DS415play                                   | `homebridge-evansport-...spk`  |

    <Callout type="info">
      If your model is not listed above, check **Control Panel > Info Center** in DSM. The **Processor** field displays your device's exact CPU type.
    </Callout>

    <Callout type="tip">
      **Alternative: Add Package Source**\
      Instead of downloading the package manually, you can add `https://synology.homebridge.io` under **Package Center > Settings > Package Sources**. Homebridge will then appear directly in Package Center searches under *Community*.
    </Callout>
  </Step>

  <Step>
    ### Install the Package Manually in DSM [#install-the-package-manually-in-dsm]

    1. In **Package Center**, click **Manual Install** in the top right corner.
    2. Click **Browse** and select the downloaded `.spk` file.
    3. Acknowledge the third-party package notice by clicking **Agree**.
    4. Ensure *Run after installation* is checked, then click **Done**.

    The package registers the background service automatically and stores configuration files and plugin data under `/volume1/homebridge`.

    <Callout type="info">
      On entry-level units such as the DS120j or DS223j, the first startup can take several minutes while initial dependencies unpack and start.
    </Callout>
  </Step>
</Steps>

***

## Method 2: Container Manager (Docker) for Plus Models [#method-2-container-manager-docker-for-plus-models]

If you operate a Plus- or XS-series model with an Intel or AMD processor and prefer containerized workflows, you can run Homebridge in the Synology Container Manager.

<Callout type="important">
  Always use host networking (`network_mode: host`) for the container. In standard isolated bridge networks, mDNS discovery packets (Bonjour) cannot leave the container, preventing Apple Home from finding the bridge.
</Callout>

### Setup with Docker Compose [#setup-with-docker-compose]

1. Open **File Station** and create a subfolder named `homebridge` inside your shared `docker` directory.
2. Open **Container Manager** and click **Project** in the left sidebar.
3. Click **Create** and complete the project fields:
   * **Project Name:** `homebridge`
   * **Path:** `/docker/homebridge`
   * **Source:** *Create docker-compose.yaml*
4. Paste the following configuration:

```yaml
services:
  homebridge:
    image: homebridge/homebridge:latest
    container_name: homebridge
    restart: unless-stopped
    network_mode: host
    volumes:
      - /volume1/docker/homebridge:/homebridge
    environment:
      - TZ=Europe/Berlin
      - PUID=1000
      - PGID=1000
      - HOMEBRIDGE_CONFIG_UI_PORT=8581
```

5. Click **Next** and finish the setup. The container will download and start automatically.

***

## Connecting and Initial Setup [#connecting-and-initial-setup]

Once the service is running, Homebridge is available on your local network. The web interface (`homebridge-config-ui-x`) acts as the browser dashboard and provides the API that Homemanager connects to.

The instance runs unencrypted over port `8581` by default.

Because this is a fresh setup without existing accounts, you create an administrator account during the first connection. You can do this in the app or in a browser:

<Tabs items="[&#x22;Homemanager (iOS & iPadOS)&#x22;, &#x22;Homebridge Web Interface&#x22;]">
  <Tab>
    ### Setup with Homemanager [#setup-with-homemanager]

    Homemanager lets you manage instances on iPhone and iPad, monitor live logs, and configure plugins.

    <Steps>
      <Step>
        #### Discover the server [#discover-the-server]

        Open Homemanager while connected to the same Wi-Fi network as your DiskStation. Tap **Connect to Server** during initial launch (or **Add Platform** in the platform list). The app scans the local network using mDNS and Bonjour.
      </Step>

      <Step>
        #### Select the instance [#select-the-instance]

        Choose the detected server from the list. It shows the Homebridge icon and port `8581`.
      </Step>

      <Step>
        #### Create an administrator account [#create-an-administrator-account]

        Homemanager detects the new server and opens the **Create new User** screen. Enter a display name, username (such as `admin`), and password, then tap **Create and Log In**.
      </Step>
    </Steps>

    The account is created directly on the server, credentials are saved securely in your iOS Keychain, and Homemanager connects immediately.

    <Callout type="info">
      Discovery issues or blocked by the DSM firewall? Refer to [Connecting Servers to Homemanager](/guide/connecting-servers) for manual IP and port configuration and network troubleshooting.
    </Callout>
  </Tab>

  <Tab>
    ### Setup in the Web Browser [#setup-in-the-web-browser]

    To configure the server from a computer, open the interface in a desktop browser.

    <Steps>
      <Step>
        #### Open the URL [#open-the-url]

        Navigate to the web interface in your browser:

        ```
        http://<your-nas-ip-address>:8581
        ```

        *(Example: `http://192.168.1.50:8581` or `http://homebridge.local:8581`).*
      </Step>

      <Step>
        #### Create an account or restore a backup [#create-an-account-or-restore-a-backup]

        Enter a username and password for the admin account. If migrating from an earlier setup, you can restore a backup archive here instead.
      </Step>
    </Steps>

    After signing in, the dashboard displays the HomeKit pairing code.
  </Tab>
</Tabs>

***

## Network Settings and DSM Firewall [#network-settings-and-dsm-firewall]

For reliable communication between Apple Home, Homemanager, and your DiskStation, check these settings:

### 1. Adjust DSM Firewall Rules [#1-adjust-dsm-firewall-rules]

If the DSM firewall is enabled under **Control Panel > Security > Firewall**, add allow rules for these ports:

* **Port 8581 (TCP):** Management interface and Homemanager API.
* **Port 51826 (TCP):** Default port for the main Apple Home bridge.
* **Port Range for Child Bridges (TCP, e.g. 51827 to 51850):** When running plugins as isolated Child Bridges, each bridge claims its own TCP port. The port is assigned upon creation or chosen dynamically. You can check the active port for any plugin inside Homemanager under **Bridge Settings** (or within the plugin settings on the web dashboard).
* **Port 5353 (UDP):** For mDNS multicast discovery (Bonjour).

### 2. Use Local IP Instead of QuickConnect [#2-use-local-ip-instead-of-quickconnect]

Apple Home, Homemanager, and Homebridge communicate using local network multicast protocols. Always use the local IP address of your DiskStation. Remote tunnels like Synology QuickConnect cannot relay these local multicast packets.

***

## File Paths and Maintenance (Native Package) [#file-paths-and-maintenance-native-package]

When using the native SPK package, DSM stores configuration and plugin data in the shared `homebridge` folder:

| Item                            | Path or Command                              |
| :------------------------------ | :------------------------------------------- |
| **Configuration File**          | `/volume1/homebridge/config.json`            |
| **Data Directory & Plugins**    | `/volume1/homebridge`                        |
| **Node.js Binary**              | `/volume1/@appstore/homebridge/app/bin/node` |
| **Restart Service (SSH)**       | `sudo hb-service restart`                    |
| **Reset Password (SSH)**        | `sudo hb-service reset-admin`                |
| **View Live Logs (SSH)**        | `sudo hb-service logs`                       |
| **Open Homebridge Shell (SSH)** | `sudo hb-shell`                              |

***

## Frequently Asked Questions & Troubleshooting [#frequently-asked-questions--troubleshooting]

<Accordions>
  <Accordion title="Cannot connect to port 8581">
    If neither Homemanager nor your browser can access the dashboard:

    * **Check Package Center Status:** Open Package Center in DSM and verify that Homebridge shows as *Running*. If stopped, start it manually.
    * **Verify DSM Firewall:** Under *Control Panel > Security > Firewall*, confirm that incoming traffic on port 8581 is allowed.
    * **Initial Startup on ARM Models:** On entry-level j-series DiskStations (such as the DS120j or DS220j), the initial launch process can take up to 10 minutes.
  </Accordion>

  <Accordion title="Using USB dongles (Zigbee or Z-Wave) on DSM 7">
    Starting with DSM 7, Synology removed native driver support for many USB serial adapters (commonly used by Zigbee dongles like ConBee II or Sonoff).

    * **Community Kernel Modules:** You can load missing drivers (`ch341.ko`, `cp210x.ko`, or `pl2303.ko`) through SynoCommunity packages or third-party kernel driver archives.
    * **Recommended Alternative:** Network coordinators (Zigbee bridges connected over Ethernet or Wi-Fi) avoid USB driver issues entirely and remain unaffected by DSM updates.
  </Accordion>

  <Accordion title="Forgot Homebridge password">
    If you lose your password for the web interface or Homemanager login, connect to your NAS over SSH and run:

    ```bash
    sudo hb-service reset-admin
    ```

    This restores credentials to `admin` / `admin`, allowing immediate login and the creation of a new password.
  </Accordion>

  <Accordion title="Apple Home cannot discover the bridge (mDNS / Bonjour)">
    If pairing in Apple Home fails:

    * **Verify Docker Networking:** If using Docker, `network_mode: host` is mandatory. Standard bridge networks isolate discovery packets.
    * **Switch mDNS Advertiser:** In Homebridge settings (under *Advanced Settings*), switch between advertiser engines (such as *Bonjour HAP* and *Ciao*). On Synology systems, *Ciao* generally performs most reliably.
    * **Router IGMP Snooping:** Some routers or network switches drop multicast traffic between Wi-Fi and Ethernet. Try disabling IGMP snooping in your router settings.
  </Accordion>

  <Accordion title="Encrypted HTTPS access (SSL) for the web interface">
    The native SPK package listens unencrypted on port 8581 (`http://`) by default. If you prefer encrypted HTTPS access with a valid certificate:

    * In DSM, open **Control Panel > Login Portal > Advanced > Reverse Proxy**.
    * Create a new entry with your preferred domain (e.g. `homebridge.your-domain.com`, HTTPS, port 443).
    * Set the destination to `localhost` and port `8581` (HTTP).
    * Under **Security > Certificate**, assign your existing Synology Let's Encrypt certificate to that hostname.
  </Accordion>

  <Accordion title="Errors compiling native plugin modules">
    Certain plugins require native C++ modules (such as specific Bluetooth or audio drivers) that compile during installation. DSM does not include build tools like `gcc` or `make` by default.

    * Install necessary compilation tools over an SSH terminal if required, or run Homebridge in Docker using an image that bundles the required build environment.
    * Reference the [Synology SPK native module compilation notes](https://github.com/homebridge/homebridge-syno-spk/wiki/DSM-7:-Enable-Compiling-Of-Native-Modules) for detailed steps.
  </Accordion>
</Accordions>

***

## Next Steps [#next-steps]

With Homebridge running on your DiskStation, complete your setup:

1. **Pair with Apple Home:**\
   Find the HomeKit setup QR code on the dashboard or in Homemanager. Open Apple Home on your iPhone, tap the plus icon, select *Add Accessory*, and scan the code.\
   [Guide to Pairing with Apple Home](/guide/pairing-apple-home)

2. **Install Plugins:**\
   Search the plugin catalog in Homemanager or the web interface for integrations supporting your smart devices (such as Tuya, Ring, Fritz!Box, Hue, or Shelly).\
   [Tips on Finding and Evaluating Plugins](/guide/finding-plugins)

3. **Configure Child Bridges:**\
   Run larger plugins in dedicated child processes to keep individual accessory issues from affecting your remaining devices.\
   [Learn more about Child Bridges](/guide/child-bridges)

***

## Further Resources [#further-resources]

### Guides in Homemanager Docs [#guides-in-homemanager-docs]

* [How to Install Homebridge: All Methods](/guide/install-homebridge)
* [Choose Your System: Hardware Comparison](/guide/choose-your-system)
* [Connecting Servers with Homemanager](/guide/connecting-servers)
* [Updating System Software & Node.js](/guide/updating-system-software)
* [Startup Errors & Log Analysis](/guide/troubleshooting-startup-errors)
* [Troubleshooting Startup Errors](/guide/troubleshooting-startup-errors)

### Official Resources [#official-resources]

* [Official Download Portal: synology.homebridge.io](https://synology.homebridge.io)
* [Official Homebridge Wiki: Install Homebridge on Synology DSM](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Synology-DSM)
* [Homebridge Synology SPK GitHub Repository](https://github.com/homebridge/homebridge-syno-spk)
* [Homebridge Docker Documentation](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Docker)
* [Compiling Native Modules on DSM 7](https://github.com/homebridge/homebridge-syno-spk/wiki/DSM-7:-Enable-Compiling-Of-Native-Modules)