Like most self-hosters, I love Immich for managing my photo library. However, looking through my collection, I had hundreds of older, low-resolution, and blurry family photos that desperately needed a restoration pass. I had a powerful Nvidia GPU sitting in my home lab, but I didn't want to resort to clunky, manual command-line scripts to process everything. I wanted a seamless, native-feeling UI experience right inside the browser.
So over the course of a few hours dispersed over a long weekend between spending time with my family, I ideated, built, and published Forge for Immich: an open-source Chrome extension and backend server pipeline that brings AI-powered restoration right into the Immich web interface.
Here is the story of how it came together, the architecture behind it, and how an "agent-first" engineering approach made it possible to ship in such a short time.
The Vision: Seamless UI, Local Power
I had two strict requirements for this project:
- Stay true to the Self-Hosted spirit: The project had to be completely open-source, private, and available for other self-hosters to deploy locally. No third-party cloud APIs.
- Seamless integration with Immich: I didn't want to download photos from Immich, upload them to a separate web UI, process them, and then re-upload them. A Chrome extension felt like the perfect solution. It overlays a native-feeling experience directly onto the existing Immich frontend, allowing me to browse, select, review, and accept modifications on the fly.
To make this happen without opening up security vulnerabilities or over-complicating the frontend, I settled on a three-tier architecture:
Plaintext
┌──────────────────┐ ┌──────────────────────┐ ┌─────────────────┐
│ Chrome Extension │───▶│ Forge Server │───▶│ Immich Server │
│ (browse, pick, │ │ (FastAPI + GPU │ │ (REST API) │
│ review, accept) │◀───│ PyTorch pipeline) │◀───│ │
└──────────────────┘ └──────────────────────┘ └─────────────────┘
talks only to Forge holds the Immich API key,
pulls originals / uploads / stacks
By keeping the Immich API key securely stored on the Forge Server, the Chrome extension only ever needs to talk to my local Forge backend. The Forge Server acts as the heavy-lifter: it pulls the original image from Immich, runs it through an advanced PyTorch AI pipeline on the GPU, uploads the enhanced version back to Immich, and neatly stacks it with the original.
Diving Into the AI Pipeline
Building the backend gave me a fantastic opportunity to dive deeper into the world of open-source computer vision and image restoration models. I wanted to offer a comprehensive suite of enhancements, which led me to assemble a specialized PyTorch pipeline using four incredible open-source projects:
- DDColor (Colorization): For breathing life into old black-and-white photos. I chose to vendor this directly under
server/app/pipeline/ddcolor/(licensed under Apache-2.0) to ensure tight integration and control over the inference process. - Real-ESRGAN (Upscaling): For turning low-res artifacts into sharp, high-resolution images. This is handled as a pip dependency combined with pre-downloaded weights (licensed under BSD-3-Clause).
- GFPGAN (Face Restoration): Essential for fixing the weird distortions that can happen to human faces during aggressive upscaling. This runs as a pip dependency with downloaded weights (licensed under Apache-2.0).
- CodeFormer (Optional Face Backend): An alternative, highly robust face restoration backend that handles heavily degraded faces incredibly well. It utilizes downloaded weights under the S-Lab License 1.0 (non-commercial).
Balancing these different libraries, managing their CUDA/GPU memory footprints, and ensuring they executed sequentially without crashing the FastAPI server was a fun engineering puzzle to solve over a Saturday afternoon.
Secret Weapon: Claude Agents
If you told me five years ago that I could build a Chrome extension, a FastAPI backend, package a complex GPU-accelerated Docker image, and pass Chrome Web Store review in a few days, I would have laughed.
The secret weapon that made this timeline possible was agent-first engineering.
Instead of treating AI tools like a simple autocomplete or a search engine replacement, I utilized AI agents as collaborative pairs-programmers. I offloaded the boilerplate—like setting up the Chrome extension manifest v3 configuration, writing standard FastAPI CORS middlewares, and drafting the multi-stage Dockerfile needed to properly expose CUDA to the PyTorch container—to the agent.
This allowed me to focus 100% of my mental energy on the architecture, debugging model inputs/outputs, and refining the user experience. Agent-first engineering didn't write the app for me; it removed the friction of context-switching, allowing me to build at the speed of thought.
Shipping It to the World
By Sunday night, the pieces were talking to each other. By Monday, I was cleaning up code and packaging it for the Chrome store.
I'm incredibly proud to say that Forge for Immich is fully live and ready for you to self-host:
- Backend Docker Image: Ready to pull and run with NVIDIA container toolkit support on Docker Hub.
- Frontend: Download the published Chrome Extension directly from the Chrome Web Store.
- Source Code: Check out the repo, submit an issue, or contribute a PR over on GitHub.
If you are a fellow self-hoster running Immich and you have an Nvidia GPU waiting for work, give Forge a spin. It’s been a blast to build, and it has genuinely transformed how I look back at my oldest digital memories.
Happy hosting!