# How to Deploy Home Assistant With xCloud One Click Apps

> Deploy Home Assistant on xCloud from the One Click Apps catalog: server size, Demo Site or Go Live, creating the owner account, what it can't do, and updates.

You can deploy Home Assistant on xCloud in a few clicks: **New Site → search "Home Assistant" → choose a server → Continue → Site Title and domain → Next**. xCloud runs the official Home Assistant image in Docker, keeps your settings on a persistent volume, and puts it on your domain with HTTPS. You never write a `docker-compose.yml`. This guide is for people who want Home Assistant dashboards and automations for cloud services, MQTT and webhooks, on a server they control.

**This install runs in the cloud, not in your home.** It can't use integrations that discover or talk to devices on your home network (local discovery, USB, Zigbee, Z-Wave, Bluetooth). If most of your devices only work locally, run Home Assistant on a machine in your home instead. See the [Home Assistant hosting page](/home-assistant-hosting/) for plans.

## What the xCloud template installs

| Part | What you get |
|---|---|
| App | Home Assistant **2026.9.4**, the official `ghcr.io/home-assistant/home-assistant` image, pinned to that version |
| Web access | Home Assistant on your domain over HTTPS. Its web port (8123) is only reachable through your domain, not by server IP and port. |
| Storage | One persistent volume, `ha_config`, mounted at `/config`. It holds your configuration, users, integrations, history database and custom components. |
| First-start setup | A default `configuration.yaml`, plus network settings that tell Home Assistant to trust xCloud's HTTPS proxy (`127.0.0.1/32` and `172.16.0.0/12`). Without them, Home Assistant blocks every request that comes through your domain. |
| Accounts | None. You create the owner account on first visit. |
| Not included | The add-on store, and integrations that discover or talk to devices on your home network (local discovery, USB, Zigbee, Z-Wave, Bluetooth) |

## Before you start

| Requirement | What you need | Why it matters |
|---|---|---|
| Server stack | An NGINX server | Home Assistant runs in Docker, and xCloud runs Docker apps on NGINX servers. If the server doesn't have Docker yet, xCloud installs it during the site install. See [enable Docker on an NGINX server](/docs/enable-docker-on-an-nginx-server-in-xcloud/). |
| Server size | At least 1 vCPU, 1 GB RAM and 8 GB free disk | xCloud checks these minimums before it installs. Long history, many integrations and cameras need more. |
| Domain (optional) | DNS access, if you choose **Go Live** | **Demo Site** gives you a temporary address, so you can start without a domain. |
| Time right after the install | A few minutes to create the owner account | Whoever opens the site first becomes its owner. |

If your server is too small, xCloud tells you before the install starts. See [how to upgrade your server](/docs/how-to-upgrade-your-server-in-xcloud/).

## Step 1: Find Home Assistant in the app catalog

In the xCloud dashboard, click **New Site**. On **What would you like to host today?**, type `Home Assistant` in the **Search apps…** box, then click the **Home Assistant** card.

![Search for Home Assistant in the New Site app catalog and click the Home Assistant card](/_landing/docs/deploy-home-assistant-with-xcloud-image-1.png)

**Expected result:** The Home Assistant page opens, with the servers you can install it on.

## Step 2: Choose where Home Assistant runs

Under **Where should it run?**, click an existing NGINX server card. The card shows the server's RAM, CPU, free disk and number of sites. If you don't have a suitable server, choose **Deploy on a new server** and xCloud creates one for you.

![Select an NGINX server under Where should it run? on the Home Assistant page](/_landing/docs/deploy-home-assistant-with-xcloud-image-2.png)

Then click **Continue**.

**Expected result:** The **Install Home Assistant Into** page opens for the server you chose.

## Step 3: Enter a Site Title

Under **Site Details**, type a name in **Site Title**, for example `Home Assistant`. Use **Add Tag (optional)** only if your team sorts sites by tags.

