magic-frame

English · Deutsch · 🌐 magicframe.dev

Runs entirely on your home network — no cloud account, no domain needed.

Drag & drop editor · Real live updates · Smart-home · Calendar · Weather · Picture-frame mode

What is it?

Magic Frame turns any browser-capable screen — tablets, kitchen monitors, old TVs, picture frames — into a self-hosted display for your home:

• Family board — shopping list, todos, calendar, weather
• Smart-home hub — live Home Assistant entities, scene buttons, camera pop-ups, notification tiles
• Digital picture frame — wallpaper rotation from Immich or WebDAV, subtle clock on top
• Status display / signage — power usage, timers, quick posts, rotating notices (non-commercial — see license)

One view per display, each with its own URL, layout and wallpaper. Everything syncs live over WebSocket — change a widget on your laptop and every display updates in under 100 ms, no refresh.

Where does it run?

Install it once on any box in your home network — that machine becomes "the server", your displays just open its IP in a browser. No cloud account, no domain, no DDNS required. Postgres ships inside the Docker stack.

Rule of thumb: as long as you don't actively set up a domain, everything stays local on your LAN.

Quick Start

Two commands on a fresh Linux box. Skip step 1 if you already have Docker:

# 1. Install Docker (with Compose plugin) — official one-liner
curl -fsSL https://get.docker.com | sh

# 2. Install Magic Frame
curl -fsSL https://raw.githubusercontent.com/jeremiaa/magic-frame/main/deploy/install.sh | bash

macOS / Windows? Install Docker Desktop instead of step 1, then run step 2 in a terminal.

No curl? Install it (sudo apt install curl / sudo dnf install curl) — or use git instead: git clone https://github.com/jeremiaa/magic-frame.git && cd magic-frame && ./deploy/install.sh

The installer clones the repo, generates secrets, pulls the pre-built multi-arch images (ghcr.io, amd64 + arm64 — no 20-minute compile on a Pi) and starts the stack: app + Postgres + Caddy. Then open http://<your-ip> → setup flow → create the first admin → done. Integrations (Google/Microsoft Calendar, OpenWeatherMap, Todoist, Home Assistant, Immich) are all added later through the UI.

Updating to a new version

The same command updates you — run it from the magic-frame folder any time a new version is out. It pulls the latest code, grabs the new images, and restarts. Your data, login, secrets and uploaded modules are never touched (none of that lives in git):

cd magic-frame && ./deploy/install.sh

No separate git pull needed — the installer does it for you. To build from source instead (forks, local changes): ./deploy/install.sh --build

Demo

Editor — drag widgets onto the grid, configure in the inspector

Dashboard — all your views and live system status at a glance

_{Watch the full ~1 min walkthrough (create view → drag widgets → configure inspector → save → live-sync to displays).}

In the wild

Real-world setups across different hardware. Same project, different layouts, different rooms.

Big portrait monitor on the wall

Info layout: clock, two upcoming calendar events, three live HA notifications, current temperature and 4-day weather forecast over a rotating Immich wallpaper. Quiet and glanceable for a hallway, office or bedroom wall.	Notifications close-up: rule-based tiles that auto-show when something happens (washing machine done, "feed Milou", dryer done) and auto-hide once acknowledged. Wallpaper keeps running underneath.

Picture-frame tablet on a side table

_{Scene-button layout: a small tablet in a real photo-frame mount. Quick-access HA buttons, small clock, current temperature, rotating wallpaper underneath.}

📸 More screenshots — dashboard, views, editor, modules

Dashboard — entry point with live status

_{3 stat cards (views · live-sync · integrations) + system-status strip (HTTPS, DDNS, HA, Todoist, modules, backups, security) + mini-previews of all views at a glance.}

Views — all dashboards & displays

_{Each view is its own URL for one display — portrait for the tablet, landscape for the TV. Live previews show the real widget arrangement per view.}

What it looks like on the display

Smart-home display: clock, 4 scene/device buttons (HA services), weather with 4-day forecast.	Minimal / picture frame: just clock + weather, the wallpaper rotation is the main element.	In action: tap on a button opens the matching pop-up — here a colour picker for a lamp incl. power toggle.

View editor — drag & drop

_{24-column grid, widget catalog on the left, inspector on the right. Auto-snapshot before every save, TV-sync to all connected displays.}

Modules — upload your own widgets

_{The core widgets ship with every install. Custom modules via JS-bundle upload — hot-loading, no container restart needed.}

Features

Widgets (18 core)

Editor & live view

• Drag & drop builder on a 24-column grid — multiple views (portrait/landscape), one URL per display
• Stack & overlay widgets with a drag-sortable layer list (z-order)
• HA-triggered show/hide — bind any widget to an entity state: doorbell rings → camera pops up over the photos, auto-hides after n seconds. Home Assistant can also "press" dashboard buttons remotely
• Light + dark editor theme · per-view auto-refresh (off / 1–24 h) · auto-snapshots before every save (last 20)
• Live sync via WebSocket to every connected display · i18n German + English

Integrations

• Home Assistant — live entity updates over one WebSocket (pushed, not polled)
• Google Calendar and Microsoft 365 via OAuth (multiple accounts) — plus plain iCal feeds
• Immich + WebDAV as wallpaper sources · Todoist · OpenWeatherMap (optional)

Custom modules

Upload a JS bundle through the UI — hot-loaded on every display, no container restart. Build helper (node scripts/build-module.mjs), manifest with field schema, example module in examples/modules/hello/. See docs/custom-modules.md — community modules & PRs welcome.

Architecture

One Docker stack with three services, all on the same host:

Data flow on save: browser edits a widget → Next.js API → snapshot to Postgres → Socket.IO event → every display re-renders in under 100 ms. Persistent volumes (Postgres data, settings, wallpaper cache, Caddyfile, certs) survive every update.

Maintenance

cd magic-frame && ./deploy/install.sh                # update — data, login and modules survive
docker compose logs -f app                           # logs (app / caddy)
docker compose exec db pg_dump -U postgres magicdashboard | gzip > backup-$(date +%F).sql.gz   # DB backup

cd magic-frame
git fetch --force --tags origin
git reset --hard origin/main
./deploy/install.sh

Troubleshooting

dig @<your-dns> ha.example.lan AAAA   # NXDOMAIN here is the problem — NOERROR is correct
dig @<your-dns> ha.example.lan A      # this one resolves fine

Documentation

Tech stack

Next.js 16 · React 19 · Postgres 16 + Prisma 7 · Caddy 2 (xcaddy custom build) · Tailwind CSS 4 · Socket.IO · react-grid-layout · iron-session · otplib · esbuild

Contributing

Issues with a clear reproduction are especially welcome — they directly drive releases (most of v1.1 came straight from community requests). PRs are happily reviewed; for larger changes please open an issue first so we can sort out what fits.

❤️ Support

Magic Frame is free for home use and built in my spare time. If it hangs on your wall and you want to say thanks:

License

Polyform Noncommercial 1.0.0 — open-source-style, allows free use, modification, distribution, and contribution. Commercial use (selling, SaaS offering, embedding in your own products) is not permitted without a separate license.

For commercial inquiries: magicframeapp@gmail.com

_{Vibe-coded with Claude.}