Home Assistant
The Frameleaf integration for Home Assistant puts your library on your smart-home dashboards. It adds:
- Sensors for how many photos and videos you have, when a phone last backed up, storage, Cloud Backup and things that need attention.
- A picture for dashboards and photo frames: today’s memory, or one of your favourites.
- A button that looks for new files in your library folders.
- Frameleaf events that start automations, such as a notification when Cloud Backup fails or a Studio export finishes.
It reads from your own server over your home network. Nothing goes through Frameleaf Cloud.
Looking for Claude or ChatGPT instead? See Connect AI assistants.
Before you start
Section titled “Before you start”- Home Assistant 2025.1 or newer.
- Home Assistant has to reach your Frameleaf server, normally on the same home network.
- For sensors beyond your own photo and video counts, an API key. For storage, Cloud Backup, things to look at, the scan button and Frameleaf events, the key has to belong to an administrator.
Install the integration
Section titled “Install the integration”With HACS
Section titled “With HACS”- In Home Assistant, open HACS.
- Open the menu and choose Custom repositories.
- Add
https://github.com/Frameleaf/frameleaf-appwith the type Integration. - Find Frameleaf in HACS and choose Download.
- Restart Home Assistant.
By hand
Section titled “By hand”- Download the Frameleaf app source and open
integrations/home-assistant/custom_components. - Copy the
frameleaffolder into thecustom_componentsfolder of your Home Assistant configuration. Makecustom_componentsif it isn’t there. - Restart Home Assistant.
Add Frameleaf
Section titled “Add Frameleaf”- In Home Assistant, open Settings → Devices & services.
- A Frameleaf server on your network is found by itself and shows under Discovered. Choose Add. If it isn’t there, choose Add integration, search for Frameleaf, and type the address you use to open Frameleaf, such as
http://frameleaf.local:2283. - Under How to sign in, choose one of the two ways below.
Sign in through Frameleaf (recommended)
Section titled “Sign in through Frameleaf (recommended)”Home Assistant asks to see your library and nothing more. It can’t change, share or delete anything.
- Choose Sign in through Frameleaf.
- Frameleaf’s Allow an app page opens. Sign in if you’re asked to, then choose Allow.
- Home Assistant says Frameleaf is connected.
Home Assistant then shows under Settings → Your sign-in & privacy → Connected apps in Frameleaf, where you can remove it at any time. After that, Home Assistant asks you to sign in again.
This way gives you the Photos and Videos sensors and the Picture.
Use an API key
Section titled “Use an API key”Choose this for the rest of the sensors, the scan button and Frameleaf events.
- In Frameleaf, open Settings → Your sign-in & privacy → API keys and make a key. See API and CLI.
- In Home Assistant, choose Use an API key and paste the key.
- To start automations from Frameleaf, turn on Send Frameleaf events to Home Assistant. This needs an administrator’s key.
A key belongs to one account. Home Assistant shows that account’s library.
What you get
Section titled “What you get”| In Home Assistant | Shows | Which sign-in |
|---|---|---|
| Photos | How many photos are in your library | Either |
| Videos | How many videos are in your library | Either |
| Picture | Today’s memory, or one of your favourites | Either |
| Last phone backup | When a phone last finished backing up | API key |
| Storage used | Space used on the server | Administrator’s API key |
| Storage used (percent) | How full the server’s storage is | Administrator’s API key |
| Cloud Backup | Backed up, Backing up, Waiting, Failed, Stopped or Not set up | Administrator’s API key |
| Things to look at | How many items Frameleaf says need attention | Administrator’s API key |
| Look for new files | A button that starts a scan of the library folders | Administrator’s API key |
Sensors refresh every five minutes.
A picture for dashboards and photo frames
Section titled “A picture for dashboards and photo frames”The Picture shows a photo from today’s memory. When there’s no memory today, it shows one of your favourites. It changes about every ten minutes.
It only ever shows photos from your timeline. Locked, hidden, archived and trashed photos are never shown, and neither are videos.
To put it on a dashboard, add a Picture entity card and choose the Frameleaf Picture:
type: picture-entityentity: image.frameleaf_pictureshow_name: falseshow_state: falseYour entity’s name may differ. Find it under Settings → Devices & services → Frameleaf.
Frameleaf events
Section titled “Frameleaf events”With an administrator’s key and Send Frameleaf events to Home Assistant on, Frameleaf tells Home Assistant when one of these happens:
| Event | When |
|---|---|
studio.export.completed |
A Studio export finished |
cloud.backup.completed |
Cloud Backup finished |
cloud.backup.failed |
Cloud Backup failed |
clients.gallery.approved |
A client approved a gallery in Clients |
cloud.job.completed |
A Frameleaf Cloud job finished |
Home Assistant fires each one as frameleaf_event. Use it as a trigger:
automation: - alias: Tell me when Cloud Backup fails trigger: - platform: event event_type: frameleaf_event event_data: event: cloud.backup.failed action: - service: notify.notify data: title: Frameleaf message: Cloud Backup failed. Open Frameleaf to see why.Each event carries event, occurred_at, subject, detail and delivery_id. Leave out event_data to trigger on every Frameleaf event.
More ideas:
- Flash a light when a long Studio export finishes.
- Send a message when a client approves their gallery.
- Show a warning card when Things to look at is above zero, or when Storage used (percent) passes 90.
- Press Look for new files on a schedule after a camera card is copied to the server.
How events get there
Section titled “How events get there”To send events, the integration adds one workflow in Frameleaf for each event, named Home Assistant: and the event. You can see them in Workflows. Removing the integration from Home Assistant removes them again.
Each message is signed with a secret that only your Frameleaf server and your Home Assistant know. Home Assistant ignores a message that isn’t signed, is more than five minutes old or was already received.
Home Assistant remembers the last 500 messages to catch repeats, and forgets them when it restarts. Write automations that are safe to run twice.
If Home Assistant is on a home address
Section titled “If Home Assistant is on a home address”Frameleaf only sends events to secure (https) addresses unless you allow home addresses. If your Home Assistant is at an address such as http://homeassistant.local:8123, an administrator has to turn on Allow automations to call devices on my network in Frameleaf under Settings → Server name & welcome. Then reload the Frameleaf integration in Home Assistant so it can add its workflows.
Remove Frameleaf from Home Assistant
Section titled “Remove Frameleaf from Home Assistant”In Home Assistant, open Settings → Devices & services → Frameleaf and delete it. Its workflows are removed from Frameleaf.
To stop Home Assistant from the Frameleaf side, remove it under Connected apps, or delete the API key it uses.
If something isn’t working
Section titled “If something isn’t working”| What you see | What to do |
|---|---|
| Frameleaf could not be reached at this address | Type the address you use to open Frameleaf in a browser, with http:// or https:// and the port. Check that Home Assistant is on the same network as the server. |
| Frameleaf did not accept this API key | Copy the whole key, and check that it hasn’t been deleted under API keys. |
| This Frameleaf server does not let new apps connect themselves | An administrator turned off Let new apps register themselves. Ask them to turn it on in Registered apps, or sign in with an API key. |
| That is a different Frameleaf account | When signing in again, use the account you added the first time. |
| Sign in to Frameleaf again | Home Assistant was removed under Connected apps, or its API key was deleted. Sign in again or paste a new key. |
| Storage, Cloud Backup or Things to look at are missing | Those need an administrator’s API key. Sign in through Frameleaf only gives the photo and video counts and the picture. |
| No events arrive | Check that you used an administrator’s key and turned on Send Frameleaf events to Home Assistant. If Home Assistant is on a home address, turn on Allow automations to call devices on my network, then reload the integration. |
| The picture never changes | It changes about every ten minutes, and only when today’s memory or your favourites hold more than one photo that can be shown. |
| Frameleaf isn’t found by itself | Choose Add integration and type the address. Discovery only works when both are on the same network. |
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.