![Type a name in the Site Title field on the Install Home Assistant page](/_landing/docs/deploy-home-assistant-with-xcloud-image-3.png)

**Expected result:** The **Site Title** field shows the name you typed.

## Step 4: Choose Demo Site or Go Live

Under **Domain Setup**, pick one. **Demo Site** is selected when the page opens.

- **Demo Site**: xCloud gives you a temporary domain. You can [move to your own domain later](/docs/how-to-go-live-from-demo-site/). Good for a first test.
- **Go Live**: you enter your own domain, and point its DNS at the server.

![Choose Demo Site under Domain Setup when installing Home Assistant](/_landing/docs/deploy-home-assistant-with-xcloud-image-4.png)

**Expected result:** With **Demo Site**, xCloud fills in a **Domain Name** for you. Click **Regenerate** if you want a different one.

Home Assistant asks for nothing else. The form has no app settings, because the account is created in Home Assistant itself.

## Step 5: Click Next to install Home Assistant

Check the details, then click **Next**.

![Click Next at the bottom of the Install Home Assistant form to start the installation](/_landing/docs/deploy-home-assistant-with-xcloud-image-5.png)

**Expected result:** xCloud shows the install progress, step by step, until **Finishing Up**. You can leave the page while it runs. The first install downloads the Home Assistant image, so this step can take several minutes.

## Step 6: Open Home Assistant from Site Overview

When the install finishes, the site's **Site Overview** opens. The **Home Assistant Credentials** card shows the site **URL**. Whoever opens it first becomes the owner, so open it now. Click **Visit Site** at the top of the page, or copy the **URL**.

![Click Visit Site on the Home Assistant Site Overview, next to the Home Assistant Credentials card](/_landing/docs/deploy-home-assistant-with-xcloud-image-6.png)

**Expected result:** The Home Assistant **Welcome!** page opens. Under **Docker Container Health** on the overview, the container whose name starts with `home-assistant-` shows **healthy**.

The first start can take a few minutes while Home Assistant loads its integrations. If the page doesn't load yet, wait a minute and reload.

## Step 7: Start the Home Assistant setup

On the Home Assistant **Welcome!** page, click **Create my smart home**. Do this right away, and don't share the site address before you have created your account.

![Click Create my smart home on the Home Assistant Welcome page](/_landing/docs/deploy-home-assistant-with-xcloud-image-7.png)

**Expected result:** The **Create user** page opens.

If you are moving an existing Home Assistant to xCloud, the **Welcome!** page also has **Upload backup** under **Or restore**.

## Step 8: Create your owner account

On **Create user**, fill in **Name**, **Username**, **Password** and **Confirm password**, then click **Create account**. Save the password in your password manager.

![Fill in Name, Username, Password and Confirm password on the Home Assistant Create user page, then click Create account](/_landing/docs/deploy-home-assistant-with-xcloud-image-8.png)

**Expected result:** Home Assistant creates your owner account and continues with its own setup screens. Follow them to finish, and you are signed in to your new Home Assistant.

## After the first sign-in

| Task | What to do |
|---|---|
| Add integrations | In Home Assistant, open **Settings → Devices & services** and add cloud-based integrations, MQTT or webhooks. Integrations that need your home network, USB or Bluetooth will not work here. |
| Keep the proxy settings | xCloud sets Home Assistant's web server settings on the first start, outside `configuration.yaml`. In Home Assistant, open **Settings → System → Network**. If you change the settings there ([Home Assistant HTTP docs](https://www.home-assistant.io/integrations/http/)), keep the option to trust the `X-Forwarded-For` header turned on, and keep `127.0.0.1/32` and `172.16.0.0/12` under **Trusted proxies**. If you remove them, Home Assistant blocks every request through your domain. |
| Add users | Create other accounts from **Settings → People** in Home Assistant. |
| Back up | Use **Backup** in the site menu. Back up and restore the whole `ha_config` volume as one unit. See [backing up Docker apps](/docs/backup-and-restore-docker-apps/). |
| Watch resources | Large history, many integrations, cameras and media use more RAM and disk. Check the server's monitoring and upgrade the server when it gets tight. |

