> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homiagent.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the integration

> Add the HomiAgent Bridge integration to Home Assistant with HACS or by hand.

HomiAgent talks to your home through the **HomiAgent Bridge** integration. It opens a secure connection *from your home to HomiAgent*, so you don't need to open ports or set up DNS or a VPN.

This page covers installing it. To link it to your account, continue with [Connect your home](/connect-home).

## Requirements

* Home Assistant **2024.12 or newer**.
* [HACS](https://hacs.xyz), for the recommended install method.

## Option 1: HACS (recommended)

<Tip>
  Shortcut: [open the repository directly in your Home Assistant's HACS](https://my.home-assistant.io/redirect/hacs_repository/?owner=homiagent\&repository=homiagent-bridge\&category=integration). It fills in step 1 for you, so you can go straight to **Download**.
</Tip>

<Steps>
  <Step title="Add the custom repository">
    In Home Assistant, open **HACS**, open the **⋮** menu (top right), and choose **Custom repositories**. Paste `https://github.com/homiagent/homiagent-bridge`, set the type to **Integration**, and click **Add**.
  </Step>

  <Step title="Download the integration">
    Search for **HomiAgent Bridge** in HACS and click **Download**.
  </Step>

  <Step title="Restart Home Assistant">
    The integration only shows up after a restart.
  </Step>
</Steps>

## Option 2: manual install

Use this if you don't have HACS.

<Steps>
  <Step title="Download the code">
    Download the latest code from the [HomiAgent Bridge repository on GitHub](https://github.com/homiagent/homiagent-bridge).
  </Step>

  <Step title="Copy the integration folder">
    Copy the `custom_components/homiagent_bridge` folder into the `custom_components` folder of your Home Assistant configuration (the one that contains `configuration.yaml`). Create `custom_components` if it doesn't exist.
  </Step>

  <Step title="Restart Home Assistant">
    The integration only shows up after a restart.
  </Step>
</Steps>

<Note>
  With a manual install, Home Assistant won't tell you about updates. Repeat these steps to update.
</Note>

## Check that it worked

After the restart, go to **Settings → Devices & Services → Add Integration** and search for **HomiAgent Bridge**. If it shows up, the installation worked.

<Card title="Next: connect your home" icon="link" href="/connect-home">
  Generate a pairing key in the dashboard and paste it into Home Assistant.
</Card>

## Common problems

<AccordionGroup>
  <Accordion title="HomiAgent Bridge doesn't show up in Add Integration">
    Make sure you restarted Home Assistant after installing. For a manual install, check that the folder is `custom_components/homiagent_bridge` (not one level deeper) and that it contains a `manifest.json`.
  </Accordion>

  <Accordion title="HACS can't find the repository">
    Check that the URL is exact and that the type is **Integration**.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.