Default paths

Everything Fregata writes lives in well-known places. This page is the canonical map.

Top-level layout

~/Fregata/
├── config/                     # FRIGATE_CONFIG_DIR
│   ├── config.yaml             # the file you edit (config.yml also works)
│   ├── config_backups/<date>/  # the last 7 versions of config.yaml, saved on quit
│   ├── .runtime_state.json     # UI/MQTT toggles that persist across restarts
│   ├── frigate.db              # SQLite events / recordings index
│   ├── model_cache/            # downloaded Frigate+ models
│   ├── models/                 # your own ONNX (conventional)
│   └── ssl/                    # cert.pem + privkey.pem (optional)
├── media/                      # FRIGATE_MEDIA_DIR
│   ├── recordings/<YYYY-MM-DD>/<HH>/<camera>/<MM.SS>.mp4   # date and hour in UTC
│   ├── clips/                  # snapshots and thumbnails; no event MP4s
│   │   ├── <camera>-<event-id>-clean.webp   # event snapshots
│   │   ├── thumbs/<camera>/    # event thumbnails (webp)
│   │   ├── previews/<camera>/  # hourly preview videos
│   │   ├── review/             # review item thumbnails (webp)
│   │   ├── export/             # thumbnails for exports
│   │   ├── triggers/<camera>/  # semantic search trigger thumbnails (webp)
│   │   └── faces/              # face-recognition snapshots
│   └── exports/                # user-initiated exports (MP4)
├── temp/                       # FRIGATE_CACHE_DIR — Basic RAM disk only;
│   ├── nginx_cache/            #   Smart memory uses a hidden ~/Library/Caches/ path
│   └── go2rtc.yaml             #   (see "The cache backing" below)
├── run/                        # FRIGATE_RUN_DIR (SSD-resident)
│   └── *.sem                   # POSIX semaphore tracker files
├── logs/                       # FRIGATE_LOG_DIR (SSD-resident)
│   ├── frigate/current         # live Frigate log (capped ~5 MiB, oldest 2 MiB chopped on overflow)
│   ├── go2rtc/current          # live go2rtc log (same cap + chop)
│   └── nginx/current           # live nginx log  (same cap + chop)
└── state/                      # FRIGATE_STATE_DIR (SSD-resident)
    ├── running                 # this run's marker: pid, start_ts, boot_time
    ├── crash_count.txt         # cumulative crash counter
    ├── last_crash.json         # most recent resolved crash signature
    ├── exit_reason.json        # non-graceful teardown breadcrumb (hung-shutdown / force-killed)
    ├── child_crash.json        # supervisor's go2rtc/nginx crash attribution
    ├── crash_breadcrumb.json   # unhandled-Python-exception breadcrumb
    └── homekit/                # Apple Home: each camera's identity and pairings

Recorded video lives in recordings/, apart from exports and the hourly preview videos. Despite the name, clips/ has no event MP4s: a clip for an event (/api/events/<event-id>/clip.mp4) is cut from the recording segments when you request it. See Recordings & retention.

run/, logs/, and state/ live on the SSD — semaphore state has to survive reboots, crash/exit diagnostics have to survive the crash they’re describing, and logs persist across restarts and crashes so you can always see what happened. temp/ lives in RAM and is destroyed on quit — see the next section for the two possible backings. Everything else is what you’d expect, with one exception: .runtime_state.json records the on/off toggles you flip from the web UI or MQTT (camera enable/disable, detection, recordings, snapshots, audio) so they survive a Frigate restart instead of reverting to whatever config.yaml says. Delete it if you ever want a restart to fall back to the config file’s values exactly.

config_backups/ holds a copy of your config for each of the last 7 versions Fregata ran on, one dated folder each (2026-11-01_18-04-12/config.yaml, in your Mac’s local time). A copy is made when Fregata quits or restarts normally after running on a valid config, and skipped when the config hasn’t changed since the newest copy, so restarting doesn’t push older versions out. Restore one by copying it back over config.yaml. Fregata only ever deletes its own dated folders there; anything else you put in the folder is left alone.

state/ is deliberately $HOME-anchored rather than a sibling of config/ — it has to keep working even if config/ is relocated onto (or the whole install is left with a mid-move) an external volume that later unmounts. It’s what powers Fregata’s own answer to “why did the last run die?”, surfaced in a diagnostic bundle as a state/ folder containing whichever of the six files above exist.

state/homekit/ holds Apple Home’s pairings: each camera’s identity and private key, and the Apple devices paired with it. Treat it like a password store. A diagnostic bundle lists its file names, never their contents. Deleting it gives every camera a new identity, so each one has to be added to the Home app again.

The cache backing

FRIGATE_CACHE_DIR is RAM-backed by one of two mechanisms, picked in the welcome wizard’s “Memory for recordings” step:

