Warning
Note
The recommended setup exposes nothing to the internet. The walkthrough is at deploy/SETUP.md.
- The panels — one URL for everything
- Setup guide
- Demo video
- Features
- How it works
- Configuration
- Security
- Required API-key permissions
- Documentation
- Contributing
- Changelog
| Doc | What it answers |
|---|---|
| Using the panels | the one URL to remember, what each panel does, and where sharing actually happens |
| Setup guide | the recommended install, step by step, nothing on the internet |
| AI-agent install | paste-into-your-agent instructions that adapt to any reverse proxy |
| Manual install | compose example, Caddy snippet, the three proxy routes |
| API key guide | the exact permissions to tick, and why each one |
| Configuration reference | every setting, its default, and when to change it |
| Hardening guide | how exposed to be, and what the addon changes about hosting |
| Doc | What it answers |
|---|---|
| Architecture | the whole design on one page — components, data flow, iron rules |
| Wire protocol | how two servers pair, share and stream, and what the connection proves |
| Sync loops | how albums, invitations and withdrawals reconcile |
| Byte path | where the actual pixels come from when you view a shared photo |
| HTTP surface | every route the addon serves, and who may call it |
| Immich API layer | the accounts the addon creates and the Immich quirks it absorbs |
| Contributing | the working contract for humans and AI agents — conventions, tests, invariants |
| Demo rig | three complete households in Docker, plus the e2e suites that gate every change |
Two households, one shared album. Created, shared, joined and commented on, all in the stock Immich apps: watch the demo.
| Features | Stock apps | Notes |
|---|---|---|
| Share an album with a person on another Immich server or instance | Yes | picked in Immich's own share menu |
| Albums join a person, not a whole server | Yes | your parents won't see the lads' holiday |
| Nothing exposed to the internet | Yes | servers connect directly, dialling out |
| Link two servers with a one-line pairing code | Yes | works once, expires in 15 minutes |
| Shared photos cost ~2KB of your disk each | Yes | full quality streams from the owner |
| Cross-server comments | Yes | both ways, credited to the writer |
| Videos | Yes | playable versions sync, originals stream |
| Public view-only share links | Yes | via immich-public-proxy, optional |
| Joinable public share links | Yes | optional, if you host Immich publicly |
| Unshare / unlink cleans everything up | Yes | leaving an album works from the app too |
| Runs on a Raspberry Pi | — | one small container, one pinned dependency |
The addon runs in its own Docker container next to Immich and talks to it over the normal API. It never modifies Immich itself. If the addon dies, Immich carries on as if it was never there.
To reach the other family's server, the two addons open an encrypted connection directly to each other (built on iroh). Each server is addressed by a cryptographic key rather than a URL, and the connection finds its way through home routers on its own. That is why neither side needs to expose anything: the servers dial out, nothing listens.
When someone shares an album with you, your server creates a lightweight copy: real album, real rows in your Immich, but each photo is a tiny placeholder. When you look at a photo, the full-quality version streams live from the owner's server. Nobody accumulates copies of anyone else's library, and if the owner stops sharing, the photos are simply gone.
You need Docker, an Immich admin API key, and a reverse proxy in front of Immich on your own network. The addon sits behind three small proxy routes so the stock app can fetch shared photos. None of it has to be reachable from the internet. Full walkthrough: deploy/SETUP.md.
- Install the addon on both servers. Options, easiest first:
- Point an AI coding agent (Claude Code, Cursor, etc.) at deploy/INSTALL-AI.md. It adapts the proxy routes to whatever reverse proxy you run.
- Run
bash deploy/install.sh. It detects your Immich, starts the addon and prints the routes to add. - Or do it by hand: see deploy/.
- Open the hub. In a web browser go to
https://<your-immich>/immich-shared-albums/while signed in to Immich. That one URL is the whole surface — bookmark it. An admin sees a choice between Your shared albums and Server settings and pairings; everyone else goes straight to their own albums. - Link the two servers. From Server settings and pairings, click Create pairing link and send the code to the other household over WhatsApp or wherever. Their admin pastes it into their own hub at the same address.
- Share an album. Open it in Immich, tap share, pick the person. Done. Remove them from the album to unshare, or unlink the whole server from the hub.
What each panel does, and what a person can do in it: docs/using-the-panels.md.
Want to send view-only links to people who don't run a server? Add immich-public-proxy as the one public piece of your setup. It renders share links as a read-only gallery and exposes nothing else. Point its IMMICH_URL at this addon instead of Immich and shared photos from other servers show up in those links too. You can then turn off "Allow other Immich users to join albums via shared links" in the panel, so links are strictly for looking at.
If your Immich is already public, share links do more: the album page shows a join card, and a visitor who runs this addon can join the album from it. Same install, one panel setting.
Two settings matter when you install; everything else has a working default (full list in deploy/configuration.md).
| Variable | What to put there |
|---|---|
ISA_IMMICH_API_KEY |
Required. An API key from an admin account, created with the permissions below. |
ISA_HOUSEHOLD_NAME |
The name the other family sees, e.g. The Smiths. |
In Immich: Account settings → API keys → New API key, ticking the permissions in the API key guide — it lists each one and why the addon needs it. Scoped like that, a leaked key can't touch your photos or settings. The addon checks its key at startup and tells you if anything is missing.
Your server stays as private as it is today, the two servers prove their identity to each other cryptographically, and the addon is built so that even its own credentials can't do much damage.
- Server-to-server traffic only ever flows between servers that were deliberately paired, over an end-to-end encrypted connection. There is no server-to-server HTTP at all.
- The pages you use (panel, joining) require you to be signed in to your own Immich. The addon has no accounts or passwords of its own.
- Every photo request from another server is checked against what was actually shared with them. Reaching an endpoint is never permission to use it.
- The API key doesn't need
all— see the API key guide. Scoped like that, a leaked key can't delete or edit photos, can't change settings, and can't create a broader key. - The addon can't touch your photos. The only assets it ever deletes are the placeholder stubs it created itself, and the delete code refuses anything it doesn't own.
- Share links are bearer credentials, same as in stock Immich: whoever has the link (and its password, if set) can use it. Treat them accordingly, or keep link-joining switched off.
- Small surface: one process, SQLite, one native dependency (the peer transport), a codebase you can read — a ~10 MB image that idles at ~7 MB. deploy/exposure.md covers how exposed to be, and what the addon changes about hosting.
- If a photo's owner is offline you'll see placeholders until they're back. Recently viewed photos survive from cache. Your own library is never affected.
- New photos show up on the app's next sync, usually within seconds.
- Leaving an album cleans up everything the join created. The addon notices the app's normal "Leave album" too.
Semver, where a major bump means older peers can't sync with you. Versions come from commits automatically and every change is gated on the e2e suite plus a browser lane. A weekly run against the latest Immich release catches breakage early. See CHANGELOG.md.
Questions, suggestions and PRs are all welcome. And if this saved your family from the cloud, you can say thanks:
