Immich Crosslink
Links between Immich apps, on the same computer
Immich Crosslink is a small, open protocol that lets apps working with an Immich server point to each other. Right-click a photo in one app, choose Show in another app, and that app opens the same photo, album, person or place. No app needs to know the others in advance: each announces itself when it is installed, and the operating system tells the others who is there.
It is at version 1.0, released in Immich Mount and Immich Gallery. Anyone may implement it, and proposals are welcome.
How it works
Every participating app announces itself in the metadata it installs (its Info.plist on macOS, its desktop entry on Linux): the version it follows, and what it can show. It also registers the URL scheme
immich-crosslink, which delivers links to it.An app asks the system which other apps registered the scheme, reads their announcements without starting them, and offers Show in app for each that shows the item, by the name and icon the system knows.
Choosing one sends that app a link naming the item the way Immich’s own web app does, with the server’s address:
immich-crosslink:///albums/<album>/photos/<asset>?server=https%3A%2F%2Fphotos.example.comThe receiving app checks it is signed in to that server, and shows the item. A link only ever shows something: it never changes, shares or deletes anything.
Every app’s settings carry the same switch, Immich Crosslink, on by default, with a Learn more… link to this page, and a switch for each app found.
Read more
- The protocol: announcing, links, Immich paths, sending, receiving, finding participants, settings, security, versioning, conformance.
- Implementing it: announcing the app, registering the scheme, and finding the others on macOS, GNOME and KDE, with code.
- Test links: links with their expected results, for testing an implementation.
- Participants: the apps that take part, and the version each follows.
- Roadmap: two implementations and 1.0, reached; next, reference implementations in Rust and Swift.
- Changelog.
- Contributing: how to propose a change or add your app.
Why a protocol
Apps that hard-code each other couple tightly: each must know the other’s links and follow its changes. With one shared scheme and Immich’s own item paths, an app supports every other participant at once, and a new app joins by registering the scheme. The paths are Immich’s, so a crosslink, an Immich web address and an Immich mobile deep link name an item the same way.