for Immich

See who's in your photos with whom.

Koram turns the face data already in your Immich library into a live force-directed graph — computed locally, exportable as PNG, CSV, or back into Immich as an album.

Get started View on GitHub

What it does

A graph of who's together, drawn from data you already have.

Co-occurrence, not recognition.

Koram trusts Immich's existing person assignments. It never re-runs a face model — it just counts how often two people appear in the same photo.

Live force layout.

D3-force on HTML canvas. Drag a node to pin it, scroll to zoom, double-click to release. The graph re-flows by edge weight in real time.

Export anywhere.

Download a 2× PNG, save the underlying co-occurrence as CSV, or push the graph back into Immich as an asset in a dedicated album.

How it looks

Your library, one frame.

127 nodes · 1,842 edges

How it works

Three steps from API key to graph.

01 / Connect

Point Koram at Immich.

Drop an API key into /app/config/koram.toml (or pass IMMICH_API_KEY as an env var). Permissions on the right.
02 / Pick faces

Choose who to graph.

Open the side drawer, search and select people. Optionally narrow by date range. Settings persist in your browser.
03 / Compute & explore

Watch the graph form.

Koram sweeps each person's photos with concurrency 8, builds the matrix on disk, and the canvas re-flows live as you drag.

Install

One Compose file. One port. Done.

docker-compose.yml

services:
  koram:
    image: koram:latest
    container_name: koram
    user: 1000:1000
    ports:
      - "5001:5001"
    environment:
      - IMMICH_API_KEY=your-api-key
      - IMMICH_BASE_URL=http://your-immich-host:2283
    volumes:
      - ./config:/app/config
      - ./cache:/app/cache
    restart: always