# ImmichFrame

ImmichFrame turns a spare screen into a digital photo frame for your [Immich](</app/immich/>) library. Open your ImmichFrame address on a TV, a tablet on the kitchen bench, an old phone or a Raspberry Pi, and it plays a slideshow of your photos, with an optional clock, weather and the date, place and people in each picture.

You choose what it shows: everything, chosen albums or people, favourites, memories, or a date range. There are also ImmichFrame apps for Android, Android TV, iOS and Apple TV if a device's browser isn't a good fit.

**When does hosted ImmichFrame make sense?**

- **Your photos are already in Immich on ElfHosted**, and you'd like them on the wall instead of only on your phone.
- **You want one setup for every screen.** The slideshow settings live in your ImmichFrame instance, so each frame only needs its address.
- **You don't want a Raspberry Pi in a drawer running yet another server.** We run ImmichFrame for you, keep it updated and back up its settings daily.

ImmichFrame reads from an Immich server, so you'll need one. It doesn't have to be on ElfHosted, but ImmichFrame comes set up to point at your ElfHosted Immich address.

[Get a 7-day trial of ElfHosted ImmichFrame! 🪄](<https://store.elfhosted.com/product/immichframe/>)

## How do I access ImmichFrame?

ImmichFrame is available:

- From your dashboard: [https://your-username.elfhosted.com](<https://your-username.elfhosted.com>)
- Directly: [https://your-username-immichframe.elfhosted.com](<https://your-username-immichframe.elfhosted.com>)

> [!NOTE]
>
> **Signed-in users see their own URLs**
>
> The addresses above show the general pattern. [Sign in](<https://docs-internal.elfhosted.com/app/immichframe/>) and these become your personal, clickable links.

## How do I use it?

ImmichFrame's address is **not** behind your ElfHosted login, because photo frames, TVs and the ImmichFrame apps can't sign in to it. ImmichFrame has two protections of its own instead: an admin password for its settings, and a secret that every frame must present. The secret is set up for you.

### 1\. Set an admin password

ImmichFrame's settings page is at [https://your-username-immichframe.elfhosted.com/admin](<https://your-username-immichframe.elfhosted.com/admin>). It stays locked until you choose an admin password. Set one with [ElfBot](<https://docs-internal.elfhosted.com/app/elfbot/>) (or ask Sam), and ImmichFrame restarts to use it:

Quick-paste into ImmichFrame's environment variables using ElfBot

```
IMMICHFRAME_ADMIN_PASSWORD=<a long password of your choosing>
```

This variable always wins, so if you ever forget the password, set a new one the same way.

### 2\. Open your frames from the dashboard link

Every ImmichFrame on ElfHosted requires a private secret from each frame, and we generate yours for you. The **ImmichFrame tile on your ElfHosted dashboard** opens your frame with the secret already in the address. Open it once on each browser-based frame (a TV browser, a tablet) and it's remembered.

For an ImmichFrame app (Android, Android TV, iOS, Apple TV), copy that address from the dashboard and enter the address and the secret in the app's settings.

Treat that link like a password: anyone who has it can watch your slideshow. To choose your own secret instead (for example, to lock out a frame you've given away), set it with [ElfBot](<https://docs-internal.elfhosted.com/app/elfbot/>). Then reopen the dashboard link on your frames: the dashboard shows the new secret after its next refresh.

Quick-paste into ImmichFrame's environment variables using ElfBot

```
IMMICHFRAME_AUTHENTICATION_SECRET=<a long random value of your choosing>
```

The **Client authentication secret** field on ImmichFrame's admin page has no effect on ElfHosted.

### 3\. Connect your Immich account

1. In Immich, open **Account Settings → API Keys** and create a new key for ImmichFrame.
2. In ImmichFrame's admin page, open the account. The server address is already set to your ElfHosted Immich ([https://your-username-immich.elfhosted.com](<https://your-username-immich.elfhosted.com>)); change it if your Immich lives elsewhere.
3. Replace the placeholder API key with the one you just created, and use **Test connection**.
4. Check the date filters. Instances created before 5 October 2026 started with **Images until date** set to 2 January 2020, which limits the slideshow to older photos: clear it to include everything.
5. Choose what to show (*albums, people, favourites, memories, videos*) and save.

Changes apply without a restart. To blend in a partner's photos, add a second account with an API key from their Immich account.

### Optional extras

- **Weather:** add a free [OpenWeatherMap](<https://openweathermap.org/appid>) API key and your latitude and longitude.
- **Calendar:** add one or more `.ics` calendar addresses under **Web calendars** to show upcoming events.
- **Look and feel:** interval, transitions, clock format, split view for portrait photos, and pan and zoom are all on the admin page too.

### Where settings live

ImmichFrame keeps its settings in a small database in your ElfHosted storage, and the admin page is the only place to change them. Editing the `Settings.yaml` file in ImmichFrame's config folder has no effect after the first start.

## ImmichFrame also works with

- [x] [Immich](</app/immich/>)

## How do I get support for ImmichFrame?

1. For general use of ImmichFrame, refer to the [official site](<https://github.com/immichFrame/ImmichFrame>) or to one of the links in the resources section below.
2. For specific support re your ElfHosted configuration / account, see the [ElfHosted support options](</get-help/>)!

## ImmichFrame resources

- [ImmichFrame (*official site*)](<https://github.com/immichFrame/ImmichFrame>)
- [ImmichFrame Documentation](<https://immichframe.dev>)
