Frequently asked questions

What is Cimmich?

An open-source, local-first memory companion for Immich. It adds a separate layer for people, pets, places, things, events, documents, search, viewing modes and owner-controlled identity evidence. Immich remains the photo management system.

Is Cimmich part of Immich?

No. It is an unofficial independent project, not affiliated with or endorsed by Immich or OpenAI. "Immich" describes the base product and compatibility target.

Does it replace or modify my Immich installation?

No. It runs beside Immich with its own database, credentials, migrations, documents and backups. Its dedicated Immich integration is read-only. Cimmich records its own collections, labels, favourites and archive choices without modifying Immich or original media.

Why does it look like Immich?

The web shell is derived from Immich so the photo viewer, account and navigation stay familiar. Cimmich adds its own named routes and runs a separate service, database, document store and lifecycle. The inherited source and licence are recorded in the repository.

Cimmich is at http://127.0.0.1:3413. Your normal Immich address still takes you to Immich.

What does Community Preview mean?

It is for technically comfortable Immich users who can inspect Docker Compose, use the checked-in installer, keep a Cimmich backup and report reproducible problems. Workflows and schemas may still change.

Preview 18 requires exact Immich 3.1.0. Its guided install has been tested on macOS and Linux Docker hosts. Windows has not yet been tested. Internet-facing and multi-user operation are outside this community preview.

Which version should I install?

Community Preview 18, using its named tar or ZIP bundle plus SHA256SUMS. The main branch carries living development and may be ahead of the named release.

Can I try it without my own photographs?

Yes. The isolated Cedar House demo runs its own loopback-only Immich and Cimmich stack on fictional, rights-cleared media so you can walk through matching, evidence correction, connected stories, search and archive checks without using your own photographs.

How long does the first start take?

A cold source build commonly takes 4 to 10 minutes while locked dependencies and container layers are prepared. Hardware, network and Docker cache all vary it. Use ./tools/install.sh --status rather than repeatedly recreating the stack. The Guide covers deeper checks. No CPU or memory minimum has been certified.

What does matching need?

Cimmich is the matcher. A local Face-analysis provider supplies the observations and embeddings it searches. Other organisation, stories, documents and archive tools do not need that provider. Face-analysis model files are installed separately.

Does Cimmich identify people automatically?

No. Cimmich ranks candidates from compatible, owner-confirmed evidence, but only you can accept who a Face belongs to. When the evidence is not strong enough, it can leave the Face unmatched.

Why separate Face, Head, Body and Presence?

They represent different truth. A clear Face may support matching. A visible Head, a Body appearance, or your own knowledge that someone was present can complete the memory without contaminating the face reference set.

Can Cimmich handle pets?

Yes. Pets have their own profiles, media, documents and optional provider evidence, and their evidence types and vector spaces stay separate. Only an owner assignment creates pet identity evidence; Cimmich may abstain and hold an observation as Unknown.

What are Enhanced and Guided?

Enhanced enables additional local analysis components. Face providers extract observations and embeddings; Cimmich builds, evaluates and runs the matcher from approved examples. You still accept, correct or reject every identity suggestion.

Guided is an optional authenticated machine-readable interface. Software you choose can discover only the operations and viewing level you granted. Cimmich stores no model-provider API key and makes no provider requests itself.

Does local-first mean nothing can ever leave my computer?

Core Cimmich and its checked local operators need no hosted model. If you enable map services or connect external software through Guided, data may leave according to that service or client's behaviour and the access you grant it. Cimmich cannot make third-party software private.

Is Private mode encryption?

No. Standard, Personal and Private are presentation filters inside an authenticated session. Private mode may add a local screen password, but it is not encryption, an access-control list, a vault or protection from the host administrator. Think "what is comfortable to show on this screen", not "who can access the host". Immich continues to own account access.

Why can an Immich user reset the Private password?

Because Private mode is a presentation filter, not a second account system. An already authenticated Immich user can reset or disable it so a forgotten value never becomes an unrecoverable lockout. Any reset ends the open Private session.

Why do I sign in and also create an API key?

They do different jobs. Your Immich session authenticates the browser. The dedicated read-only key lets the Cimmich service read library inventory and original assets for the features you choose. Create it with current-user read, asset read and download, Face read and Person read only, enter it in Cimmich's write-only settings field, and revoke it from Immich whenever you like.

Can I remove Cimmich without harming Immich?

Yes, using the installer-created operator. disable and up preserve Cimmich state. Confirmed removal targets only Cimmich's project, volumes and dedicated state directory. Back up first: removal deletes Cimmich-owned context, decisions and documents. It does not remove Immich or original media.

How do backup and restore work?

A normal backup covers Cimmich's database, documents, configuration and provider state for the same installation. Restore verifies checksums, project identity, schema compatibility and semantic counts before replacement.

Portable export carries the database and document store to another installation while excluding original media, Immich credentials and provider artifacts. Verified complete-file SHA-256 can reconnect identical bytes after inventory even when paths or Immich identifiers changed. Changed bytes remain a new asset.

How was Cimmich built?

Benji holds product direction, acceptance and release authority. The product problem, privacy and identity boundaries, compatibility target, acceptance gates and release decisions are human-owned. Living development uses substantial AI assistance coordinated and accepted under that authority. The historical Build Week tooling and the inherited Immich-derived web foundation are separately attributed.

What existed before OpenAI Build Week?

The underlying archive problem, identity and matching research, semantic-search exploration and an experimental Immich-derived UI seed all predated the event. The Build Week work and the prior-work boundary are recorded in the repository, and the exact submission is preserved as v1.0.0-build-week. Later product work does not rewrite it.

How is Cimmich licensed?

AGPL-3.0-only, with preserved upstream and third-party notices. The repository contains an adapted Immich web foundation. Cedar House and Space Trip carry their own licence, attribution, provenance and checksum material, which must travel with the packs.

Where do I report a bug or a security issue?

Use the repository's issue forms with a minimal synthetic reproduction. Never attach real photographs, embeddings, credentials, database dumps, host paths or private library details.

For a security issue, do not open a public issue. Use the repository's private vulnerability-reporting route.