imogen

imogen은 홈랩을 위한 자체 호스팅 사진·동영상 라이브러리입니다. 당신이 통제하는 하드웨어에 사진을 보관하면서, 그 위에 무엇이든 만들 수 있도록 열어 줍니다: 웹 인터페이스, REST API, 모바일 앱용 TypeScript SDK, 그리고 AI 어시스턴트가 라이브러리를 검색할 수 있게 해 주는 MCP 엔드포인트까지.

• 균등한 타임라인 — 사진은 촬영 당시의 비율을 유지한 채 날짜별로 묶입니다

• 카메라가 만들어 내는 모든 것 — HEIC, RAW, JPEG, 동영상, Live Photos

• 설치형 — 웹 인터페이스는 PWA이며 오프라인에서도 작동합니다

• 두 가지 로그인 방식 — 로컬 계정, 또는 Authentik, Keycloak, Google 등 OIDC를 지원하는 어떤 서비스를 통한 단일 로그인(SSO)

• 그 위에 만들 수 있도록 설계 — OpenAPI, SDK, OAuth 2.1 서버를 갖추어, 서드파티 앱이 나중에 덧붙여지는 게 아니라 일급 시민입니다

• 사람 — 선택적 얼굴 그룹화, 전적으로 당신의 서버에서만 실행됩니다

• 금고 — 암호를 입력해야만 볼 수 있는 사진으로, 그 밖의 모든 곳에서 숨겨집니다

• 공유 — 앨범이나 사진 한 장을 링크로 게시하되, 선택적 비밀번호, 만료일, 다운로드 허용/차단을 지정할 수 있습니다

• 관리 — 사람 초대, 계정 정지, 처리 큐 확인, 앱 연결 해제, 현재 공개된 모든 항목 확인

• 에이전트 준비됨 — URL 하나로 Claude나 Grok을 라이브러리에 연결합니다

실행하기

curl -O https://raw.githubusercontent.com/ergofobe/imogen-server/main/docker-compose.yml
docker compose up -d

http://localhost:3000을 엽니다. 처음 만드는 계정이 관리자가 됩니다.

그것이 설치의 전부입니다. imogen은 Postgres가 필요하며, compose 파일이 하나를 함께 띄워 줍니다. 메시지 브로커도, 캐시도, 실행할 사이드카도 없습니다.

설정

모든 것은 환경 변수이며 시작 시 검증됩니다 — 서버는 잘못된 구성으로는 부팅을 거부하고, 부하가 걸린 뒤에 실패하지 않습니다.

관리

처음 만들어진 계정이 관리자가 됩니다. 그 계정의 설정(Settings) 페이지에는 /admin으로 연결되는 링크가 있으며, 계정, 초대, 처리 큐, 연결된 애플리케이션, 저장소, 공유 링크를 여기서 관리합니다.

이 영역은 단순히 다른 사람에게 닫혀 있을 뿐만 아니라, 서버가 존재하지 않는 경로에 대해 주는 것과 똑같은 평범한 404를 응답합니다. 그래서 찾아내려 해도 찾을 수 없습니다. 관리 패널을 스캔하는 어떤 것에도 아무 정보도 주지 않습니다.

폐쇄된 서버에 누군가를 추가하려면 초대장을 만들고 링크를 보내세요. 링크는 한 번만 표시되고 해시로만 저장되므로, 링크를 잃어버리면 폐기하고 새로 만들면 됩니다.

단일 로그인(SSO)

모든 OIDC 공급자를 imogen에 연결할 수 있습니다. 공급자에서 리다이렉트 URI를 https://photos.example.com/api/v1/auth/oidc/callback으로 설정하세요.

IMOGEN_OIDC_ISSUER: https://auth.example.com/application/o/imogen/
IMOGEN_OIDC_CLIENT_ID: ...
IMOGEN_OIDC_CLIENT_SECRET: ...
IMOGEN_OIDC_LABEL: Sign in with Authentik
IMOGEN_OIDC_ADMIN_VALUE: imogen-admins   # members of this group become administrators
IMOGEN_OIDC_ACCOUNT_URL: ''              # optional; guessed for Authentik and Keycloak

