Tessera with Home Assistant Container (Docker)

Home Assistant Container has no app store, so the app can't be installed from inside Home Assistant. Instead, you run the same app as its own container next to Home Assistant. The ESPHome tools are already in the image, so you don't need ESPHome Device Builder.

Inside Home Assistant the app is called ESP Screen Manager, and its sidebar panel is ESP Screens. On Home Assistant OS you don't need this page: follow the normal installation instead.

Which route is yours

What you need

• Home Assistant Container, and Docker with Compose on the same machine (amd64 or aarch64).
• git on that machine, because Compose builds the image straight from GitHub. No git? See Synology and other hosts without git.
• The ESPHome integration in Home Assistant, to pair the screens.
• A Home Assistant account with administrator rights, to create an access token.

Install

1. Create a folder, for example esp-screens, and save compose.yaml in it.

2. Create an access token. In Home Assistant, open your profile, go to the Security tab, and under Long-lived access tokens choose Create token. Paste only the token into a new file named ha_token, next to compose.yaml. On Linux, make it readable for you only:

   chmod 600 ha_token
   

   On Docker Desktop, continue with Home Assistant on a bridge network now.

3. Check two lines in compose.yaml:

   • HA_API: http://127.0.0.1:8123/api is right when Home Assistant runs on the same machine on port 8123. Keep /api at the end.
   • ./esphome:/config keeps the screens' ESPHome files in a new esphome folder. If you already use ESPHome Device Builder, put its folder here instead, so both see the same files.

4. Start the container from the folder:

   docker compose up -d --build
   

   The first build downloads the official ESPHome image and takes a few minutes.

5. Check that it runs:

   docker compose logs -f
   

   What you'll see: the line Home Assistant connected once the token works. Press Ctrl+C to stop following the log. After about a minute, docker ps shows (healthy) next to esp-screens.

Open ESP Screens

The page has no login of its own, so it only listens on 127.0.0.1:8099 of the Docker host and answers nothing else. Don't make port 8099 reachable from your network.

In the Home Assistant sidebar (recommended)

1. Install hass_ingress from HACS.

2. Add this to configuration.yaml:

   ingress:
     esp_screens:
       title: ESP Screens
       icon: mdi:monitor-dashboard
       require_admin: true
       url: http://127.0.0.1:8099
   

3. Restart Home Assistant.

What you'll see: ESP Screens in the sidebar. Home Assistant handles the login, just like the app panel on Home Assistant OS.

Through an SSH tunnel

From your own computer:

ssh -L 8099:127.0.0.1:8099 you@docker-host

Then open http://localhost:8099. The Open Devices & services button only works in the sidebar panel, so open Home Assistant yourself when you pair a screen.

Home Assistant on a bridge network

Use this when Home Assistant does not use network_mode: host but publishes its ports under ports:. That is the usual setup with Docker Desktop on Windows and macOS, where "host" means Docker's own Linux VM and not your computer.

Without these steps the sidebar panel shows 502: Bad Gateway: inside the Home Assistant container, 127.0.0.1 is Home Assistant itself, not ESP Screens. The fix is to let ESP Screens share the network of the Home Assistant container, so 127.0.0.1 means the same in both.

1. Move the esp-screens service from the downloaded compose.yaml into the compose file that already holds Home Assistant. Copy the secrets: block at the bottom along with it, and put ha_token next to that file.

2. Change the two services like this. Put the service name of Home Assistant after service::

   services:
     homeassistant:
       # ... your existing settings ...
       ports:
         # ... your existing ports ...
         - 8098:8098                    # camera images for the screens
   
     esp-screens:
       # ... build, restart, init, secrets, volumes and healthcheck stay as they are ...
       network_mode: "service:homeassistant"   # replaces network_mode: host
       depends_on:
         - homeassistant
       environment:
         SCREEN_DEV: "1"
         HA_API: http://127.0.0.1:8123/api     # Home Assistant in the shared network, see the https note below
         HA_TOKEN_FILE: /run/secrets/ha_token
         ESPHOME_CONFIG: /config
         SCREEN_DATA: /data
         SCREEN_CAMERA_URL: http://192.168.1.20:8098   # your computer's address on the home network
   

   Home Assistant on https only? Then http://127.0.0.1:8123 doesn't answer, and https://127.0.0.1:8123 fails the certificate check. Point HA_API at an http address that reaches Home Assistant, such as a reverse proxy in front of it. On Docker Desktop, http://host.docker.internal:<port>/api reaches a port your computer publishes.

