# Configuration

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/run/config-file/>.

Change a setting in **Settings** for the easy route. Use a file or environment variables when you
want the deployment to control it. Settings saves to the database; the app normally only reads
`~/.immich-memories/config.yaml`.

## Quick start config

```yaml
tier: basic
immich:
  url: "https://photos.example.com"
  api_key: "${IMMICH_API_KEY}"

trips:
  homebase_latitude: 50.85
  homebase_longitude: 4.35

output:
  directory: "~/Videos/Memories"
```

Both home coordinates are needed for trips. Everything else keeps its default.
Every server URL (`immich.url`, `llm.base_url`, `network.geocoding_url` and the rest) must start
with `http://` or `https://`; anything else is refused when the file loads or a setting is saved.
`immich.public_url` matters when `immich.url` is a cluster or
container name your browser cannot open, set it to the address you do open, and the "View in Immich" and
"Open in Immich" links and notification links use it. Requests still go to `immich.url`.
`auth.public_url` is the address of Immich Memories itself; it does not set the Immich link address.
Keep the file at permissions `600` if it contains credentials.
Docker can use [environment variables](https://sam-dumont.github.io/immich-memories/docs/run/environment-variables.md) without a file.

## Where a setting comes from

For each key, the first source that sets it wins:

| Priority | Source |
| - | - |
| 1 | Environment variables, including the ones the image sets |
| 2 | `config.yaml` |
| 3 | Values saved from Settings or the config CLI |
| 4 | Deployment defaults (`IMMICH_MEMORIES_DEPLOYMENT_*`) |
| 5 | Built-in defaults |

Command-specific flags can override these for that command. LLM key shorthands have a
[special rule](https://sam-dumont.github.io/immich-memories/docs/run/environment-variables.md#shorthands).
The UI greys out settings controlled by the file or environment and shows their source.

Authentication (`auth.*`; the generated first password is kept as a hash in `generated-login.json` beside the config file) and server (`server.*`) settings, like the database location, are set
only in the environment or `config.yaml` and take effect on restart; Settings shows them
read-only. So are the keys that pick a program the server runs, a file it writes or the host that
receives your Immich keys: the render worker URL and token, and the model and helper paths.
[Network and security](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md#settings-only-the-operator-sets) lists them. The [configuration reference](https://sam-dumont.github.io/immich-memories/docs/run/reference/configuration.md) has the full precedence
rules, including what happens to a stale value an older version saved.

### Keys pinned by Docker

The shipped Compose file and image always set these, so YAML and Settings cannot override them:

| Runtime key | Docker value |
| - | - |
| `immich.url` | `IMMICH_URL`, default `http://immich-server:2283` |
| `editorial.preparation.detector_cache_dir` | `/home/immich/.immich-memories/models/huggingface` |
| `output.directory` | `/app/output` (image default) |

`IMMICH_API_KEY` also pins `immich.api_key` when nonempty. The auth pair takes effect when both
values are nonempty. Added runtime environment lines pin their keys too.
Change values in Compose or `.env`, then run `docker compose up -d`.
To let Settings control a Compose-pinned key, remove its environment line and any YAML value.
Keep the model cache and output paths on mounted volumes.

`TIER` (`basic`, `gpu` or `full`) pins `tier` like any environment variable: a `tier` in
`config.yaml` or Settings is ignored with a warning naming it. Change the tier in `.env`.
The service addresses that tier implies stay editable defaults.
Home coordinates are not forwarded by the base Compose file: save them in Settings or YAML.

Inspect the same result from the CLI:

```bash
immich-memories config show llm immich.url
```

Secrets print as `***`. `--config PATH` selects one file for the CLI, UI, authentication and reloads.
If a configured store is unreadable, startup stops rather than silently using different settings.
Fix the database, or use `IMMICH_MEMORIES_SKIP_STORED_SETTINGS=1` for a deliberate recovery start
without its saved settings. A new URL for a server that receives a credential (Immich, an extra
account, the LLM, the caption server, MusicGen, ACE-Step) needs that credential typed again in
the same save, when one is set.

### Moving a key out of the file

To let Settings control a key currently in YAML:

```bash
immich-memories config move-to-db llm.model automation.cooldown_hours
```

Use runtime paths without `advanced.`. The [reference](https://sam-dumont.github.io/immich-memories/docs/run/reference/configuration.md#moving-a-key-out-of-the-file)
has the exact rules for what can't move.

### Secrets in the database

Saving credentials from Settings or the CLI needs `IMMICH_MEMORIES_SECRET_KEY`:

```bash
openssl rand -base64 32
```

Keep the output with your other secrets. On Docker, put it in `.env` and recreate:

```ini
IMMICH_MEMORIES_SECRET_KEY=paste-the-generated-value-here
```

```bash
docker compose up -d
```

Without it, keep credentials in environment variables or YAML; secret saves are refused. Losing
the key means re-entering saved credentials. This is separate from the UI's
[session signing key](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md#sessions). [What's encrypted and how](https://sam-dumont.github.io/immich-memories/docs/run/reference/configuration.md#secrets-in-the-database).

## What each top-level section is for

| Want to change | Section | Guide |
| - | - | - |
| Immich connection or extra accounts | `immich` | [Accounts](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md) |
| Home base and trip detection | `trips` | [Memory types](https://sam-dumont.github.io/immich-memories/docs/make/memory-types.md#trip) |
| Sharing, transitions and captions | `defaults` | [Sharing](https://sam-dumont.github.io/immich-memories/docs/reference/selection-internals/family-audience-duplicates.md#sharing-levels) |
| Resolution, codec and HDR | `output` | [Photos and HDR](https://sam-dumont.github.io/immich-memories/docs/make/photos-and-live-photos.md) |
| Photo timing | `photos` | [Photos](https://sam-dumont.github.io/immich-memories/docs/make/photos-and-live-photos.md) |
| Titles, maps and music | `title_screens`, `audio` | [Titles, maps and music](https://sam-dumont.github.io/immich-memories/docs/make/titles-maps-music.md) |
| Upload destination | `upload` | [What Immich sees](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md#what-immich-sees) |
| Place names and map tiles | `network` | [Outside calls](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md#geocoding-and-maps) |
| A daily check for a newer release | `updates` | [Update check](https://sam-dumont.github.io/immich-memories/docs/run/reference/privacy-egress.md#update-check) |
| Disk usage and persistence | `cache`, `database` | [Caches](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/health-logs-cache.md#caches), [database](https://sam-dumont.github.io/immich-memories/docs/run/database.md) |
| A model or service | `advanced.llm`, `advanced.inference`, `render` | [Add-ons](https://sam-dumont.github.io/immich-memories/docs/get-started/choose-your-setup.md) |
| Login or daily schedule | `advanced.auth`, `advanced.automation` | [Authentication](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md), [automation](https://sam-dumont.github.io/immich-memories/docs/make/automate.md) |

Every key/default is in the [config reference](https://sam-dumont.github.io/immich-memories/docs/reference/config-reference.md).
The [annotated example](https://github.com/sam-dumont/immich-memories/blob/main/examples/config.example.yaml)
is there when you need a larger file.

## Everyday keys and advanced keys

Everyday settings live at the top level. Tuning sections live under `advanced:`:

```yaml
advanced:
  llm:
    provider: openai-compatible
    base_url: "http://localhost:8000/v1"
    model: "your-model-name"
```

Both placements are accepted and merge key by key; a top-level key wins a tie. Environment
variables and CLI paths always omit `advanced.` (`llm.model`). Use `config show` to check
effective values after editing; the [full merge and validation rules](https://sam-dumont.github.io/immich-memories/docs/run/reference/configuration.md#everyday-keys-and-advanced-keys)
are in the reference.

## Paths in the config are host paths

Paths refer to the machine **running the app**. Inside Docker, `output.directory` must be a
container path, not a desktop folder. The image already sets `/app/output`; mount your host folder
there. Environment variables override file paths, and that includes the image's own
`IMMICH_MEMORIES_OUTPUT__DIRECTORY=/app/output`: an `output.directory: /output` in `config.yaml`
is ignored while that variable is set, and films would land in the container's writable layer and
vanish when that container is replaced. Mount the output volume at `/app/output`, or set the environment variable to
the path you mounted. `preflight` flags missing paths; the
[reference](https://sam-dumont.github.io/immich-memories/docs/run/reference/configuration.md#paths-in-the-config-are-host-paths) lists every path key,
including model/cache overrides.

## Where the store and logs live

Without a `database.url`, the run history store and the scheduler's log files (macOS) sit
beside the config file that was loaded, not always under `~/.immich-memories`. A plain
`immich-memories` run still gets `~/.immich-memories/store.db` and `~/.immich-memories/logs/`,
since that is where the default config lives. `--config /path/to/other/config.yaml` gets
`/path/to/other/store.db` and `/path/to/other/logs/` instead, so a second setup, a test library
say, never mixes into the main one. Loading an explicit config leaves the default home's
application directory and permissions alone. Other storage settings keep their own defaults:
cache paths still point under `~/.immich-memories`, and the web session signing key stays in
`~/.immich-memories/.storage_secret` unless `IMMICH_MEMORIES_STORAGE_SECRET` is set. Newly created
thumbnail and video cache directories are owner-only. For an isolated installation, set absolute
cache paths and supply a separate session signing key. Paths written with `~` refer to the running
process's home. Upgrading a `--config` run that already has history under
the old path gets a startup warning and a `preflight` line naming both paths, with how to
keep the old store (`database.url`) or move it (`store backup` / `store restore`).

## Environment variable substitution

Use `${VAR_NAME}`, not `$VAR`. Substitution happens only in `config.yaml`, for [credentials and
selected service/path fields](https://sam-dumont.github.io/immich-memories/docs/run/reference/configuration.md#environment-variable-substitution); it is not applied to every string. Settings and environment
variables are always taken as written: a Settings value containing `${` is refused there and by
the config CLI. For any config key, the reliable alternative is its
[`IMMICH_MEMORIES_SECTION__FIELD` variable](https://sam-dumont.github.io/immich-memories/docs/run/environment-variables.md#the-pattern).

## Compute tier

Keep the tier you selected during installation. Use `tier: auto` only when you want the app to
choose from detected inference hardware and reader configuration. It can select GPU on an Apple
Silicon Mac before captions are ready. [Requirements and tiers](https://sam-dumont.github.io/immich-memories/docs/run/requirements.md#the-preparation-tier)
explains the required services and how deployment defaults interact with Settings.

## Immich API compatibility

Leave `immich.api_version: auto`; v2 and v3 are detected. `v2`/`v3` overrides are for diagnosing
unusual proxies. An unknown major stops the run.

```bash
immich-memories config test
```

This only checks authentication/API compatibility. It does not generate or upload.

## A second Immich account

Follow [A second account](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md) to connect a partner's library, bind matching people
and select both accounts. The primary remains the only upload target.

Set `immich.native_sharing: true` to use verified shared person IDs on Immich 3.2,
or people sharing on Immich 3.3. It defaults to `false`. Both owner keys remain required;
see [native identities](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md#native-person-identities).

## Footage the camera roll did not shoot

Filename patterns and the camera-EXIF filter exclude doorbell recordings, screenshots and saved
messaging-app images. [Selection boundaries](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/family-audience-duplicates.md)
and the [analysis config reference](https://sam-dumont.github.io/immich-memories/docs/reference/config-reference.md) explain how to adjust them.

## Upload back to Immich

```yaml
upload:
  enabled: true
  album_name: "Memories"
```

Off by default. The web Render panel has its own upload choice. An uploaded film gets its title as
its Immich description (and its story summary, when the experimental `title_screens.llm_titles` is
on), and tags naming the release that made it and the day. `film_tags: true` also tags it with
its memory type, years and stories. [Privacy](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md#what-immich-sees) lists every write.

## Outside calls

Geocoding and map tiles are off by default. Enable them under `network` only after reading
[what leaves your network](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md).

## Enabling a reader

A model name or endpoint on its own does not turn the reader on. Set
`advanced.llm.enabled: true` to use it for the music mood and, on Full, for selection; one section
covers every model call. Naming special days and trips and writing the film's summary also needs
the experimental `title_screens.llm_titles` (or `--llm-title` for one run). Year, month, season,
person, couple, birthday, holiday and on-this-day films always get the app's own title. With the
reader off, `preflight` warns that a reader is configured but disabled.

## Reader concurrency

Use `advanced.llm.reader_concurrency` only when tuning model throughput. The default is one
request for loopback, a private IP or a bare service name, and four for a dotted DNS name or
public IP. A dotted LAN name still counts as hosted. Accepted overrides for external servers:
1 to 16; the owned reader always runs one request at a time.
See [Reader setup](https://sam-dumont.github.io/immich-memories/docs/better/reader.md).

## Invalid configuration

A YAML configuration must be a mapping of setting names to values. An empty file or `null`
means no file overrides; scalar values and lists are rejected. Unknown authentication keys
are errors, so a misspelled `enabled` cannot silently leave authentication off.
Configured service URLs also follow the [address policy](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md#configured-service-addresses).

## Product tier names

The product tiers are `basic`, `gpu` and `full`. Basic uses CPU classifiers and rules; it is
not restricted to NAS hardware. `auto` chooses from available inference capability. The old
`nas` value is rejected; use `basic`.
