# Child Bridges (https://docs.homemanager-app.de/guide/child-bridges)





By default, Homebridge runs all installed plugins inside a single Node.js process. If one plugin hits an unhandled error or loses a cloud connection, the entire server can crash. When that happens, every accessory across your home becomes unresponsive in Apple Home at the same time.

A **Child Bridge** isolates a plugin into its own operating system process. Homebridge monitors this subprocess independently: if the plugin crashes, Homebridge restarts only that single process. The rest of your smart home stays online without interruption.

## Why Child Bridges are useful [#why-child-bridges-are-useful]

1. **Outage isolation:** When a plugin crashes or hangs on a network request, only its own subprocess goes down. All other switches, sensors, and lights remain responsive.
2. **Faster response times in Apple Home:** When you open the Apple Home app, iOS requests the status of all accessories on a bridge simultaneously. On a single shared bridge, a slow cloud plugin delays the response of all other accessories. Apple Home queries child bridges concurrently, allowing local accessories to respond instantly.
3. **Overcoming the 150-accessory limit:** Apple limits each bridge to 149 accessories (150 including the bridge itself). Child bridges split this threshold, because Apple Home treats each isolated plugin as an independent bridge with its own quota.
4. **Multi-core CPU distribution:** Node.js runs on a single thread. Child bridges distribute heavy background tasks like FFmpeg camera transcoding or frequent device polling across multiple processor cores.
5. **Targeted restarts:** Changing a plugin's configuration only requires restarting that specific subprocess, keeping the rest of your home online.

<Callout type="tip">
  Isolating plugins right when you install them saves the most work. Homemanager automatically prompts you after each download to choose between the main bridge and a child bridge, avoiding the need to reassign rooms in Apple Home later.
</Callout>

## Setting up a child bridge [#setting-up-a-child-bridge]

Each child bridge requires its own TCP port and a unique virtual MAC address on your local network, and pairs separately with Apple Home.

<Tabs items="[&#x22;Homemanager (iOS & iPadOS)&#x22;, &#x22;Web Interface (Config UI X)&#x22;, &#x22;Manual (config.json)&#x22;]">
  <Tab>
    ### Setting up in Homemanager [#setting-up-in-homemanager]

    Homemanager offers two ways to set up a child bridge:

    * **During plugin installation:** When installing an extension from the [Integration Store](/guide/finding-plugins), Homemanager asks how you want to run it right after the download finishes: on the main bridge or as an isolated child bridge. If you choose a child bridge, the app creates a backup first and configures the new bridge automatically.
    * **From the System tab:** You can move existing integrations into child bridges at any time through the bridge manager.

    <div className="grid grid-cols-1 sm:grid-cols-3 gap-4 my-6 items-start">
      <div className="flex flex-col items-center text-center">
        <ImageZoom src="/images/homebridge/child-bridges/homemanager-system-bridges.png" alt="Bridges overview in the System tab of Homemanager" className="max-w-[200px] rounded-2xl border border-fd-border shadow-md" caption="1. System tab with bridge list" />
      </div>

      <div className="flex flex-col items-center text-center">
        <ImageZoom src="/images/homebridge/child-bridges/homemanager-new-child-bridge.png" alt="New bridge wizard with automatic backup and integration selection" className="max-w-[200px] rounded-2xl border border-fd-border shadow-md" caption="2. Automatic backup & selection" />
      </div>

      <div className="flex flex-col items-center text-center">
        <ImageZoom src="/images/homebridge/child-bridges/homemanager-bridge-detail.png" alt="Bridge detail view showing status, controls, and Apple Home pairing" className="max-w-[200px] rounded-2xl border border-fd-border shadow-md" caption="3. Status, controls & pairing" />
      </div>
    </div>

    How to isolate an existing integration:

    1. Open Homemanager and select the **System** tab. The **Bridges** section displays your main bridge alongside all running child bridges.
    2. Tap the three dots in the Bridges section and select **New bridge**.
    3. Homemanager automatically creates a backup of your configuration before making any changes.
    4. Pick the installed integration you want to isolate.
    5. Once saved, the bridge starts up. A yellow **Pending pairing** banner indicates that the bridge still needs to be linked to Apple Home.
    6. Tap **Apple Home Pairing** to open the QR code and add the bridge to your home. For a complete walkthrough, see the [Apple Home pairing guide](/guide/pairing-apple-home).

    <div className="my-5 flex flex-wrap items-center gap-3">
      <AppStoreButton size="sm" />

      <span className="text-xs text-fd-muted-foreground">
        Download Homemanager for free on the App Store
      </span>
    </div>
  </Tab>

  <Tab>
    ### Setting up in the Web Interface (Config UI X) [#setting-up-in-the-web-interface-config-ui-x]

    1. Open the Homebridge web interface in your browser.
    2. Go to the **Plugins** tab.
    3. Click the **wrench icon** (Settings) on the plugin card.
    4. Select **Bridge Settings**.
    5. Enable the toggle for **Run as Child Bridge** and click **Save**.
    6. Once the process restarts, a new bridge tile appears on your dashboard.
    7. Click the bridge icon to reveal its QR code, then scan it using the Apple Home app.
  </Tab>

  <Tab>
    ### Manual configuration in config.json [#manual-configuration-in-configjson]

    If you run Homebridge without a graphical interface, configure the child bridge directly in `config.json`. Add a `_bridge` object inside the corresponding entry in the `platforms` or `accessories` array:

    ```json title="/var/lib/homebridge/config.json"
    {
      "platforms": [
        {
          "platform": "Shelly",
          "name": "Shelly",
          "_bridge": {
            "username": "0E:8A:2B:3C:4D:5E",
            "port": 51830,
            "name": "Shelly Bridge"
          }
        }
      ]
    }
    ```

    * **username:** A unique, custom MAC address in `XX:XX:XX:XX:XX:XX` format. It must not match any other bridge on your network.
    * **port:** An unused TCP port for communication with Apple Home.
    * **name:** An optional display name for the bridge in Apple Home.

    Restart Homebridge after saving. The pairing PIN matches your primary bridge PIN from the `bridge.pin` field in your `config.json`.
  </Tab>
