# Connecting Homebridge and HOOBS to Homemanager (https://docs.homemanager-app.de/guide/connecting-servers)





Homemanager connects directly to the APIs provided by the Homebridge web interface (`homebridge-config-ui-x`) and the HOOBS Core API. You do not need any companion bridge plugins or custom server packages. The [HOOBS app alternative](/guide/hoobs-app-alternative) page shows what Homemanager can do on HOOBS.

You can establish the connection in two ways: automatically through local mDNS discovery, or manually by specifying an IP address and port.

<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 for iPhone & iPad
  </span>
</div>

<div className="grid grid-cols-2 lg:grid-cols-4 gap-4 my-8 items-start">
  <div className="flex flex-col items-center text-center">
    <ImageZoom src="/images/app/connecting/discover-platforms.jpg" alt="Automatic network scan in Homemanager" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="1. Scan for servers" />
  </div>

  <div className="flex flex-col items-center text-center">
    <ImageZoom src="/images/app/connecting/create-user.jpg" alt="Initial user setup in Homemanager" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="2a. Create user" />
  </div>

  <div className="flex flex-col items-center text-center">
    <ImageZoom src="/images/app/connecting/login.jpg" alt="Logging in to an existing instance in Homemanager" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="2b. Existing account" />
  </div>

  <div className="flex flex-col items-center text-center">
    <ImageZoom src="/images/app/connecting/connect-manually.jpg" alt="Manual server connection using IP and port" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="3. Connect manually" />
  </div>
</div>

***

## Prerequisites [#prerequisites]

Before starting the connection process, confirm the following:

1. The server (Homebridge or HOOBS) is powered on and connected to your local network via Ethernet or Wi-Fi.
2. The web interface is active (`homebridge-config-ui-x` for Homebridge, or the system UI for HOOBS).
3. Your iPhone or iPad is connected to the same Wi-Fi network as the server.
4. iOS has granted Homemanager permission to access the local network.

<Callout type="warn">
  Do not connect your iOS device to an isolated guest Wi-Fi network. Guest networks typically enable client isolation, preventing devices from communicating directly with each other.
</Callout>

***

## Method 1: Automatic Discovery (mDNS / Bonjour) [#method-1-automatic-discovery-mdns--bonjour]