기존 로컬 계정은 확인된 이메일 주소로 연결되므로, SSO를 켜도 누구도 버려지지 않습니다.

공급자는 자신이 관리하는 계정의 이름과 이메일을 소유합니다. imogen은 로그인할 때마다 이 값을 다시 읽어 설정에서 읽기 전용으로 표시하고, 공급자의 자체 계정 페이지로 연결합니다. 그 링크가 추측된 곳이 아닌 다른 곳을 가리켜야 한다면 IMOGEN_OIDC_ACCOUNT_URL을 설정하세요.

IMOGEN_OIDC_ADMIN_VALUE를 설정하면 관리자 상태가 이 값을 따릅니다 — 누군가 그룹을 떠나면 관리자 상태도 제거됩니다. 설정하지 않으면 imogen은 역할을 건드리지 않으므로, 로컬에서 승격된 관리자는 계속 관리자로 남습니다.

리버스 프록시 뒤에서

imogen은 일반 HTTP를 제공하며 TLS를 종료하는 무언가 뒤에 위치할 것을 기대합니다. 세션이 합리적인 주소를 기록하도록 X-Forwarded-For를 전달하고, 동영상 업로드를 위해 큰 요청 본문을 허용하며, IMOGEN_PUBLIC_URL을 외부 URL로 설정하세요.

photos.example.com {
    reverse_proxy localhost:3000
    request_body { max_size 8GB }
}

Related MCP server: immich-mcp

사람

imogen은 얼굴을 찾아 각 사람이 등장하는 사진을 그룹화할 수 있습니다. 한 번 이름을 붙이면 그 사람이 나오는 모든 사진을 둘러볼 수 있습니다. 감지와 인식은 당신의 서버에서 실행되며, 어떤 사진도 외부로 전송되지 않습니다.

이 기능은 당신이 켜기 전까지 꺼져 있습니다. People 페이지에서 켤 수 있습니다. 켜면 약 190MB의 인식 모델을 다운로드하고 기존 라이브러리를 백그라운드에서 스캔합니다.

• 금고에 있는 사진은 절대 스캔되지 않으며, 사진을 금고에 넣으면 그 사진에서 이미 찾은 얼굴도 잊어버립니다.

• 이름을 붙이기 전까지는 아무도 이름을 갖지 않습니다. 이름 없는 그룹은 이름을 붙일 수 있도록 표시되며, 둘 다 숨길 수 있습니다.

• 그룹화는 두 사람을 하나로 합치기보다 한 사람을 두 그룹으로 나누는 쪽으로 치우칩니다. 여러 그룹을 선택하고 같은 사람이라고 알려 주면 됩니다.

모델에 관한 참고 사항. imogen은 InsightFace의 SCRFD와 ArcFace를 사용하며, 이들은 비상업적 연구용으로 라이선스가 부여되어 있습니다. imogen은 어떤 모델도 포함하지 않습니다. 기능을 켤 때 당신의 서버가 모델을 다운로드하므로, 라이선스 결정은 당신의 몫입니다. 상황에 맞지 않는다면 기능을 꺼 두세요.

금고

어떤 사진들은 부주의한 스크롤 한 번에 노출되어서는 안 됩니다. 금고로 옮기면 그 사진은 라이브러리에서 완전히 빠져나갑니다: 타임라인에도, 검색에도, 앨범에도, 공유 링크에도, AI 어시스턴트가 볼 수 있는 어떤 곳에도 없습니다.

금고를 여는 데는 암호가 필요하며, 이미 로그인되어 있어도 다시 입력해야 합니다.

알아 두면 좋은 몇 가지 결정 사항:

• 암호는 계정 비밀번호가 아닙니다. 단일 로그인 계정에는 로컬 비밀번호가 없고, 더 중요한 것은 이미 로그인된 세션만으로는 부족해야 한다는 점입니다 — 노트북이 열려 있다고 해서 이것까지 열려서는 안 됩니다.

• 브라우저 세션으로만 열 수 있습니다. API 토큰이나 MCP 커넥터는 충분히 유효한 자격 증명을 가질 수 있어도 들어갈 방법이 없습니다. 이것은 누락이 아니라 설계입니다.

• 15분 후에 스스로 닫히며, 요청하면 즉시 닫힙니다.