</Tabs>

## What happens when converting existing plugins [#what-happens-when-converting-existing-plugins]

<Callout type="warn">
  **Impact on rooms, scenes, and automations:**\
  When you convert an already paired plugin into a child bridge, Apple Home treats its accessories as new hardware.\
  Room assignments, custom device names, favorites, and any automations or scenes tied to those accessories will be lost and need to be configured again.
</Callout>

## Managing child bridges in daily operation [#managing-child-bridges-in-daily-operation]

* **Status and controls:** A green status indicator in Homemanager shows that the process is running. Use the *Restart* and *Stop* buttons to manage that specific process without touching the rest of your server.
* **Pending pairing:** This notice appears when a child bridge is running on the server but has not yet been linked to Apple Home. Accessories from that plugin only appear in your home once the pairing code has been scanned.
* **Memory consumption:** Each child bridge runs as an independent Node.js process using approximately 20 to 30 MB of RAM. Keep overall memory limits in mind on low-RAM hardware such as older Raspberry Pi models.
* **Network and ports:** Every child bridge listens on its own dedicated TCP port. If you run Homebridge inside [Docker](/guide/install-docker), use host network mode (`--net=host`) so the container exposes new child bridge ports without manual port forwarding. If accessories fail to connect, adjusting the mDNS advertiser can help resolve discovery issues, as detailed in our [troubleshooting guide for 'No Response'](/guide/troubleshooting-no-response).

## Related guides [#related-guides]

<Cards>
  <Card icon="<ShieldCheck />" title="Pairing with Apple Home" description="Step-by-step instructions for pairing primary and child bridges with your Apple Home." href="/guide/pairing-apple-home" />

  <Card icon="<AlertTriangle />" title="Fixing 'No Response' Errors" description="Diagnose and resolve connection drops and unreachable accessories in Apple Home." href="/guide/troubleshooting-no-response" />

  <Card icon="<Bug />" title="Resolving Startup Errors" description="Troubleshoot crashes, port collisions, and boot loops using your server logs." href="/guide/troubleshooting-startup-errors" />

  <Card icon="<ExternalLink />" title="Homebridge Wiki: Child Bridges" description="Official child bridge documentation maintained by the Homebridge developer team on GitHub." href="https://github.com/homebridge/homebridge/wiki/Child-Bridges" />
</Cards>