Run Denframe on a server
A few features need a setting on the computer that runs Denframe, made by whoever runs it, before Denframe starts. Denframe Desktop and the Home Assistant app need none of these for everyday use.
Set each one in the environment that starts Denframe: the service, the container or the shell that runs it. In the Home Assistant app, the options named below take their place. Restart Denframe after changing one.
Each section names the guide that uses the setting, so a household can see what it is for.
| Variable | What it sets |
|---|---|
DENFRAME_MANAGEMENT_BASE_URL | A secure address for phones |
DENFRAME_RECEIVER_BASE_URL | The address screens and phones reach |
DENFRAME_HANDOFF_HOSTS | Streams a phone may continue |
DENFRAME_LOCAL_ALBUM_ROOTS | Folders for photo albums |
DENFRAME_RECEIVER_APP_ID | Which Cast receiver to use |
DENFRAME_HOSTED_RECEIVER_ORIGIN | Which Cast receiver to use |
DENFRAME_NETWORK_DISCOVERY | TVs that play files themselves |
DENFRAME_UPNP_PLAYBACK | TVs that play files themselves |
DENFRAME_CUSTOM_BLOCK_HOSTS | Hosts a custom data connection may reach |
DENFRAME_INGEST_BASE_URL | The address pushed data arrives at |
DENFRAME_POWER_BI_CACHE_KEY | The Power BI encryption key |
DENFRAME_API_TOKEN | The token for automations |
DENFRAME_ALERT_IMAGE_HOSTS | Hosts an alert's picture may come from |
A secure address for phones
DENFRAME_MANAGEMENT_BASE_URL: the https address a phone opens, for example https://denframe.example.com. Phones and tablets join through a link, so Add a device offers their codes only once Denframe has one; the phone button in Studio's header and Continue on my phone need it too. Wall displays pair without it.
After changing it, restart Denframe and make a new code. See Invite your household.
The address screens and phones reach
DENFRAME_RECEIVER_BASE_URL: the address on your home network that screens, and phones adding photos, use to reach Denframe, for example http://192.168.1.20:8001. Denframe Desktop sets this itself with Enable LAN receiver access… from its menu-bar or tray icon.
See Photos and art and the glossary's LAN receiver access.
Streams a phone may continue
DENFRAME_HANDOFF_HOSTS: the comma-separated hosts of https streams that Continue on my phone may hand to a phone. See Denframe on your phone.
Folders for photo albums
DENFRAME_LOCAL_ALBUM_ROOTS: the directories under which a folder may become an album, as absolute paths separated by : on macOS and Linux, at most 20. Studio offers folders only where this is set; Denframe reads them and never changes them. Folder albums don't work on Windows yet.
See Photos and art.
Which Cast receiver to use
DENFRAME_RECEIVER_APP_ID: left as it is, Denframe casts through its own registered receiver. Set to empty, it stays on the DashCast compatibility receiver, which casts one dashboard, one way. To use a Cast receiver you host yourself (Google's Custom Web Receiver setup (opens in a new tab)), set it to that receiver's app ID, and DENFRAME_HOSTED_RECEIVER_ORIGIN to the https origin it is served from.
In the Home Assistant app these are the receiver_app_id and hosted_receiver_origin options. See Chromecast and Google TV.
TVs that play files themselves
DENFRAME_NETWORK_DISCOVERY=true finds TVs that offer a UPnP media renderer, and DENFRAME_UPNP_PLAYBACK=true lets Denframe play files on them, in a build with network TV support. See Play a video or photo on a screen.
Hosts a custom data connection may reach
DENFRAME_CUSTOM_BLOCK_HOSTS: the comma-separated host names, with no scheme or path, that HTTP API and MCP connections may reach, for example api.example.com. Keep the entries already there when adding one. Only public https hosts on port 443 qualify; listing a private address does not make it eligible.
The address pushed data arrives at
DENFRAME_INGEST_BASE_URL: the https origin producers send pushed data to, for example https://ingest.example.com. Expose only the ingestion route through your proxy, never the administration interface. See Webhook.
The Power BI encryption key
DENFRAME_POWER_BI_CACHE_KEY: a Fernet key that protects Power BI sign-ins, made with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())". Keep it apart from the database and its backups, and keep it the same across restarts: changing it means connecting every Power BI source again. Without it, direct sign-in is refused.
See Power BI · Direct.
The token for automations
DENFRAME_API_TOKEN: a token of at least 20 characters that an automation sends to post an alert. Keep it in the automation's protected settings. See Alerts on a screen.
Hosts an alert's picture may come from
DENFRAME_ALERT_IMAGE_HOSTS: the exact host names, comma-separated with no scheme, port or path, that an alert's picture may come from, such as camera.local. Alert pictures are off until one is listed. See Alerts on a screen.