Mode	Backing	Where the mount lives
Smart memory (default)	tmpfs (sparse, demand-paged)	`~/Library/Caches/com.3rdbitlabs.fregata/temp`
Basic RAM disk	HFS+ disk image (pre-allocated, wired)	`~/Fregata/temp`

The path in the tree above (~/Fregata/temp/) is therefore only literal under Basic RAM disk. Under Smart memory the same contents (nginx slice cache, go2rtc.yaml, IPC sockets, detection scratch) live under ~/Library/Caches/, deliberately hidden from Finder and Spotlight. The chosen mode is logged at startup as Cache backing: … in the Frigate log.

The tray’s Settings → Folders → Open Cache Folder menu item is disabled under Smart memory — the mount path isn’t safe to open in Finder (see the danger callout on Performance — RAM-disk cache) and there’s nothing in there worth poking at anyway. Under Basic RAM disk the same item opens ~/Fregata/temp/ normally.

Both backings unmount automatically when Fregata quits. Neither needs manual management.

See Performance — RAM-disk cache for the full trade-off (sparse vs wired, sizing, fall-back behaviour if the privileged helper isn’t approved).

Where the macOS app puts its own state

Path	What’s in it
`/Applications/Fregata.app`	The signed, notarized bundle.
`~/Library/Preferences/com.3rdbitlabs.fregata.plist`	Folder choices, env vars, “launch at login” flag, welcome-wizard state.
`~/Library/Caches/com.3rdbitlabs.fregata/temp`	Smart memory cache mount (tmpfs, ephemeral, destroyed on quit). Not Finder-safe.
macOS Service Management database	Login Item registration. No user-visible file.

Bundle internals

Most users never care about this — but if you’re poking around or debugging:

Fregata.app/Contents/
├── Info.plist
├── MacOS/Fregata           # the Swift entry point
└── Resources/
    ├── frigate-ffmpeg      # bundled ffmpeg binary
    ├── frigate-ffprobe
    ├── frigate-go2rtc
    ├── frigate-nginx
    ├── Python.framework/   # bundled Python interpreter + stdlib
    ├── lib/python3.11/site-packages/  # Frigate, Fregata, deps
    ├── models/default.onnx # the bundled YOLOv9-tiny
    ├── labelmap.txt        # fallback labels for custom models
    ├── labelmap/           # coco-80.txt: labels for the bundled model
    └── web/                # built web UI assets

Everything in Resources/ is signed at build time. Modifying the bundle in place breaks the signature and triggers Gatekeeper warnings on next launch.

Custom go2rtc binary

Fregata ships its own go2rtc build inside the bundle (Resources/frigate-go2rtc). If you need a different version — a newer release, a build with a codec Fregata’s binary doesn’t include, or a debug build for tracing — you can drop a replacement in ~/Fregata/config/:

Download the macOS arm64 go2rtc binary from the go2rtc releases page.
Copy it to ~/Fregata/config/go2rtc.
Make it executable:
Terminal window
```
chmod +x ~/Fregata/config/go2rtc
```
Restart Fregata. You can confirm it took effect by checking the version line near the top of ~/Fregata/logs/go2rtc/current.

To go back to the bundled binary, delete ~/Fregata/config/go2rtc and restart.

The bundled binary is Apple-notarized and signed. A replacement binary won’t be — macOS may quarantine it and prevent Fregata from launching it. If go2rtc fails to start after swapping the binary, run:

xattr -d com.apple.quarantine ~/Fregata/config/go2rtc

Logs

The Python core’s stdout/stderr is redirected to ~/Fregata/logs/frigate/current on the SSD (go2rtc and nginx write alongside it at ~/Fregata/logs/go2rtc/current and ~/Fregata/logs/nginx/current). Each file is kept under ~5 MiB: once it crosses that, a background thread chops the oldest ~2 MiB at a line boundary and keeps the latest ~3 MiB.

To follow the live log from a terminal:

tail -F ~/Fregata/logs/frigate/current

The tray’s Settings → Open Frigate Logs entry opens this file in Console.app, which follows it live as new lines are appended; Reveal Logs in Finder opens ~/Fregata/logs/.

To hand these logs to the support team, Settings → Troubleshooting → Create Diagnostic Bundle… packages them (with your config and system state) into a single shareable ID — see Getting help → Create a diagnostic bundle.

Changing locations

The two folders you’d realistically want to move are config and media. Both are settable via Settings → Folders → Change … Location… in the tray. The launcher writes the new path to UserDefaults and Fregata moves the existing files on next launch.

Alternatively, set FRIGATE_CONFIG_DIR or FRIGATE_MEDIA_DIR explicitly in Settings → Environment Variables and restart. The env-var path wins over the UserDefaults path; this is useful when you’ve separately copied or symlinked data first.