3. Start both:

   docker compose up -d
   

4. Check that Home Assistant reaches the app. Replace homeassistant with the name of your Home Assistant container (docker ps shows it):

   docker exec homeassistant curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8099/
   

   What you'll see: 200 means the panel works. 000 means the two containers don't share a network yet.

5. Set up the sidebar panel as in Open ESP Screens. The configuration stays the same.

Good to know:

• Updating Home Assistant recreates its container and takes the shared network away. Run docker compose up -d again afterwards, so ESP Screens is recreated too.
• Camera images: your computer's firewall has to let the screens in on port 8098 (Windows Firewall on Windows).
• USB: Docker Desktop passes no USB ports to containers. Use the download route in Installing screens.

Opening the panel this way is confirmed on Docker Desktop for Windows with WSL 2. Camera images and updates over Wi-Fi have not been tested on Docker Desktop yet. If you try them, please report back in an issue.

Synology and other hosts without git

Compose builds the image from a GitHub address, and that needs git on the host. Synology Container Manager doesn't have it and stops with an error that it can't find git. Build from a local copy instead:

1. Download the source of the current release as a ZIP from the releases page (under Assets, Source code (zip) of the latest release, tagged screens-v0.3.14 at the time of writing). If you have git over SSH, git clone https://github.com/MaxGramser/homeassistant_espscreen.git works too.

2. Unpack it into your esp-screens folder, next to compose.yaml.

3. In compose.yaml, point context: at the screen_manager folder of that copy, for example:

   build:
     context: ./homeassistant_espscreen-screens-v0.3.14/screen_manager
   

4. Continue with Install step 2. In Container Manager, create a Project from this folder instead of running docker compose yourself.

To update, download the new release, change context: to its folder, and build again. There is no ready-made image yet. The Synology steps have not been tested by the project; please report how they go.

Installing screens

From here it works like the app on Home Assistant OS: New screen installs a screen, you pair it under Settings → Devices & services in Home Assistant, and then you choose the tiles. The installation guide walks through it.

How to get the first firmware onto a screen:

After the first install, every update goes over Wi-Fi and needs nothing extra.

Camera images: every screen except the CYD, the Waveshare 3.5-inch and the Hosyond 4-inch shows camera pictures and album covers. The screens load them from port 8098 of the Docker host, so keep that port open to them. By default the app gives the screens Home Assistant's own network address. If the screens reach the Docker host under another address, set SCREEN_CAMERA_URL. More in Camera images.

Claude: the Install for Claude Code button is meant for the Claude Code app on Home Assistant OS. Use Download for claude.ai instead.

Updating

Update the ESP Screen Manager app first, then update each screen.

To update the app, run this in the folder with compose.yaml:

docker compose build --pull
docker compose up -d

This builds the latest release from the main branch, the same one Home Assistant OS users get. Afterwards, ESP Screens shows for each screen whether newer firmware is available.

To stay on one version, replace #main in the context: line of compose.yaml with a release tag:

context: https://github.com/MaxGramser/homeassistant_espscreen.git#screens-v0.3.14:screen_manager

Backups

Home Assistant backups don't include this container. Keep a copy of:

• data/screens.json and data/updates.json: your layouts and update settings.
• The ESPHome folder (esphome by default): the screens' files and Wi-Fi secrets.

data/build, data/esphome, data/idf and data/platformio are caches and can be left out.

Settings in compose.yaml

If something doesn't work

Still stuck? Please open an issue.