• 누구도 당신을 위해 재설정해 주지 않습니다. 복구 경로가 없으며, 그것이 바로 핵심입니다.

사진을 금고로 옮기면 모든 앨범에서도 제거됩니다. 앨범은 공유할 수 있는 것이기 때문입니다.

AI 어시스턴트 연결하기

imogen은 MCP를 지원하므로, 어시스턴트가 당신의 허락 아래 — 그리고 오직 그 허락 아래 — 라이브러리를 검색하고, 사진을 보고, 앨범을 관리할 수 있습니다.

Claude.ai 또는 Grok: https://photos.example.com/mcp를 가리키는 커넥터를 추가하세요. 손으로 붙여 넣을 것은 없습니다. 클라이언트가 imogen을 발견하고 스스로 등록한 다음, 정확히 무엇을 요청하는지 밝히는 동의 화면으로 안내합니다. 설정에서 언제든지 철회할 수 있습니다.

로컬 에이전트 (Claude Code 또는 stdio로 MCP를 지원하는 모든 것):

bun add -g @imogen/mcp
imogen-mcp login --server https://photos.example.com

{ "mcpServers": { "imogen": { "command": "imogen-mcp" } } }

어시스턴트가 할 수 있는 일

모든 도구는 연결된 계정에 한정됩니다. 무엇이든 삭제하는 도구는 없으며, 금고 안의 어떤 것도 이 도구들에 보이지 않습니다. 이름을 붙인 사람만 찾을 수 있습니다 — 이름 없는 그룹과 숨겨진 사람은 찾을 수 없습니다.

그 위에 만들기

API는 /api/v1/docs에 문서화되어 있으며, OpenAPI 3.1 설명은 /api/v1/openapi.json에 있습니다.

imogen-sdk에는 다섯 가지 언어용 클라이언트가 있습니다 — TypeScript, Rust, Python, Swift, Kotlin. TypeScript에서는:

bun add @imogen/sdk

import { ImogenClient } from '@imogen/sdk'

const imogen = new ImogenClient({ baseUrl: 'https://photos.example.com', token })

const page = await imogen.assets.list({ q: 'harbour', limit: 50 })
for await (const asset of imogen.assets.iterate()) console.log(asset.originalFilename)

// Picks its protocol by size: one request for photos, a resumable session for video.
await imogen.assets.uploadMany(files, {
  onFileComplete: (outcome, done, total) => console.log(`${done}/${total}`),
})

모바일 앱 작성하기

모든 SDK에는 네이티브 앱에 필요한 OAuth 클라이언트가 포함되어 있습니다 — Swift와 Kotlin용이 정확히 이것을 위해 있습니다. 하드코딩된 것은 없습니다. 앱이 스스로 등록하므로, 사용자가 가리키는 어떤 imogen 서버에서도 작동합니다.

import { OAuthClient } from '@imogen/sdk'

const oauth = new OAuthClient('https://photos.example.com')
const client = await oauth.register('My Photo App', ['myapp://oauth'])
const pending = await oauth.beginAuthorization(client.client_id, 'myapp://oauth')

// Open pending.authorizationUrl in the system browser, then on the callback:
const tokens = await oauth.completeAuthorization(pending, callbackUrl)

업로드는 콘텐츠 기준으로 멱등적입니다. 서버가 이미 가진 사진을 다시 보내면 두 번째 복사본을 저장하는 대신 기존 자산을 반환하므로, 동기화 루프가 단순해도 여전히 정확합니다. deviceAssetId를 전달하면 클라이언트는 자체 원장을 유지하지 않고도 이미 보낸 것을 알 수 있습니다.

호스트 이름을 묻는 대신 페어링

위 흐름에서도 앱이 어떤 서버와 통신할지 알아야 하며, 자체 호스팅 라이브러리는 소유자가 선택한 주소에 있습니다. 휴대폰 키보드로 그 주소를 입력하는 것은 이런 앱을 설치할 때 가장 최악의 순간이므로, 브라우저가 대신 처리합니다.

설정 → 기기 → 기기 페어링은 일회성 티켓을 만들고, 서버 URL과 코드를 모두 담은 QR 코드로 렌더링합니다. 앱이 그 사각형을 읽고 나머지를 처리합니다:

val invitation = parsePairingUri(scanned) ?: return
val oauth = OAuthClient(invitation.serverUrl)
val paired = oauth.pair(invitation.code, "imogen for Android", "imogen://oauth", Build.MODEL)

카메라로 비추는 것은 토큰이 아니라 티켓입니다. 일회용이며, 5분간 유효하고, 정확히 하나의 인가 코드를 얻습니다 — 기기를 떠난 적 없는 PKCE 챌린지에 묶여 있으므로, 누군가의 화면을 사진으로 찍는 것만으로는 충분하지 않습니다. 그 결과 나오는 권한 부여는 평범한 것이며, 다른 것과 마찬가지로 연결된 애플리케이션 아래에 표시됩니다.

같은 페이지에서 티켓을 링크로도 제공하므로, 이미 웹 인터페이스를 보고 있는 휴대폰에서는 링크를 눌러 앱을 바로 열 수 있습니다.

개발하기

git clone https://github.com/ergofobe/imogen-server
cd imogen-server
bun install

docker compose -f docker/compose.dev.yml up -d     # Postgres
export DATABASE_URL='postgres://imogen:imogen@localhost:5432/imogen'
bun run db:migrate

bun run dev        # API on :3000
bun run dev:web    # web on :5173, proxying to the API

bun test          # needs the dev Postgres running
bun run typecheck
bun run lint

테스트는 목(mock) 대신 실제 Postgres와 실제 HTTP 서버를 대상으로 실행됩니다. 제대로 맞추는 게 중요한 부분 — OAuth 흐름, 커서 페이지네이션, 미디어 파이프라인 — 은 정확히 목이 틀리게 만들기 쉬운 부분입니다.

구성

클라이언트 라이브러리는 자체 저장소인 imogen-sdk에 있습니다. TypeScript, Rust, Python, Swift, Kotlin으로 작성되어 있으며, 하나의 공유된 계약 픽스처(contract fixtures) 집합으로 검증됩니다. @imogen/shared — 이 서버가 검증에 사용하고 OpenAPI 문서를 생성하는 기반이 되는 Zod 스키마 — 도 그곳에 있습니다. 그것이 API 계약이며, 계약은 그것을 지켜야 하는 클라이언트와 함께 있어야 합니다.

packages/server/src/api/sdk-contract.test.ts는 그 합의의 이쪽 편입니다. 실제 앱을 띄우고 배포된 TypeScript 클라이언트를 통해 그 앱을 구동함으로써, 두 반쪽이 일치함을 보여줄 수 있는 유일한 지점을 제공합니다.

설계 문서는 docs/superpowers/specs에 있습니다.

아직 미구현

시맨틱 검색(사진을 설명해서 찾는 기능)은 구현되지 않았습니다. 스키마에는 에셋에 벡터 컬럼이 예약되어 있고 검색 인덱스도 마련되어 있어 마이그레이션 없이도 추가될 수 있습니다. 하지만 현재 검색은 파일 이름, 설명, 장소, 카메라 메타데이터, 그리고 이름을 붙인 사람들만 대상으로 합니다.

또한 빠져 있는 것: 역지오코딩(좌표는 좌표로 표시됨), 비디오 트랜스코딩, S3 스토리지. 스토리지 드라이버가 인터페이스이므로 S3는 누군가 원할 때 추가할 수 있는 국소적 변경입니다.

얼굴 그룹화는 작동하지만 알아둘 만한 거친 부분이 있습니다. 정면이고 조명이 적절한 얼굴은 잘 읽지만, 프로필, 선글라스, 모션 블러, 그리고 저장된 평균으로 따라잡을 수 없을 만큼 얼굴이 빨리 변하는 어린아이들은 실망스러운 부분입니다. 이 기능은 두 사람을 한 그룹으로 합치는 쪽보다 한 사람을 두 그룹으로 나누는 쪽으로 오류를 범합니다. 전자는 클릭 한 번으로 고칠 수 있지만 후자는 누군가의 사진을 다른 사람의 이름으로 분류해 버리기 때문입니다.

라이선스

AGPL-3.0-or-later. 수정된 imogen을 서비스로 실행한다면 수정 사항을 공개해야 합니다.