## Update Home Assistant

xCloud pins Home Assistant to **2026.9.4**. **App Actions → Update** downloads the version set on the Compose page (2026.9.4) again and restarts Home Assistant. Your settings stay. It does not move you to a newer release. Your site keeps the version in its own Compose file.

To move to a newer Home Assistant release:

1. Read the [Home Assistant release notes](https://www.home-assistant.io/blog/categories/release-notes/) for breaking changes in the version you want.
2. Back up the site first, including the full `ha_config` volume.
3. On the site's **Compose** page, replace the whole image line, including the `@sha256:…` part, with the new version, for example `ghcr.io/home-assistant/home-assistant:2026.10.1`, then click **Save & Redeploy**. Keep the volume name as it is.
4. Sign in and check your integrations and automations.

The full steps are in [Update a One Click App and edit its Docker Compose file](/docs/update-a-one-click-app-and-edit-its-docker-compose-in-xcloud/).

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| **Continue** stays disabled | No compatible server is selected | Click an NGINX server card that meets the minimums, or choose **Deploy on a new server**. |
| The site stops loading after you saved network settings | The `X-Forwarded-For` option was turned off, or `127.0.0.1/32` and `172.16.0.0/12` were removed from **Trusted proxies** | Wait a few minutes. Home Assistant may undo unconfirmed web server changes after a few minutes (see the [Home Assistant HTTP docs](https://www.home-assistant.io/integrations/http/)). If the site still doesn't load, restore a backup of `ha_config`. |
| Home Assistant is still on the old version after **Save & Redeploy** | The image line still ends in `@sha256:…`. That part locks the old version, so the new version number has no effect. | On the **Compose** page, remove the `@sha256:…` part so the line ends with the new version, then click **Save & Redeploy** again. |
| The page doesn't load right after the install | Home Assistant is still starting | Wait a few minutes and reload. The first start loads all default integrations. |
| A local device or integration isn't found | The server is not on your home network | Use a cloud integration or MQTT for that device, or run Home Assistant at home. |

## Frequently asked questions

### Can Home Assistant on xCloud control the devices in my home?

Only devices and services it can reach over the internet, such as cloud integrations, an MQTT broker the server can reach, and webhooks. It runs on a cloud server, so it can't discover or talk to devices on your home network, and has no USB, Zigbee, Z-Wave or Bluetooth access.

### What is the username and password for Home Assistant on xCloud?

There is none yet. Home Assistant has no preset account. The first person who opens your site creates the owner account, so open it and create yours as soon as the install finishes.

### Is the Home Assistant add-on store available?

No. xCloud runs the official Home Assistant Container image, and the add-on store is not part of that image. You can still add integrations from Settings in Home Assistant.

### Does App Actions → Update move Home Assistant to a newer version?

No. Update downloads the version set on the site's **Compose** page (2026.9.4) again and restarts Home Assistant. Your settings stay. To get a newer version, back up the site, then replace the whole image line on the site's **Compose** page with the new version and click **Save & Redeploy**. Remove the `@sha256:…` part, or the old version keeps running.

## Related resources

- [Home Assistant hosting on xCloud](/home-assistant-hosting/), the plans and what is included
- [How to use One Click App templates](/docs/how-to-use-one-click-app-templates-in-xcloud/) for App Actions, the Environment editor and events
- [Deploy n8n with xCloud One Click Apps](/docs/deploy-n8n-with-xcloud-with-one-click-apps/), another automation app you can run next to Home Assistant
- [Explore the One Click Apps catalog](/one-click-apps/)
- Upstream: [Home Assistant documentation](https://www.home-assistant.io/docs/)

If Home Assistant does not come up after the install, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/) with the site's failed event output.