<Steps>
  <Step>
    ### Start the network scan [#start-the-network-scan]

    When opening Homemanager for the first time, an onboarding assistant guides you through the setup. You can follow the installation steps or jump directly to **Connect to Server** if your instance is already running on the network.

    If you already manage a server in the app, navigate to the **Platforms** screen and tap **Add Platform**.

    Homemanager immediately scans your local network using mDNS and Bonjour to detect active Homebridge and HOOBS instances.
  </Step>

  <Step>
    ### Select your server [#select-your-server]

    Detected servers appear in the discovery list:

    * **Homebridge:** Identified by the Homebridge logo, the hostname (such as `homebridge.local`), and the address with port (such as `https://192.168.188.30:443&#x60;). Homemanager also detects associated child bridges and displays them inline (for example, *+1 additional related bridges*).
    * **HOOBS:** Identified by the yellow HOOBS icon, the hostname `hoobs.local`, and port `80`.

    Tap your server in the list to proceed.
  </Step>

  <Step>
    ### Create an account or sign in [#create-an-account-or-sign-in]

    Homemanager checks the instance status and opens the corresponding screen:

    <Tabs items="[&#x22;Initial Setup (Fresh Server)&#x22;, &#x22;Existing Server&#x22;]">
      <Tab>
        #### Initial setup directly in the app [#initial-setup-directly-in-the-app]

        When connecting to a newly installed server without an existing account, Homemanager opens the **Create new User** screen:

        1. **Display name:** Enter an administrative profile name (such as your first name or *Admin*).
        2. **Username:** Choose your login username (such as `admin`).
        3. **Password & Repeat password:** Enter a secure password and repeat it for confirmation.
        4. Tap **Create and log in**.

        The administrator account is configured directly on your server, and Homemanager finishes the connection immediately.
      </Tab>

      <Tab>
        #### Sign in to an existing instance [#sign-in-to-an-existing-instance]

        If your server is already configured, the **Login** screen appears:

        1. **Username & Password:** Enter your existing dashboard credentials (the same login you use in your desktop browser).
        2. Tap **Login**.

        <Callout type="info">
          **Encrypted storage:** Homemanager stores your credentials encrypted locally in the iOS Keychain. Encryption happens entirely on your device. Credentials are never transmitted to external cloud servers.
        </Callout>
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## Method 2: Manual Connection via IP and Port [#method-2-manual-connection-via-ip-and-port]

If automatic discovery does not list your server, you can connect directly using its local IP address and port. This is often necessary in networks with isolated subnets, VLANs, or routers that filter multicast traffic.

<Steps>
  <Step>
    ### Open manual entry [#open-manual-entry]

    Tap **Connect platform manually** at the bottom of the discovery screen.
  </Step>

  <Step>
    ### Enter connection parameters [#enter-connection-parameters]

    Provide the connection details for your server:

    * **Encryption:**
      * Choose &#x2A;*`https`** if you are using the official Homebridge Raspberry Pi image on port `443` or have configured an SSL certificate in your system settings.
      * Choose &#x2A;*`http`** if you are using the unencrypted default port `8581` for Homebridge UI or a standard HOOBS installation on port `80`.
    * **Host:** Enter your server's local IPv4 address (such as `192.168.178.50`) or local hostname (such as `homebridge.local`).
    * **Port:** The web interface port:
      * **8581:** Default port for Homebridge (`homebridge-config-ui-x`).
      * **443:** Standard HTTPS port on the official Raspberry Pi image.
      * **80:** Default port on many HOOBS setups.
  </Step>

  <Step>
    ### Verify and connect [#verify-and-connect]

    Tap **Connect**. Homemanager verifies that the endpoint is reachable and prompts for your login credentials.
  </Step>
</Steps>

***

## The Manual Route: Browser Access [#the-manual-route-browser-access]

You can open the web interface from any desktop browser to confirm server health. If the dashboard fails to load in Safari on your iPhone, the issue is almost always located in your server or local network configuration.

### Default Local Addresses [#default-local-addresses]

| System                                     | Default Browser URL            | Fallback IP Address                                |
| :----------------------------------------- | :----------------------------- | :------------------------------------------------- |
| **Homebridge (Raspberry Pi Image)**        | `https://homebridge.local`     | `https://<server-ip>` or `http://<server-ip>:8581` |
| **Homebridge (Docker / Synology / macOS)** | `http://homebridge.local:8581` | `http://<server-ip>:8581`                          |
| **HOOBS**                                  | `http://hoobs.local`           | `http://<server-ip>`                               |

<Callout type="info">
  **HTTPS Certificate Warnings:** The official Homebridge image uses a self-signed SSL certificate. When accessing `https://homebridge.local` in a desktop browser, Safari or Chrome will display a warning that the connection is not private. On your local network, you can safely proceed by clicking *Advanced > Proceed to homebridge.local*. Homemanager handles this certificate verification automatically in your local environment.
</Callout>

***

## Troubleshooting and FAQ [#troubleshooting-and-faq]

<Accordions type="multiple">
  <Accordion id="local-network-permission" title="Server not found: Check iOS Local Network permission">
    Starting with iOS 14, every app requires permission before scanning for devices on your local network. If this prompt was declined during initial launch, Homemanager cannot send or receive mDNS packets.

    To check and enable the permission:

    1. Open the iOS **Settings** app on your iPhone or iPad.
    2. Scroll down to **Privacy & Security**.
    3. Tap **Local Network**.
    4. Ensure the toggle for **Homemanager** is enabled (green).

    Relaunch Homemanager and run the scan again.
  </Accordion>

  <Accordion id="vlan-multicast-issues" title="Server in an isolated VLAN or subnet (mDNS issues)">
    Multicast DNS (Bonjour) discovery operates strictly within a single broadcast domain. If your Homebridge server is placed in an isolated IoT VLAN while your iPhone is connected to your primary home network, the router blocks discovery broadcasts by default.

    You have two solutions:

    * **Quick fix:** Use Method 2 (Manual Connection) in Homemanager and enter the server's static IP address directly. TCP communication between subnets works as long as your firewall rules permit traffic on port `8581` or `443`.
    * **Permanent fix:** Enable an **mDNS Reflector** or **mDNS Repeater** (such as Avahi in pfSense, OPNsense, or UniFi) to forward Bonjour packets across VLAN boundaries.
  </Accordion>

  <Accordion id="forgotten-password" title="Forgotten credentials: Resetting the admin password">
    If you lose your login credentials, reset the administrative user to default values using the server terminal.

    Connect to your server via SSH or the terminal console and run:

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

    This command resets the credentials to:

    * **Username:** `admin`
    * **Password:** `admin`

    Sign in with these credentials and update your password immediately in your account settings.
  </Accordion>

  <Accordion id="remote-access" title="Managing your server outside your home network (Remote Access)">
    Homebridge and HOOBS are designed as local services without open public cloud endpoints. Exposing their web interface ports directly to the internet through router port forwarding is dangerous and should be avoided.

    To manage your server securely while away from home:

    * **VPN Tunnel (WireGuard):** Most modern routers (including AVM FRITZ!Box models) offer an integrated WireGuard VPN server. Once connected, your iPhone behaves as if it were on your home network.
    * **Mesh VPN (Tailscale):** Tailscale can be installed on both your Raspberry Pi and your iOS device, providing encrypted point-to-point connections without opening router ports.
    * **Homemanager Remote Access (in development):** A dedicated, end-to-end encrypted remote access solution integrated directly into Homemanager is currently being built.
  </Accordion>
</Accordions>

***

## Next Steps [#next-steps]

Once your server is connected, explore the core administration tools available in Homemanager:

<Cards>
  <Card icon="<HardDrive />" title="Finding and Installing Plugins" description="Browse verified community plugins and configure accessories without editing JSON files directly." href="/guide/finding-plugins" />

  <Card icon="<Wifi />" title="Pairing with Apple Home" description="Scan the HomeKit QR code to add your Homebridge or HOOBS bridge to the Apple Home app." href="/guide/pairing-apple-home" />

  <Card icon="<HelpCircle />" title="App FAQ & Support" description="Answers to common questions regarding licensing, remote access, background notifications, and diagnostic logs." href="/guide/faq" />
</Cards>