Skip to content

Installation

Check the requirements before installing. Immich Lounge supports Immich 3.1 or later; birthday memories require Immich 3.3 or later.

Companion

The companion image supports AMD64 (x86-64) and ARM64 hosts with a 64-bit operating system. Docker selects the matching image automatically; no platform override is needed.

If you already run immich with Docker Compose, the simplest setup is to add one service to that existing compose file.

Use a normal Docker port mapping on 4383. Do not expose the companion to the public internet.

Preferred setup

Choose the Compose layout that fits your installation. Keep the companion on the same trusted LAN as your Roku and Immich server, and persist its data in a Docker volume.

Keep the companion on your LAN

Use a normal Docker port mapping on 4383. The companion does not provide public-internet authentication.

Add the service and named volume below to your existing Immich Compose file. Keep its existing services and volumes.

Companion service and volume
# docker-compose.yml
# Add this service to your existing Immich docker-compose.yml.
services:
  immich-lounge-companion:
    image: ghcr.io/immich-lounge/immich-lounge-companion:latest
    container_name: immich-lounge-companion
    pull_policy: always
    ports:
      - "4383:4383" # change the left side if 4383 is already in use; do NOT expose publicly
    volumes:
      - immich-lounge-data:/data
    environment:
      - ASPNETCORE_URLS=http://+:4383
    restart: unless-stopped

volumes:
  immich-lounge-data:

From that stack's folder, start only the companion:

docker compose up -d immich-lounge-companion

Create a folder for the companion and save this as docker-compose.yml:

docker-compose.yml
# docker-compose.yml
# Add this service to your existing Immich docker-compose.yml.
services:
  immich-lounge-companion:
    image: ghcr.io/immich-lounge/immich-lounge-companion:latest
    container_name: immich-lounge-companion
    pull_policy: always
    ports:
      - "4383:4383" # change the left side if 4383 is already in use; do NOT expose publicly
    volumes:
      - immich-lounge-data:/data
    environment:
      - ASPNETCORE_URLS=http://+:4383
    restart: unless-stopped

volumes:
  immich-lounge-data:

From that folder, start the companion:

docker compose up -d

The companion stores settings, profiles, schedules, and cache data under /data.

Why localhost does not work for the Immich URL

The companion and Roku both need to reach the Immich server. localhost refers to the device making the request, so it does not identify your Immich server from the Roku. Use its LAN host name or IP address.

To update the companion later, run these from its Compose folder:

docker compose pull immich-lounge-companion
docker compose up -d immich-lounge-companion

Reference: docker-compose.yml.

Roku apps

Add the Roku apps to your account:

App Channel Store Add Link
Immich Lounge Open in Store Add to Account
Immich Lounge Screensaver Open in Store Add to Account

Install on your Roku:

  • Immich Lounge
  • Immich Lounge Screensaver

The channel handles normal playback. The screensaver is configured from Roku system settings.

First Roku setup

Open Immich Lounge on Roku and enter the companion URL:

http://192.168.1.10:4383

Then choose a profile.

Roku companion connection screen

Manual companion setup on Roku uses the companion host and port 4383.

Screensaver setup

From the Roku home screen, go to Settings -> Theme -> Screensavers, switch the active screensaver to Immich Lounge Screensaver, then open Configure Screensaver.

The screensaver can share the same companion URL and use either the same or a different profile.

For the step-by-step Roku flow, see Using the Roku Apps and Roku's own help article: How to change the screensaver on your Roku streaming device.

Network notes

You usually only need two paths to work:

  • Roku to companion on port 4383
  • Roku to immich on your immich server port, usually 2283

The Roku fetches media and most metadata directly from immich. The companion is not a media proxy.

After install