> ## 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.

# Quick Start

> From zero to your first command in about ten minutes.

This guide takes you through the whole setup: create your account, connect Home Assistant, link Telegram, add credits, and send your first message.

## Before you begin

You'll need:

* A running **Home Assistant** instance (2024.12 or newer) with [HACS](https://hacs.xyz) installed.
* A **Telegram** account.
* About ten minutes.

You **don't** need to open ports, have a public IP, or configure DNS or a VPN.

## 1. Create your account

<Steps>
  <Step title="Open the sign-in page">
    Go to [homiagent.app/login](https://homiagent.app/login).
  </Step>

  <Step title="Enter your email">
    We'll email you a temporary access code.
  </Step>

  <Step title="Enter the code">
    You're signed in.
  </Step>
</Steps>

There's no password and no separate sign-up step. Your account is created the first time you sign in with a new email.

<Info>
  Access codes expire after 15 minutes. If yours expires, just request a new one.
</Info>

## 2. Install the integration in Home Assistant

HomiAgent connects to your home through the **HomiAgent Bridge** integration.

<Card title="HomiAgent Bridge on GitHub" icon="github" href="https://github.com/homiagent/homiagent-bridge">
  [https://github.com/homiagent/homiagent-bridge](https://github.com/homiagent/homiagent-bridge)
</Card>

<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>

## 3. Connect your home

<Steps>
  <Step title="Generate a pairing key">
    In the [HomiAgent dashboard](https://homiagent.app/app), click **Generate pairing key** and copy the key that appears.
  </Step>

  <Step title="Add the integration">
    In Home Assistant, go to **Settings → Devices & Services → Add Integration**, search for **HomiAgent Bridge**, and select it.
  </Step>

  <Step title="Paste the key">
    Paste the pairing key and submit.
  </Step>

  <Step title="Check the dashboard">
    Refresh the HomiAgent dashboard. Your home should show up under **Connected homes** as online.
  </Step>
</Steps>

<Warning>
  Pairing keys expire after 10 minutes and work only once. If Home Assistant says the key is invalid, expired, or already used, generate a new one in the dashboard and try again.
</Warning>

Once it's connected, HomiAgent syncs your rooms, devices, and services automatically. In Home Assistant, a connectivity sensor on the integration shows whether the link is up. If the connection drops, the integration reconnects on its own.

## 4. Link your Telegram account

<Steps>
  <Step title="Get a link code">
    In the HomiAgent dashboard, open [**Telegram**](https://homiagent.app/app/telegram) and click **Link account**. Copy the message shown. It looks like `/connect ABC123`.
  </Step>

  <Step title="Message the bot">
    In Telegram, search for the **HomiAgent** bot and send it that message.
  </Step>

  <Step title="Confirm">
    The bot confirms the link. Refresh the dashboard and your Telegram account appears under **Linked accounts**.
  </Step>
</Steps>

<Info>
  Link codes expire after 10 minutes. You can link more than one Telegram account, for example one for each person in your household.
</Info>

## 5. Add credits

HomiAgent runs on prepaid credits, and you'll need some before the assistant can answer.

<Steps>
  <Step title="Send /buy">
    In the HomiAgent chat on Telegram, send `/buy`.
  </Step>

  <Step title="Pick an amount">
    The menu shows your current balance and the minimum top-up.
  </Step>

  <Step title="Pay">
    Finish the payment on the checkout page that opens. You'll be sent back to Telegram afterwards.
  </Step>
</Steps>

Credits show up in your balance as soon as the payment is confirmed. Your balance is also shown on the dashboard home page.

## 6. Send your first message

Try something simple in the HomiAgent chat:

> Which lights are on right now?

Then try an action:

> Turn off the kitchen lights.

You can also hold the microphone button and say it out loud. If HomiAgent isn't sure which device you mean, it asks before acting.

## Bot commands

| Command | What it does |
| - | - |
| `/connect <code>` | Links this chat to your HomiAgent account. |
| `/buy` | Buys credits. |
| `/clearsession` | Starts a fresh conversation and clears the current context. |
| `/disconnect` | Unlinks this chat from your account. |

## Troubleshooting

<AccordionGroup>
  <Accordion title="My home shows as offline">
    Check that Home Assistant is running and has internet access. Under **Settings → Devices & Services → HomiAgent Bridge**, look at the connectivity sensor. If the key expired before pairing finished, generate a new key in the dashboard and use **Reconfigure** on the integration to paste it.
  </Accordion>

  <Accordion title="The bot says I'm out of credits">
    Send `/buy` to top up. It works even when your balance is zero.
  </Accordion>

  <Accordion title="The bot doesn't recognize my account">
    Generate a new link code from **Telegram → Link account** and send the `/connect` message again.
  </Accordion>
</AccordionGroup>

## Next step

<Card title="Context matters" icon="lightbulb" href="/context-matters">
  Name your entities, assign areas, and use HomiAgent labels so the assistant gets it right the first time.
</Card>


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