Skip to content

System settings

The Command Center: every setting, reviewed before you save Watch on YouTube

Every server-wide setting lives in one place, the Command Center, and you can review all your changes before you save them. Select Settings in the sidebar, then open the area you need. Only administrators see these sections; everyone else sees their own preferences.

This page walks through the server settings area by area. Each setting also has a key in the config file, shown in brackets where it helps.

Every settings page edits one shared draft. You can change things on several pages and save them together.

  • Review changes lists every change with its page, the saved value and the new value. Save changes saves them all at once.
  • Discard returns every page to the saved settings. Reset this page puts that page’s defaults into the draft; they’re applied when you save.
  • Pages with unsaved changes are marked in the settings list. Leaving with unsaved changes asks whether to keep editing or discard them.
  • Reloading the tab brings the draft back, except passwords, keys and addresses that contain credentials. Those are never stored in the browser.
  • If another administrator saves while you’re editing, your draft is kept. Changes to different settings are carried onto theirs and you save again. If you both changed the same setting, the page shows the saved value and yours side by side: keep your changes on top of the latest settings, or discard your draft and load the latest.
  • Actions that do something straight away, such as sending a test email or disconnecting everyone from a sign-in provider, run on their own. Sending a test email also saves the email settings, and nothing else.

To keep a copy of the saved settings or load them on another server, open Server & updates, then Advanced, then Copy settings. See Copy settings. If you’d rather manage settings from a file on disk, see Config file.

Change history lists every change saved from the settings pages, including credential changes, newest first. Each entry shows the administrator who saved it, the time, and each setting before and after. It’s kept on the server, so every administrator sees the same list of the latest 50 saves. Credentials only ever appear as replaced or cleared.

The OAuth client secret and the SMTP password are write-only. Their rows show Stored or Not set, never the value itself.

  • Replace credential opens a dialog with a single field. The value is sent once, checked like any other change (a new SMTP password is tested against the mail server, for example), and cleared from the dialog when it closes.
  • Clear removes the stored value after you confirm.
  • Saving any other setting, copying, exporting or importing never carries a credential.
  • A stored secret never follows a change of server. Saving a different mail server host or username clears the SMTP password, and saving a different OAuth issuer URL clears the client secret. Replace the credential for the new server afterwards.
  • Send a test email uses the stored SMTP password as long as the server, port, username and security settings on the page match the saved ones.
  • Every replacement or removal is written to the server log by credential name and administrator, never by value.

Scripts can use GET /api/admin/config/credentials to see which credentials are stored, and PUT or DELETE /api/admin/config/credentials/{name} to replace or clear one. While a config file manages the settings, credentials come from that file and can’t be changed in the Command Center.

How full the drive is, how original files are named and arranged on disk, and how long deleted photos and deleted accounts are kept.

The area opens on a status page. It says how much space your photos use and how much is free, such as “Your photos use 1.2 TB. 640 GB is free.”, and once a month of growth has been counted, roughly how long the room will last. Below it:

  • Before the disk fills up has Warn me when the disk is nearly full (storageWarning.percent, 90). Choose At 85% (recommended), At 95% or Off. You’re told under What needs your attention when the drive passes that mark. It counts everything on the drive, not only your photos. Off still warns once less than 10 GB is left.
  • Where photos are kept opens Folder layout and Move or export.
  • When things are deleted opens Deleted items and Your Trash.
  • Identical files are stored once says how much space that saves, with Open Duplicates. The server’s owner also sees Unused files with how many files are waiting. See Identical files.
  • Sort originals into folders (storageTemplate.enabled, off). Off, originals are kept under the folders Frameleaf chooses for them. On, each new original is named and filed by the layout you pick. See Folder layout.

  • The layout cards: By year, then day (recommended), By year, then month, By year, then month name, By year, and Custom… for your own pattern. Each card shows a sample path. See Layouts.

  • Under the cards, a preview sentence shows where a sample photo goes: “A photo you take on 15 June 2024 will be saved as:” and the path, starting with your own storage label, or your account ID if you have none.

  • Copies are checked before the old file is removed is a promise, not a switch: “When Frameleaf moves a photo to another drive, the old file stays until the new copy matches it exactly.” A move also never replaces another file. See How files are moved.

Advanced: custom pattern holds Custom pattern (storageTemplate.template, default {{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}). Under it, every tag is listed by kind with what it becomes for a sample photo, with Example patterns; they’re the same as the full list. File endings are always written in small letters.

storageTemplate.hashVerificationEnabled is retired. It used to be the Check files after moving them switch. Every copy is now checked, so the setting no longer does anything. It stays in the config file and the API so older files and scripts keep working, and Review changes, Change history and Copy settings name it Old copy-check switch (no longer used).

How long deleted photos and deleted accounts can be brought back. The page starts with the answer, such as Deleted photos can be brought back for 30 days, and how many photos and videos are waiting in people’s Trash.

Deleted photos and videos. Each person restores or removes their own photos in their own Trash; this sets how long everyone has.

  • Keep deleted photos for (trash.days, 30). Choose 7 days, 30 days (recommended), 60 days, 90 days, 1 year or Another length…. The line under it gives the date a photo deleted today could still be brought back.
  • The Trash itself is trash.enabled (on). While it’s off, the page says The Trash is off. Deleting a photo removes it at once., and nothing deleted can be brought back. Choose a length to turn it on again.
  • If you choose a shorter time, the page warns how many photos already in the Trash are older than that. They’re removed for good that night.

Deleted accounts. When you delete someone’s account in Users, it and its photos are kept for a while in case you change your mind.

  • Keep a deleted account for (user.deleteDelay, 7 days). Choose 1 day, 7 days (recommended), 30 days or Another length…. A shorter time also applies to accounts that are already waiting.
  • Accounts waiting to be removed are listed with Restore. See Delete an account.

Emptied by the overnight tidy-up. Photos and accounts past their time are removed when the Empty Trash and tidy up step of the overnight schedule runs, not at the minute their time runs out. While that step is switched off, nothing is removed and no space comes back; the page then says The Trash is not being emptied.

Waiting in the Trash now shows how much each person has waiting. You never see the photos themselves. See Trash.

Nothing to set here. What do you want to do? offers Move to a new Frameleaf server, Move my photos to a bigger drive and Take a copy out, and says what will happen for each. Nothing on the page moves or deletes anything.

  • A move is done in Frameleaf Manager, so it can stop and start Frameleaf safely while it works: Open Frameleaf Manager. On a server without Manager, the page offers restoring your backup on the new server or drive instead.
  • Advanced: move with the command-line tool is a step-by-step checklist for moving between two servers from another computer, one person at a time.

See Move to a new server and Move data to another drive.

Bring photos in from other places, and take a copy out. There’s nothing to set for the whole server here: the page starts with how your imports are going, such as No imports running or how far a Google Photos import has got, then lists the ways in and out.

  • Bring photos in from…: Google Photos (Import from Google Photos), iCloud Photos (iCloud Photos), A folder on this server (Folders of photos) and Your phone (Mobile apps). Each one checks what you already have, so nothing is added twice.
  • Take a copy out: Export a copy (Preservation) and Move to another server or drive (Move or export).
  • Looking for backups? opens Backup, below. Backup keeps a second copy of your library up to date by itself; an exported copy is one you make by hand.

Backup is an area of its own, under Overview and Library analytics. One screen answers “am I protected?” and has three tabs, Overview, Schedule and Restore. The Overview opens on the state of your backups (Your library is backed up, Backing up now, Your first backup hasn’t finished yet, Your photos have no backup away from home, or how many backups need attention), then Where your backups are kept: each place keeps its own copy, so losing one never costs you the others. On this server holds library data only; Buddy Backup and Cloud Backup hold photos, videos and library data, and are set up under Frameleaf Cloud. Restore is covered in Backup and restore.

When backups run is one schedule for every backup. They run one after another, never at the same time. Choosing a schedule writes backup.schedule.cronExpression, and keeps the snapshot’s own time (backup.database.cronExpression) and Cloud Backup’s in step with it. It is empty until it is first chosen; until then the snapshot’s own time, 2 am, is the schedule in force.

  • Back up: Every day, On chosen days or Every few hours.
  • On (for chosen days): pick one day or several. Choosing all seven is simply every day.
  • How often (for every few hours): Every 2 hours, 3, 4, 6, 8 or 12 hours, counted from midnight on this server’s clock.
  • Start at (for every day or chosen days): a time of day on this server’s clock. The page says what that is where you are. Night is best: backups use your disk and internet.

Backups have a start time and no stop time: each one carries on until it has finished, and the next run waits for it. What will happen says the schedule back as a sentence and lists The order backups run in: the snapshot on this server goes first, then Buddy Backup, then Cloud Backup, each starting when the one before it finishes. A place that is switched off is left out, and a backup that can’t run doesn’t hold up the next. The first backup of a large library takes longer. If it is still going when the next start time comes, the next run begins as soon as it ends.

A snapshot holds your albums, people, edits and settings. It’s kept on this server, so it protects against mistakes, not against losing the server. Use Cloud Backup or Buddy Backup for your photos and videos.

  • Take a snapshot with every backup (backup.database.enabled, on). It goes first and takes a minute or two.
  • Keep the last (backup.database.keepLastAmount, 14 snapshots). Older snapshots are removed only after a new one succeeds.
  • Take a snapshot now makes one straight away, outside the schedule.
  • Saved snapshots lists them: download one to keep elsewhere, or take the library data back to it. Restoring asks you to confirm first.

See Automatic database backups for where the files are and how to restore one by hand.

Everything Frameleaf works out about your photos on its own: finding them by describing them, recognising people, reading text, writing captions and tags, suggesting photos to lock, and building albums that fill themselves. The work runs on this server, or on another computer you choose in Where work runs.

The area opens on a status page, then has one page per feature. Each page starts with a plain choice, and keeps the numbers behind it under Advanced, so you can pick a preset without knowing the numbers, or set your own. When a choice is one of the presets, the page names it; when you have set your own numbers, it says Custom.

The status at the top says whether everything is on, off or paused, and how many photos are still waiting to be read. Open Computers takes you to the computers that do the work; See what’s waiting opens Background work.

Search and recognition (machineLearning.enabled, on) is one switch for every feature below. Turning it off keeps everything that has already been read: search, people, text and captions stay as they are, and nothing new is read. Turning it back on carries on from there.

Where this work runs shows which computer does recognition. By default it’s this server; Where work runs lets you send each kind of work to another computer. See Workers and where jobs run.

Runs in the overnight schedule tells you how the work is paced: new photos are read soon after they arrive, and reading a whole library again waits for the night. The night is set in Overnight schedule; see Jobs and queues.

Features lists the six features with their state: Ready, Off (what was read is kept), Paused (waiting for the computer), or a count of photos still being read. Each one can be turned off by itself.

Recognition runs on this server or on another computer. Frameleaf checks that it is answering and waits a short time for each reply.

  • Address (machineLearning.urls, http://frameleaf-machine-learning:3003) is where the computer answers. Add an address adds a second one, tried when the first doesn’t answer; addresses are tried in order. A new address is used once you save. To run recognition on a more powerful computer, see Remote machine learning.
  • Check that it is answering (machineLearning.availabilityChecks.enabled, on) makes Frameleaf stop sending work to an address that doesn’t answer, and try it again later.
  • Checked every (machineLearning.availabilityChecks.interval, 30 seconds) is how often each address is checked.
  • Waits for a reply (machineLearning.availabilityChecks.timeout, 2 seconds) is how long a check waits before the address counts as not answering.

Finds photos and videos by describing them, like “dog on a beach”. Smart albums, suggested tags and look-alike duplicates all use the same reading of each photo, so they need Visual search on. See Search for how to search, and Choose a smart search model for the models.

Search by describing a photo (machineLearning.clip.enabled, on). Off, you can still search by date, place, person, album and file name, but look-alike photos can’t be found and no tags are suggested.

Search quality (machineLearning.clip.modelName, ViT-B-16-SigLIP-384__webli) is a slider of the search models Frameleaf publishes, from lighter to heavier: ViT-B-32__openai, ViT-B-16-SigLIP-384__webli and ViT-SO400M-16-SigLIP2-384__webli. A heavier model understands unusual descriptions and other languages better, and is slower. The band under each stop says where it runs: Processor, Your GPU (as the last graphics card check found it) or Cloud. A Cloud stop keeps this server’s model and sends the work to Frameleaf Cloud; see Search and faces on Frameleaf Cloud.

Advanced: use your own model holds Hugging Face model. A “model” is the trained program that turns photos and words into something that can be compared. To use one that isn’t on the slider, enter its full name from Hugging Face, like organisation/model-name. Frameleaf checks its files and settings before anything is read again. While your own model is in use, the page names it; empty the box to go back to the slider.

Answer questions about your photos (localFeatures.askSearch.enabled, on) lets people ask things like “when did we last go camping?” from the Search page. Answers only ever include photos the person asking is allowed to see. Advanced: how many answers sets Most answers shown (localFeatures.askSearch.maxResults, 100), from 1 to 1,000. See Ask about your photos.

  • Use Frameleaf Assistant in search (localFeatures.assistant.enabled, on). A question typed in search gets matching photos, each with a line saying why it matched. Classic search stays one tap away.
  • Read questions with a language model (localFeatures.assistant.planner, off). When a planner model is installed on this server or a computer at home, it reads each question first. Without one, simple search rules answer.
  • Advanced: how many answers sets Most answers shown (localFeatures.assistant.maxResults, 100), from 1 to 500.

See Search.

Groups photos of the same person so you can name them. Your own corrections always win: every “same person” and “different person” choice you make is kept when faces are checked again. See People and pets for naming and fixing, and How face recognition works for what happens underneath.

Recognise people (machineLearning.facialRecognition.enabled, on). Off, the people you have named stay named, and new photos are not added to them.

How carefully to group sets the three numbers under Advanced:

Choice What it means Numbers
Fewer mistakes Someone appears after 5 clear photos. The same person may show up twice and need merging distance 0.4, clarity 0.8, 5 photos
Balanced (default) Someone appears after 3 photos. A few look-alikes may need splitting distance 0.5, clarity 0.7, 3 photos
Group more photos Someone appears after 2 photos, including blurry and side-on faces. Expect more look-alikes to split distance 0.6, clarity 0.5, 2 photos

Recognition quality is a slider of the face models Frameleaf publishes (buffalo_s, buffalo_m, buffalo_l and antelopev2), with the same Processor, Your GPU and Cloud bands as Search quality. Changing the face model reads your whole library again to find faces: until that finishes, new photos may not match the people you’ve already named. Your corrections are kept.

Use people tags saved by other apps (metadata.faces.import, off). If Lightroom, digiKam or another app saved who is in a photo, those people are shown here. It applies to photos added from now on; to include the photos you already have, read their details again from Background work after saving.

Save people’s names in XMP sidecars (metadata.faces.write, on). Saves names and face positions beside photos so other photo apps can read them. See XMP sidecars.

Advanced: face model and numbers

  • Face model (machineLearning.facialRecognition.modelName, buffalo_l) is the model the slider chose. A larger model is more accurate and slower.
  • How alike two faces must be (machineLearning.facialRecognition.maxDistance, 0.5), from 0.1 to 2. Lower is stricter and makes fewer wrong matches. Lowering it a little can help Frameleaf tell identical twins apart.
  • Face clarity needed (machineLearning.facialRecognition.minScore, 0.7), from 0.1 to 1. Higher ignores blurry or tiny faces in the background.
  • Photos needed before someone appears (machineLearning.facialRecognition.minFaces, 3), 1 or more. Fewer shows people sooner, including some you may not know.

Makes signs, receipts and documents searchable by the words in them. See Documents and text in photos for the Documents view, copying text and correcting misread lines.

Read text in photos (machineLearning.ocr.enabled, on). Off, the words already read stay searchable, and new photos are not read.

Languages to read (machineLearning.ocr.modelName) chooses one group of alphabets at a time; pick the one most of your photos use. The choices are English, French, Spanish and similar; English only; Chinese, Japanese and English (the default); Korean and English; Russian, Ukrainian and similar; Greek and English; and Thai and English. Each group has its own text-reading model.

How much to read sets the two scores under Advanced:

Choice What it means Scores
Clear text only Signs, headings and printed pages. Fewest mistakes; faded or small text is skipped noticed 0.7, kept 0.9
Balanced (default) Signs, receipts and printed pages. Very faded or tiny text is skipped noticed 0.5, kept 0.8
Faint text too Also faded receipts and handwriting. More words to search by, and more of them wrong noticed 0.3, kept 0.6

Read small print (machineLearning.ocr.maxResolution, off) reads the fine print on receipts and documents. It’s slower and needs more memory: on, text is read at 1,280 pixels of detail instead of 736.

Suggest receipt details (machineLearning.ocr.documentFields, off) suggests the shop, the date and the total from what was read. Suggestions stay editable and show where they were read from. See Suggested details.

Advanced: text model and numbers

  • Text-reading model shows the model for the language group. Only Chinese, Japanese and English has a larger model (PP-OCRv5_server), which reads more accurately and is several times slower than the usual PP-OCRv5_mobile.
  • How clear text must be to be noticed (machineLearning.ocr.minDetectionScore, 0.5), from 0.1 to 1. Higher skips faint or partial text.
  • How sure a word must be to be kept (machineLearning.ocr.minRecognitionScore, 0.8), from 0.1 to 1. Higher keeps fewer mistakes and fewer words.
  • Detail used for reading text (machineLearning.ocr.maxResolution, 736 pixels), from 1 to 4,096. Set by Read small print.

Writes a sentence or two about each photo, and suggests tags from what is in it. Search uses both, so a photo can be found by its caption as soon as it is written. See AI descriptions for what people see, and Set up AI descriptions for choosing a model and previewing before you commit.

The status at the top says how many photos have captions. Update captions now writes the rest, or rewrites them after you change the choices below. Changes apply to photos added from now on; the photos you already have keep their old captions until they are updated.

Write captions for photos (machineLearning.imageDescription.enabled, on). Off, captions already written are kept and still used by search; new photos get none.

Caption length sets the sentence count and writing style under Advanced:

Choice What it means Underneath
Short One sentence. “Two people paddle a red canoe on a lake.” 1 sentence, plain and brief
Medium (default) Two or three sentences. “Two people paddle a red canoe on a calm lake at sunset. Mountains rise behind them.” 3 sentences, balanced
Detailed Up to six sentences, with colours, weather and what people are doing. Longer captions are not always more accurate 6 sentences, rich in detail

Mention people I have named (machineLearning.imageDescription.prompt.identityInjection.enabled, on) makes captions say “Jamie at the lake”. People you haven’t named stay unnamed.

Things to look out for (machineLearning.imageDescription.prompt.lookFor) is a list of things captions mention when they can be seen in the photo. It starts with brands, signage, screens, documents, uniforms, tools, vehicles, animals, food and landmarks.

Never guess at (machineLearning.imageDescription.prompt.forbiddenInferences) is a list captions leave out. It starts with diagnoses, medication names, procedures, pregnancy and disability. Check a few captions after changing this list: it can’t be guaranteed.

Try it on a few photos writes sample captions with the choices above. Nothing in your library changes.

Describe moments in videos (machineLearning.imageDescription.videoMomentCaptions, off) adds captions to a few moments in each video. It takes longer, and speech is not written down.

Descriptions written by hand are kept follows the preference Keep what I wrote myself: while it’s on, writing captions again only replaces what Frameleaf wrote. Off, writing captions again can replace a description written by hand.

Suggest tags automatically (machineLearning.clip.zeroShotTagging.enabled, on) suggests tags from what is in each photo. Tags you added are always kept. Tags are suggested by Visual search, so it has to be on. See Tags.

How many tags sets the two numbers under Advanced:

Choice What it means Numbers
Fewer, surer Up to 3 tags on a photo, and only the obvious ones strictness 0.35, 3 tags
Balanced (default) Up to 6 tags on a photo, with an occasional wrong one strictness 0.25, 6 tags
More tags Up to 12 tags on a photo. More to search by, and more to tidy strictness 0.18, 12 tags

Where this work runs is the computer chosen for captions; Where work runs opens the page where you choose it. While captions are on, Caption model is a slider of the models Frameleaf publishes, from lighter to larger; see Choose a model. Captions follow the overnight schedule too: new photos are captioned soon after they arrive, and rewriting many captions waits for the night. Overnight schedule opens the nightly settings.

The “model” is the trained program that writes captions. A bigger one writes better captions and needs more graphics memory. The Caption model slider shows the ones Frameleaf publishes (machineLearning.imageDescription.modelName, Qwen/Qwen2.5-VL-3B-Instruct).

  • Hugging Face model is for a model that isn’t on the slider. Enter its full name, like organisation/model-name. It’s downloaded the first time captions are written.
  • Backup model (machineLearning.imageDescription.fallbackModelName, microsoft/Florence-2-base-ft) is used when the main model isn’t available. It must be installed too. Choose Another model, by its Hugging Face name… to type one in Backup model name.
  • Kind of graphics card (machineLearning.imageDescription.acceleration, Automatic). NVIDIA (CUDA) or Intel (OpenVINO); choosing one also picks the caption and private-photo models that suit it. This does not install anything.
  • Which graphics card (machineLearning.imageDescription.device, AUTO). Leave as AUTO unless the computer has more than one.

Advanced: wording lists and extra instructions

Section titled “Advanced: wording lists and extra instructions”
  • Sentences in a caption (machineLearning.imageDescription.prompt.sentenceCountTarget, 3), from 1 to 6, and Writing style (machineLearning.imageDescription.prompt.style, balanced): Plain and brief, Balanced or Rich in detail. Both are set by Caption length; change either and the length shows Custom.
  • Extra instructions (machineLearning.imageDescription.prompt.customInstructions) is anything else captions should follow, up to 2,000 characters.
  • The page also keeps the lists of words that mark a photo as private or medical (machineLearning.imageDescription.prompt.nsfwIndicators, machineLearning.imageDescription.prompt.medicalIndicators) and the vocabulary captions should prefer (machineLearning.imageDescription.prompt.customVocabulary). See Prompt & Vocabulary.

Advanced: names, and writing your own instructions

Section titled “Advanced: names, and writing your own instructions”
  • Most names in one caption (machineLearning.imageDescription.prompt.identityInjection.maxNames, 5), from 1 to 20.
  • How sure before naming someone (machineLearning.imageDescription.prompt.identityInjection.minFaceConfidence, 0.7), from 0 to 1. Higher names fewer people. Fixing a face updates its captions.
  • Write my own instructions (machineLearning.imageDescription.prompt.advanced.enabled, off) is for experts: it replaces the built-in caption instructions with Your instructions (machineLearning.imageDescription.prompt.advanced.rawPromptTemplate). {schema}, {names}, {vocabulary} and {style_hint} are filled in for each photo. Keep {schema}, or captions can’t be read back. If the schema placeholder is missing (machineLearning.imageDescription.prompt.advanced.placeholderValidation, Don’t save) chooses between Don’t save and Warn me. Start again from the built-in text puts the built-in instructions back. See Raw prompt editor.
  • Tag match strictness (machineLearning.clip.zeroShotTagging.minSimilarity, 0.25), from 0 to 1. Higher gives fewer, surer tags.
  • Most tags on one photo (machineLearning.clip.zeroShotTagging.maxTags, 6), from 1 to 20. Tags you added don’t count.

Looks for private photos, such as nudity, and suggests moving them to Locked. Only the photo’s owner sees the suggestion, and nothing is locked until they agree. Who can open Locked, and what it hides, is set by each person in Your sign-in & privacy; see Locked and private content and its Automatic detection section.

Suggest photos to lock (machineLearning.nsfwDetection.enabled, off). Off, photos already in Locked stay there, and no new suggestions are made. On, new photos are checked soon after they arrive.

How cautious to be sets the score under Advanced:

Choice What it means Score
Only the obvious Suggests only photos that are clearly private. Some will be missed 0.95
Balanced (default) Suggests most private photos, with an occasional beach or bath photo by mistake 0.85
Suggest more Misses very little. Expect more ordinary photos among the suggestions 0.7

What Locked hides opens Locked content in Your sign-in & privacy, the one place where who can open Locked, and what it hides, is set.

Tags never unlock a photo: a photo stays in Locked even if someone removes its tags. Only its owner’s PIN opens it.

Advanced: model, hardware and number

  • Hide flagged photos until unlocked (machineLearning.nsfwDetection.hideFromLibrary, off) keeps the photos this check flags out of library views until the session is unlocked with the PIN.
  • Private-photo model (machineLearning.nsfwDetection.modelName, onnx-community/nsfw_image_detection-ONNX). What it finds stays on this server. Type another only if you know it is installed.
  • Runs on (machineLearning.nsfwDetection.device, AUTO) is which processor or graphics card does the checking. AUTO lets Frameleaf choose.
  • How sure before suggesting (machineLearning.nsfwDetection.threshold, 0.85), from 0.01 to 1. Higher suggests fewer photos.

Albums such as Travel, Food and Pets that fill themselves from what is in each photo, and categories of your own. Your own albums and tags are never changed. See Built-in smart albums.

Build smart albums (smartAlbums.enabled, off). Off, no albums are made for anyone; the choices for each album are kept.

Smart albums lists each built-in album as Offered or Not offered. Open one to change it:

  • Offer this album: off takes the album out of everyone’s library. No photo is removed or changed.
  • Album name is the name everyone sees.
  • Words that add a photo: a photo joins when it shows any of these. Behind it are two lists, under Advanced: the two lists and the number: a single word is a tag that adds a photo, which has to be on the photo exactly; several words are a description that adds a photo, compared with what the photo looks like.
  • How strict sets Match strictness under Advanced, from 0.2 to 0.4: Fewer, surer (0.32), almost every photo clearly belongs but some that belong may be left out; Balanced (0.28), a few photos may not belong; More photos (0.24), more of them will only look a bit like the album.
  • Update this album sorts the photos you already have again with the saved choices. Changes otherwise apply to photos added from now on; Update albums now on the main page does the same for every album.

Suggest my own categories (smartAlbums.rules.visualCategories, on) lets people describe a category, such as “birthday parties”, and see which photos match before anything is tagged.

When a photo matches a category (smartAlbums.rules.defaultAction, Ask me first): Ask me first keeps matches in a list for you to accept, and nothing is tagged until you do; Tag it automatically gives matching photos the category’s tag straight away, and you can remove it from any photo. Nothing is ever archived unless you choose that for a category.

How photos and videos are made ready to view, and how edits are saved. Photos get a preview and videos that won’t play everywhere get a playback copy, so browsing is fast on every device. Your originals are never changed.

The area opens on a status page that says whether photos and videos are ready to view, or how many are still waiting, and names the saved preview quality and playback rule. Under Viewing are Image previews and Video playback copies; under Editing are Edited masters, AI restoration and Studio & Dolby Vision. Each page starts with a plain choice and keeps the numbers behind it under Advanced. When the numbers match a preset, the page names it; when you have set your own, it says Custom.

Smaller copies that keep browsing fast. The status at the top says whether every photo has a preview, or how many photos and videos are still waiting; browsing keeps working with the old previews until each new one is ready.

Preview quality sets the thumbnail and preview numbers under Advanced:

Choice What it means Thumbnail Preview
Space saver Takes the least space. Fine on phones, a little soft on a large screen WebP, 200 px, quality 70 WebP, 1080 px, quality 70
Balanced (default) Sharp on phones, tablets and most laptops WebP, 250 px, quality 80 JPEG, 1440 px, quality 80
Sharpest Sharp on 4K screens and when you zoom in. Takes the most space WebP, 480 px, quality 90 JPEG, 2160 px, quality 90

Make full-size viewing copies (image.fullsize.enabled, off) is for RAW and HEIC photos, which browsers can’t show at full size. It uses more space.

Rebuild every preview has the Rebuild previews button, which makes them all again straight away with the saved choices; browsing keeps working meanwhile, and Stop on the status ends it, keeping the previews already made. A photo with no preview yet shows a grey square until it is made. Runs in the overnight schedule reminds you that new photos get their previews as they arrive, and any preview still missing is made in the overnight schedule, which Overnight schedule opens. See Jobs and queues.

For videos, Frameleaf samples several frames before it picks the thumbnail. On longer videos it prefers frames at least 30 seconds in, and it skips black, blown-out or flat frames.

The small pictures in the library grid. Preview quality sets these; changing one here makes that choice Custom.

  • Size (image.thumbnail.size, 250 px) is the longer edge, in pixels: Smaller, 200 px; Small, 250 px; Medium, 480 px; Large, 720 px; or Largest, 1080 px. Larger looks sharper and uses more space. A size set in the config file outside these choices is shown as it is and kept.
  • Format (image.thumbnail.format, WebP). WebP takes less space; JPEG works everywhere.
  • Quality (image.thumbnail.quality, 80), from 1 (Smaller files) to 100 (Best looking).
  • Show a blurry version while loading (image.thumbnail.progressive, off). The picture sharpens as it arrives. JPEG only: choosing WebP turns it off.

The picture you see when you open one photo. It is also what search and recognition read.

  • Size (image.preview.size, 1440 px): Small, 720 px; Medium, 1080 px; Large, 1440 px; or Largest, 2160 px.
  • Format (image.preview.format, JPEG).
  • Quality (image.preview.quality, 80), from 1 to 100.
  • Show a blurry version while loading (image.preview.progressive, off). JPEG only.

Used when you zoom in on a photo your browser can’t open by itself. Only made when Make full-size viewing copies is on, and these rows are held until it is.

  • Format (image.fullsize.format, JPEG). JPEG works everywhere; WebP takes less space.
  • Quality (image.fullsize.quality, 80), from 1 to 100.
  • Show a blurry version while loading (image.fullsize.progressive, off). JPEG only.
  • Colour range (image.colorspace, Display P3). Display P3 keeps richer colours on modern screens; sRGB suits older ones. sRGB photos stay sRGB either way.
  • Use the camera’s own preview (image.extractEmbedded, off) gives faster previews for RAW photos, using the picture the camera already made. How good it is depends on the camera.
  • Better RAW previews (image.enhancedRaw.enabled, on) works the picture out from the RAW file itself when the camera’s preview is missing or unusable.

Copies that play smoothly on every device. A playback copy sits beside the original; downloads and backups always use the original. The status at the top says whether every video plays on every device, how many are waiting for a copy, or that playback copies are off, in which case videos play from the original, which some phones, TVs and browsers can’t show. Video transcoding goes further into every option.

Which videos get a copy (ffmpeg.transcode, Only videos that need one) is the rule in plain words. The three other rules stay under Advanced; while one of them is saved, the choice here shows that rule’s name:

Choice What it means Rule
Only videos that need one (default) Videos that already play on every device are left as they are required
All videos Every video gets a copy. Uses more space; worth it on a slow connection, where a smaller copy starts sooner all

Playback quality sets the size and the quality number under Advanced:

Choice What it means Playback size Quality number
Good (720p) Plays everywhere and takes the least space. Looks soft on a TV 720p 23
Better (1080p) (default) Plays everywhere. Sharp on phones, laptops and most TVs 1080p 23
Best (4K) Needs a fast connection and a recent device, and copies take much longer to make 4K 20

Remake every playback copy has the Remake copies button, which makes the copies again straight away with the saved choices; videos keep playing meanwhile, and Stop on the status ends it, keeping the copies already made. It is held while the rule is Never make copies.

HDR on regular screens (ffmpeg.tonemap, on) shows bright HDR videos with natural colours on screens that aren’t HDR. Your HDR originals are kept. Turning it on uses the HDR method saved under Advanced, or Hable if none was. It also decides how an edited HDR video is saved; see Edited masters.

Adjust quality to the connection (early feature) (ffmpeg.realtime.enabled, off) makes videos start faster and switch quality as the connection changes. Each step is made as the video plays, so a server that can’t keep up may stutter. See Adjust quality to the connection.

Your original videos are never changed: a playback copy sits beside the original, and downloads and backups always use the original.

Use the graphics card to convert videos faster (ffmpeg.accel, off) says which card it is set to use, or the card the server’s own check found. It can only be turned on once a card has been found or chosen; otherwise it says that no graphics card for video was found. Test it makes a short test video with the card and says whether it worked, and how many times faster than the processor it was; the row then shows when it was last tested. If the card stops answering later, the page says the day it stopped helping: playback copies are made with the processor instead, which is slower, and every video still plays. Which graphics card this server has opens Graphics card check, where the card is checked once for the whole server. See Hardware transcoding and Hardware acceleration.

A video is played as it is when its picture, its sound and its file type are all on these lists. Anything else gets a playback copy.

  • Rule (ffmpeg.transcode, Only videos that need one): Only videos that need one, All videos, Also videos larger than the playback size (optimal), Also videos above the largest file rate (bitrate) or Never make copies (disabled). With Never make copies, some videos will not play on some devices. See Which videos get a copy.
  • Video formats played as they are (ffmpeg.acceptedVideoCodecs, H.264): H.264, HEVC, VP9 and AV1. Called codecs. The format copies are made in is always on the list and can’t be cleared.
  • Sound formats played as they are (ffmpeg.acceptedAudioCodecs, AAC, MP3 and Opus), plus PCM 16-bit. Other sound is converted even if the picture plays fine. The sound format copies are made in is always on the list.
  • File types played as they are (ffmpeg.acceptedContainers, MOV, Ogg and WebM). Called containers.
  • Largest file rate (ffmpeg.maxBitrate, 0). Called the maximum bitrate: how much data one second of video may use, such as 8M. Videos above it get a smaller copy. 0 means no limit.

The video converter’s own settings. Playback quality sets the size and the quality number together; change either and it shows Custom.

  • Playback size (ffmpeg.targetResolution, 1080p): 480p, 720p, 1080p, 1440p, 4K or Same as the original. The longer side is scaled down to this; videos are never scaled up.
  • Video format (ffmpeg.targetVideoCodec, H.264): H.264, HEVC, VP9 or AV1. Called the codec. H.264 plays almost everywhere; newer ones are smaller but not every device has them. Choosing a format also makes it the only one played as it is, so older copies are not kept.
  • Quality number (ffmpeg.crf, 23), from 0 to 51. Called CRF. Lower looks better and uses more space. The right value depends on the format: typically 23 for H.264, 28 for HEVC, 31 for VP9 and 35 for AV1.
  • Conversion speed (ffmpeg.preset, ultrafast): ultrafast, superfast, veryfast, faster, fast, medium, slow, slower or veryslow. Called the preset. Slower makes smaller files and takes longer. Real-time playback uses it too.
  • Sound format (ffmpeg.targetAudioCodec, AAC): AAC, MP3 or Opus. Only for playback copies. Choosing one adds it to the sound formats played as they are.
  • Processor cores for video (ffmpeg.threads, 0), from 0 to 256. 0 lets Frameleaf decide. More convert faster and slow other things down.
  • HDR method (ffmpeg.tonemap, Hable): Hable, Mobius, Reinhard or Off. Called tone mapping: how bright HDR colours are fitted to a regular screen. Used when HDR on regular screens is on; choosing Off here turns that switch off. Hable keeps detail, Mobius colour and Reinhard brightness.
  • Convert in two passes (ffmpeg.twoPass, off). Better quality at the same size. Takes about twice as long. With H.264 and HEVC it needs a largest file rate and ignores the quality number.
  • Keyframe spacing (ffmpeg.gopSize, 0 frames), 0 or more. Called the GOP size. 0 uses the default. Shorter spacing makes skipping through a video snappier and files larger.

Set these only if Frameleaf picks the wrong graphics card or you are tuning a particular card.

  • Kind of graphics card (ffmpeg.accel, Off): NVIDIA (NVENC), Intel (Quick Sync), VAAPI, Rockchip (RKMPP) or Off. Called hardware acceleration. This is what the Use the graphics card switch above turns on and off.
  • Read videos with the graphics card too (ffmpeg.accelDecode, on). Called hardware decoding. Faster when the card supports the video’s format.
  • Which graphics card (ffmpeg.preferredHwDevice, auto) is the card’s place on the server, such as /dev/dri/renderD128. Leave as auto unless there is more than one. Applies to VAAPI and Quick Sync.
  • B-frames (ffmpeg.bframes, −1 frames), from −1 to 16. In-between frames that make files smaller. −1 uses the default.
  • Reference frames (ffmpeg.refs, 0 frames), from 0 to 6. More makes files smaller and uses more memory.
  • Constant-quality mode (ffmpeg.cqMode, Automatic): Automatic, CQP or ICQ. How the card holds quality steady. The choices depend on the card.
  • Smarter quality over time (ffmpeg.temporalAQ, off). Called temporal AQ. Spends more detail on moving scenes when the card supports it. NVIDIA cards only.

Advanced: adjusting quality to the connection

Section titled “Advanced: adjusting quality to the connection”

Used when Adjust quality to the connection is on; both rows are held until it is. Each step is made as the video plays.

  • Formats to stream (ffmpeg.realtime.videoCodecs, H.264 and HEVC), plus AV1. With a graphics card, choose only formats it can make.
  • Quality steps (ffmpeg.realtime.resolutions, 480p, 720p and 1080p), plus 1440p and 4K. Never larger than the original.

How your edited photos and videos are saved. See How edits are stored for what lives where, and What an edited video keeps for the full list of guarantees.

Original quality is what every edit keeps. Frameleaf always does this; it isn’t a choice:

  • Resolution: Original size. Edits keep the original size. Only a crop makes an edit smaller.
  • Colour handling: Standard range while HDR on regular screens is on, so edited HDR videos look right on every screen; HDR kept while it is off, so edited HDR videos keep their HDR colours. Your HDR original is always kept. The row links to the switch that sets it, on Video playback copies.
  • Audio handling: Every channel. Edits keep every audio channel as recorded, with its timing.

Video trims is where the video editor starts each new trim; you can still cut one video the other way.

  • How trims are cut (editing.trimMode, Precise). Precise cuts exactly where you choose: the video is made again from the original, which takes a little longer. Fast · keyframe aligned saves in seconds when a trim is the only change, but may start slightly earlier; with other changes the cut stays exact. It is also how the server cuts a trim that names no mode. See Video tools.

Clean up and sharpen old videos, with a short preview first. See Restore and upscale and the Studio guide to Restoration.

Restoring a video holds the one setting: each restoration starts with this style, and you can still choose the other one for a video.

  • Restoration style (editing.restoration.style, Faithful). Faithful removes noise and blockiness without inventing detail. Creative rebuilds fine detail, which suits very small or soft videos; it can invent texture that wasn’t there. See Choose a mode.

The page then lists what every restoration does:

  • A 5-second preview comes first. You compare before and after on part of the video, then decide whether to restore all of it.
  • Your original is always kept. A restored video is saved as a new version beside it.
  • Restored videos are at most 4K. You choose the size for each video. Nothing is made larger than 3840 × 2160.

Where restoration runs: AI restoration and Smooth motion run on the computer chosen in Where work runs, which the button opens. Choose Nowhere (keep this off) there to stop offering one of them. See Choose where each kind of work runs.

Whether this server can make Studio exports. Nothing here is a setting: each row is a fact this server can answer, and Graphics card check opens the page that checks the server’s own card. See the Studio overview and Exporting.

  • Studio exports: making the finished video of a project. It needs a computer with a graphics card connected to this server, so the row says Ready, Can’t run yet, Checking… or Couldn’t check, from what the connected computers can take now.
  • HDR projects: Automatic. A project becomes HDR as soon as it holds an HDR clip. Regular screens see it tone mapped. See HDR projects.
  • Dolby Vision: Not yet. Studio can’t make Dolby Vision video yet.
  • Where Studio opens: Browsers and tablets. Studio opens in any web browser and in the Frameleaf app on tablets. The phone apps don’t include it in this version.

The Libraries page, where you add and check folders of photos, sits above the settings. Keeping folders up to date holds the two server-wide settings:

  • Check every folder each night (library.scan.enabled, on). Frameleaf looks for new, changed and removed files, one folder after another, so photos added to a folder show up without anyone pressing Check now. It Runs in the overnight schedule, after backups; the time is set in Overnight schedule (see Jobs and queues).
  • Notice new files right away (library.watch.enabled, off). A photo saved into a folder shows up within a minute, instead of waiting for the next check. It works for folders on this server’s own disks, not network drives, and is still being tested. See Keeping folders up to date.

Check that your photos and videos are all there, fix what isn’t, and clear out duplicates. The area opens on Library health, the answer to “is my library all right?”, then has one page for each part: File checks, Things to fix, Tidy up, Duplicates, Album cleanup and Search and recognition progress, and ends with Identify photo locations and the Tools. An administrator sees the whole household and every setting below; a member sees their own library, their own Things to fix and their own damaged and missing files, and no settings. Checks only look. When one finds a damaged or missing file, Frameleaf tries to fix it by itself and lists what it did; nothing is deleted to fix a file, and any fix can be undone.

For the tools themselves see Library Care; for damaged and missing photos see Damaged and missing files; for what each check looks at see System integrity; for finding a file that moved see Media recovery.

The status at the top says Your library is healthy when every photo and video was on the drive and undamaged when last checked, Not checked yet before the first check (it runs tonight, and reads every file, so on a large library it is spread over a few nights), or how many files need attention. Check now starts the three file checks straight away; you can keep using Frameleaf while they run. Under it, Original files says whether they are all present and undamaged and when that was checked, and Search and recognition says how many photos are still to read for faces, captions, text and search.

Needs attention lists what was found, one row per kind: missing files (Find them), damaged files and files not in a library (Review), and files that couldn’t be processed. Nothing has been removed; each row opens the place it is fixed.

After a library is brought in from another app, Checking your imported library shows here while Frameleaf reads every imported file, with how many files are checked and how many identical photos were merged. Pause stops it without losing anything, and Resume carries on from where it stopped.

Look after your library opens the pages below, each with its state. Beside the pages described here it has Tidy up, which moves memes, receipts, screenshots and other clutter off the timeline (see Tidy up), and Album cleanup, which merges duplicate albums and nests albums by their names, with Undo last cleanup after one has run (see Tidy your albums).

Identify photo locations names the places your photos were taken, such as a park or a café, using AI credit you choose to spend on Frameleaf Cloud. See Name the businesses and venues in your photos.

Tools opens the lists you work through at your own pace: Live Photo pairing, Missing files, Damaged files and, for the server’s owner, Unused files. See Library Care for each tool.

Looks for original files that have gone missing, been damaged, or been left on the drive in nobody’s library, and shows what was found. The status says Every file is present and undamaged with when that was last checked, Not checked yet, Checking your files now, File checks are off (nothing is looking, so a problem would only show up when someone opens the photo), or how many files need attention. Check now runs every check that is on; Check again does the same once something was found.

Each kind that found something gets its own list, with its fixes in order of safety:

  • Missing files are in your library but no longer on the drive; the photos still show their previews. Find them again opens the Missing files tool; see Find a file that moved or was renamed. Clear this list forgets the findings and touches nothing; anything still wrong at the next check is listed again. Move these photos to Trash… takes them out of your library, and asks first.
  • Damaged files are on the drive but have changed since Frameleaf stored them, so they may not open. Restore from a backup opens the restore page. Look for a good copy (or Look at it, when no other copy can be searched for) opens the Damaged files tool; see Damaged files. Clear this list and Move these photos to Trash… work as above.
  • Files not in a library are in Frameleaf’s folders on the drive but in nobody’s library, usually left by an upload that was cut off. Frameleaf read each one once and sorted it. The list says how many are photos again (“Any of them can be undone”), how many are spare copies (Left alone) and how many need a decision from you, and shows a few of the photos. See the photos opens Photos found on the drive. There is no button here that deletes these files.

Each list shows three findings and says how many more are in Details for support; Remove from list takes one finding off the list without touching its file.

Three checks, one after another. Nothing is moved, renamed or deleted unless you press a button. Each has a switch, Look for …, and its own Check now. Check one…, on Missing files and Damaged files, lets you pick one photo or video and checks its file straight away, without waiting for the rest of the library or tonight’s run. A switch writes every setting that check is made of, and reads as on only when all of them are on.

  • Missing files (integrityChecks.missingFiles.enabled with libraryCare.healthScan, on) looks for files that are in your library but no longer on the drive. Off: missing files won’t be noticed.
  • Damaged files (integrityChecks.checksumFiles.enabled with libraryCare.checksumScan, on) looks for files that have changed since Frameleaf stored them. Off: damage won’t be noticed.
  • Files not in a library (integrityChecks.untrackedFiles.enabled, on) looks for files on the drive that are in nobody’s library. Photos are put back by themselves. Off: photos left off the library won’t be noticed.

Turning Missing files or Files not in a library on also keeps the audit of the database’s file references on (libraryCare.integrityAudit, on); it goes off only when both are off. A row that has never run says Not checked yet and First check tonight.

“Frameleaf tries to fix it at once and lists what it did, so you can review it.” See damaged and missing files opens Damaged and missing files, where the same switches sit.

  • Repair damaged photos by themselves (libraryCare.autoRepair, on). “A repaired copy takes the damaged one’s place, and the damaged file is kept beside it. Any repair can be undone.” Off: “Damaged photos wait for you. You see each repair before choosing it.” Either way, Frameleaf still looks for an exact copy of a photo whose file changed after it was stored.
  • Look for missing files (Always). “Compares files on this server’s drives, in the folders your old photo app used and in your backups by their contents, so a renamed or moved copy is still found.” There’s no setting behind it; it can’t be turned off.
  • Put found photos back by themselves (libraryCare.putBackFoundFiles, on). “A photo that went missing is joined to its file again, and a photo no library has is added. Either can be undone.” Off: “found photos wait in Needs you, and nothing joins the library until you choose.” See found photos opens Photos found on the drive, where the same switch sits.

Runs in the overnight schedule: the checks run at night, so they don’t slow Frameleaf down during the day. Overnight schedule opens the nightly settings in Computers & background work; see Nightly tasks.

Advanced: how much is checked each night holds the limits on the damage check. Looking for damage means reading each file from start to finish, which keeps the disk busy, and these two stop a big library from being read all night:

  • Stop after (integrityChecks.checksumFiles.timeLimit, 1 hour): 30 minutes, 1 hour, 2 hours, 4 hours or 8 hours. Each night’s damage check stops after this long, and the next night carries on where it left off.
  • Check each night (integrityChecks.checksumFiles.percentageLimit, The whole library) is how much of the library the damage check reads in one night:
Choice What it means Underneath
The whole library (default) Every file is read again on each night it fits in the time allowed 100%
Half Every file is read again every 2 nights 50%
A quarter Every file is read again every 4 nights 25%

A share set in the config file that matches none of these is shown as its percentage; choose one of the three to change it.

The checks, and the file health scan that fills the Missing files and Damaged files tools, all run in the overnight schedule’s Check files step, so they have no start times of their own. The config file still keeps integrityChecks.missingFiles.cronExpression, integrityChecks.checksumFiles.cronExpression, integrityChecks.untrackedFiles.cronExpression and libraryCare.healthScanCronExpression, but they no longer start anything.

Details for support lists every finding with the place of its file on the drive, for when you are working through a fault with someone: See every path opens one check’s full list, and Download … as a spreadsheet saves it. See Review the reports.

Recent checks lists the last runs: which check, when, how many files it read and how long it took, and whether it found nothing wrong, stopped before it finished, or carries on next night.

Everything Frameleaf has found that needs a decision from you, in one list. Every account opens it: an administrator sees the whole household, a member their own library. The status says Nothing to fix, how many suggestions are waiting for you, or how many files need attention. Nothing changes until you choose.

Waiting for you has a row per kind, each with a count and a Review button that opens its list. Turn a kind of suggestion off and Frameleaf stops looking for it; the row then says Not looking, and suggestions already made are kept.

  • Missing files and Damaged files come from File checks. Review opens the Needs you list in Damaged and missing files.
  • Fixed for you (administrators): “Damaged photos Frameleaf repaired and missing ones it found again. Any of them can be undone.” The count is for this week, the same as the Overview’s. Review opens the Fixed for you list.

When Frameleaf has fixed files this week and some are still left, the status says how many files need you: “Frameleaf fixed N files by itself this week. N missing and N damaged are left: it has tried everything it can for them.”

  • Live Photos to reconnect (libraryCare.livePhotoRepair, on): photos that lost their moving part. Unclear pairs wait for you. Review opens the Live Photo pairing tool; see Live Photos.
  • RAW files to match (libraryCare.rawRecovery, on): RAW originals that belong with a JPEG you already have. They are matched when missing files are searched for, so the row says Looking rather than a count; Review opens the Missing files tool.
  • Look-alike photos suggests which copy to keep, and is turned on and off in Duplicates. Review opens the duplicates review; see Review duplicates.
  • Couldn’t process: photos and videos Frameleaf couldn’t read or make previews of, set aside after 3 tries. The originals are untouched. See Couldn’t process.
  • Dates that look wrong: a camera clock, a time zone or a missing date put these in the wrong place. Review opens the Date & Time Doctor.

“Every file Frameleaf found a problem with, what it did about it, and anything left for you.” Every account has this page: a member sees their own files, and an administrator also sees the household’s, without their pictures. The tabs are Needs you, Fixed for you and Left as they are, and each file opens its What happened history. See Damaged and missing files for the page itself and what to do about each file.

What Frameleaf does by itself (“As soon as a problem is found, and after each night’s file checks”) is shown to administrators only:

  • Repair damaged photos by themselves (libraryCare.autoRepair, on). The same switch as in File checks. Off: “Damaged photos wait in Needs you, where you see each repair before choosing it.”
  • Look for missing files (Always). Frameleaf compares files by their contents, so a renamed or moved copy is still found.
  • Ask phones for missing photos (libraryCare.askPhones, on). “Phones with the Frameleaf app look for photos this server has lost each time the app is opened, and send back any they still have. Nothing to tap.” Off: phones aren’t asked, and a missing photo goes straight to Needs you once the server’s own search and Cloud Backup have been tried. See Phones send lost photos back.

Under them, Nothing is deleted to fix a file: “A repaired photo takes the damaged one’s place in your library, and the damaged file is kept beside it. When Frameleaf moves a file into its folder, the old one stays until the new copy has been checked to match it exactly.”

“Files that were on the drive but in nobody’s library: what each one turned out to be, and what Frameleaf did with it.” Administrators open it from File checks with See the photos; it isn’t in the list of pages. The files are shown as pictures in four lists, Needs you, Put back, Added and Spare copies, and each picture opens what happened to that file, with Undo. Another account’s picture is never shown; a lock stands in its place. See Photos found on the drive for the page itself.

Tidied without asking says how many previews for photos that are gone were cleared, and how many XMP files were joined to the photo of the same name. Neither is listed for review.

What Frameleaf does by itself (“After each night’s file checks, and as soon as a file is found”):

  • Put found photos back by themselves (libraryCare.putBackFoundFiles, on). The same switch as in File checks. Off: “found photos wait in Needs you, and nothing joins the library until you choose.”
  • Clear previews for photos that are gone (libraryCare.clearGonePreviews, on). “Only files Frameleaf made itself. An original is never cleared.” Off: those previews are left on the drive.

Under them, An original is never deleted to tidy the drive: “Each file is read once and remembered, so the drive isn’t read again for the same answer. Spare copies and files that won’t open stay where they are until you delete them yourself.”

Two kinds: exact copies of the same file, which Frameleaf handles for you, and photos that only look alike, where you choose. The status says Every file is stored once, No duplicates to deal with, how many look-alike groups are waiting (Review look-alikes), or how many files could not be checked. See Duplicates for the review itself.

When the very same file is added twice, by you or by two people, Frameleaf keeps one file on the drive. Each person still sees it in their own library, with their own albums and edits. There is no switch for this. Under Identical files are stored once the page shows:

  • how much space is saved, and when the library was last checked
  • Check again, which reads every file again. It changes nothing you can see, and every merge it makes can be undone
  • Recent merges: how many the last check made. See merges opens the duplicate review, where each one is listed under Merged for you and can be undone
  • Extra copies not stored once yet: identical files that were found but not merged yet, and the space they take. Check again stores them once
  • Extra copies: the copies that are no longer needed wait in Unused files, and the space comes back when the server’s owner empties it
  • Problems: files that were skipped, as Could not be read from the drive, Changed while it was being read or Not merged (files in folders Frameleaf reads but never changes). Nothing is merged or removed on a guess

Only files that are exactly the same are merged: Frameleaf reads each whole file from the drive, and two files are identical only when every byte matches. The oldest copy is kept.

See Identical files.

Bursts, edited versions and copies saved again by another app. Frameleaf groups them and suggests which to keep. Nothing is deleted until you choose.

Find look-alike photos (machineLearning.duplicateDetection.enabled with libraryCare.duplicateReview, on) is one switch for both settings, and is on only while both are. Off: groups already found stay in the review until you deal with them. Search and recognition has to be on for this page to work, because look-alikes are found from what Visual search has read.

How alike they must be sets the photo distance under Advanced:

Choice What it means Photo distance
Nearly identical Only photos that are almost the same picture, such as a copy saved again by another app 0.004
Balanced (default) Bursts and copies saved again, but not different photos of the same scene 0.01
Loosely alike Also photos taken a moment apart. More groups, and more of them will not really be duplicates 0.03

A number set under Advanced that matches none of these shows as Custom; choose one of the three to replace it.

Check one photo or video… looks for the look-alikes of one photo straight away; any it finds go to Things to fix.

Camera originals are suggested first (machineLearning.duplicateDetection.preferOriginalFormat, always on): RAW, then HEIC, over copies that were saved again. You still decide. See Suggested keepers.

Compare whole videos (machineLearning.duplicateDetection.enhancedVideo.enabled, on). Before calling two videos alike, Frameleaf lines up their timelines picture by picture, so a shared title screen or intro is not enough. A trimmed or re-saved copy matches when it still holds most of the video. Off: videos are matched on one picture alone.

Uses what Visual search has read: look-alikes are found from the same reading of each photo, so if Visual search is turned off, no new ones are found. Your choices here are kept, and the page says so; Visual search opens its page in Search & intelligence.

Advanced: how alike, in numbers. “Distance” is how different two pictures are: 0 means the same picture, and bigger numbers mean less alike.

  • Photo distance (machineLearning.duplicateDetection.maxDistance, 0.01), from 0.001 to 0.1. Lower finds only very close matches; higher finds more. Set by How alike they must be.
  • How much of a video must match (machineLearning.duplicateDetection.enhancedVideo.minMatchFraction, 70%), from 50 to 100%. Of the part two videos have in common, this is how much must line up picture by picture. Higher is stricter: a trimmed copy may stop matching.
  • How different the pictures may look (machineLearning.duplicateDetection.enhancedVideo.maxHashDistance, 8), from 0 to 16, in five steps: Very strict (only copies that look the same, picture for picture), Strict, Balanced, the usual choice (a copy saved at another size or quality still matches), Loose and Very loose (different videos that only look alike may be grouped together).

The video numbers can only be changed while Compare whole videos is on.

What Frameleaf has finished reading in your photos, and what is still waiting. The status says Nothing is waiting to be read, how many photos it is still reading (you can keep using Frameleaf, and results appear as they are ready), or Reading is paused. Finish now appears when work is held: it resumes paused work and queues the photo details still to read, and the server is busier until it finishes.

What is still to read has one line for each thing Frameleaf reads: Visual search, Faces & identity, Text, documents & receipts, Descriptions & tags, Photo details (dates, places and camera details from each file) and Look-alike photos. Each says Nothing waiting, how many are left to read (Reading now or Waiting its turn), Paused, how many couldn’t be read (details in the Job manager), or Off when the feature is turned off in its settings. Open goes to that feature’s page, and Redo one… reads one photo or video you pick again straight away with today’s settings. A line says Waiting for a computer when the computer chosen for that work isn’t answering.

When this work runs: Runs in the overnight schedule, because new photos are read soon after they arrive and anything still waiting is picked up overnight, so the server stays quick during the day; Overnight schedule opens the nightly settings. Where this work runs is this server, or another computer you have set up to help; Where work runs opens the routing page. See Nightly tasks and Workers and where jobs run.

A change in Search & intelligence can mean reading photos again.

Keep what I wrote myself (libraryCare.manualMetadata, on). Writing captions again only replaces what Frameleaf wrote, never a description someone typed. Off: a description written by hand can be replaced the next time captions are written again.

Redo only what changed (libraryCare.incrementalEnrichment, on). Renaming someone updates their photos without checking the rest again.

The area opens on a short status: whether the computers that do the work are answering, and whether the background work is keeping up. Its pages are Computers, Background work, Graphics card check and Overnight schedule. Computers includes Where work runs, whose photos each computer works on, and each person’s choice about Frameleaf Cloud. Computers and the graphics card check are covered in Workers and where jobs run and Hardware acceleration.

The page has two views, Everyday and Advanced; see Jobs and queues. Its settings:

  • How hard this server works (job.*.concurrency): Light, Balanced or Fast sets how many of each kind of job run at once. It’s saved through the same review draft. Higher concurrency gets more done per hour, though each single action takes as long as before.
  • When heavy work runs: Overnight or Any time. It’s the same setting as Save heavy background work for the night in Overnight schedule (nightlyTasks.quietHours, on).
  • Jobs running at once (job.capacity, Automatic): the most jobs the server works on together, across every task. Choose Automatic, which suits most servers, or a number from 1 to 32. If the server was started with FRAMELEAF_JOB_CAPACITY, that number is used and can’t be changed here.
  • Each task’s own number: in Advanced, How many run at once sets one task by hand. Finding faces, preparing photos for search, recognising people and converting videos are heavy, so raise them in small steps. If a task’s number is higher than Jobs running at once allows, the page says so and offers to raise it.
Job Default concurrency (Balanced)
Making thumbnails 3
Reading photo details 5
Converting videos 1
Finding faces 2
Preparing photos for search 2
Reading text in photos 1
Library scans, photo detail files, updating search, moving files, sending notifications, housekeeping 5 each

Recognising people always runs one at a time, because the clustering it uses isn’t parallel. See Jobs and queues for what each kind of work does.

The server’s own night work, in one place: when it runs, what it does, and whether heavy background work waits for it. The page opens on how last night went, then Tonight, in order and Recent nights. See Nightly tasks for what each step does.

  • Start time (nightlyTasks.startTime, midnight). When the night’s work starts, on this server’s clock. Night is best, because the steps read your whole disk.
  • Stop the night’s work in the morning (nightlyTasks.stopTime, 6:00 AM). No step starts after this time, and anything left carries on the next night. Turn it off (an empty value in the config file) to run every step to the end.
  • Run (nightlyTasks.days, every night). Every night, or Only some days with the days the work starts on.
  • Save heavy background work for the night (nightlyTasks.quietHours, on). Faces, pets, reading text, descriptions, Visual search, duplicates and converting videos wait for the start-to-stop window. Uploads and thumbnails never wait. See Quiet hours.
  • Finish anything that didn’t process (nightlyTasks.reprocessUnfinished, on). Each night, checks for photos and videos that still need previews, details, search, faces, text or a playback copy, and queues what’s missing.
  • Empty Trash and tidy up each night (nightlyTasks.databaseCleanup, on). The first step, and the only one that removes anything for good. Choose what this step does has:
    • Empty Trash and remove deleted accounts (nightlyTasks.emptyTrash, on). If off, the step still tidies up, but Trash isn’t emptied and keeps using space.
    • Make missing thumbnails (nightlyTasks.missingThumbnails, on).
    • Group new faces (nightlyTasks.clusterNewFaces, on). Adds new photos of people to the right person. See People recognition.
    • Prepare memories (nightlyTasks.generateMemories, on). See Memories.
    • Recount storage (nightlyTasks.syncQuotaUsage, on). See Storage quotas.
    • Count the library and check phone backups always runs. It keeps Library analytics up to date and notices a phone whose backup has stopped.
  • Different timing for one step (nightlyTasks.steps). Each step can run Every night, with the others, Once a week on the Once-a-week day (nightlyTasks.weeklyDay, Sunday), or Only when I start it. A step set to run only when you start it leaves the order and runs with Run now. If that’s the tidy-up step, Trash isn’t emptied until you run it.
  • Advanced: clock. Every time here, in Backup and in Library care uses this server’s clock, set by Time zone in Server name & welcome.

Run now starts every step that’s on, one after another, whatever its own timing. Stop ends tonight’s run; the steps it didn’t reach run at the usual time.

Backups keep a schedule of their own, set in Backup and shown here so the whole night is in one place. If the two overlap, only the steps that use the disk or the internet (checking folders, iCloud Photos, checking files) wait for the backups to finish. Emptying Trash never waits. If the start time is close to the backups, the page suggests starting one an hour or more after the other.

Frameleaf Cloud is optional. It adds remote access, cloud processing and cloud backup to your server, and the server works fully without it: local photos, albums, accounts and sign-in never depend on the link. The area has six pages, in this order: Account & link, Plan, Licence, Remote access, Cloud processing and Cloud backup. See Frameleaf Cloud for what a plan includes, and Your Frameleaf account for the account itself.

Every control on these pages is written to the frameleafCloud group of the configuration. Most of them save as soon as you change them, with a notice such as “Remote access is on.”; the ones that save with the rest of your settings say so below. On a server run from a configuration file the pages are read-only, like the rest of Settings.

The page opens on the link’s state: This server isn’t linked to a Frameleaf account, Linked to your account, or Frameleaf Cloud ended this link. Linking is free and optional. It is the first step for remote access, backups away from home and cloud processing, and nothing from your library is uploaded by linking. If whoever runs the server has turned Frameleaf Cloud off in its configuration, the page says Frameleaf Cloud is turned off for this server: nothing is sent to Frameleaf, and everything else works as usual.

Link this server starts the link. The page shows Your code, a QR code and the address to approve it on. Open that address on your phone or computer, sign in, and check that the code matches; only approve it if the key fingerprint matches too. Linking finishes by itself once the code is approved. Get a new code replaces a code that expired, Cancel stops the attempt, and Clear this link abandons one that did not finish. If your Frameleaf account keeps its data in another region than the one this server asked for, the page says so and offers Link in the account’s region.

What linking leads to lists each extra with what else it needs: Free with an account, Needs a licence, Needs a plan or Pay as you use it. Linking a server without a browser explains the one-time link token; see Link a server with no browser.

Once linked, the page shows the account, the date it was linked, when Frameleaf last heard from this server and the region your data is kept in. Manage on frameleaf.cloud opens your account.

A notice says whether the Frameleaf apps find this server Available anywhere or At home only. Sign in to the Frameleaf app on iPhone, iPad or Android with your Frameleaf account and this server appears by itself; away from home the app connects directly when it can and through the Frameleaf relay otherwise. Set up remote access takes you to the Remote access page.

What you can do from your Frameleaf account when you’re away has two switches. Your account can only ask: this server decides, and keeps a record of each request. They are kept with the link, not in the configuration:

  • Turn remote access on or off lets you enable remote access from your Frameleaf account when you are away.
  • Start a cloud backup lets the account site start a backup run. It can never read, change or delete backups.

What this server sends says what a check-in holds. Sent: how it is doing (its Frameleaf version, how long it has been running and whether it is healthy). Also sent: where to reach it (its addresses, and whether remote access is connected). Never sent: anything of yours, meaning photos, videos, thumbnails, metadata, names, accounts or usage. Check-ins happen every few minutes.

Advanced, under it, holds the rest:

  • Instance ID is this server’s ID, the same one used on Licence and Sign in with Frameleaf.
  • Key fingerprint is what the approval page shows when you link.
  • Contact Frameleaf now, with Check in now, contacts Frameleaf Cloud straight away. It happens by itself; use it after fixing a connection problem.
  • Refresh your plan automatically picks up renewals and plan changes without a manual refresh.
  • Take the tour opens the short tour of what a linked server can do.
  • The exact list of what each check-in sends.

Unlink this server, with Unlink…, stops every cloud feature on this server; you can link again at any time. Before you confirm, the dialog lists what stops: remote access, cloud processing (queued jobs are cancelled and held AI credit is released), scheduled cloud backups (backups already made are kept, and this server can still open them), everyone’s linked Frameleaf accounts and the plan. Licences stay, and local photos, albums, accounts and sign-in keep working exactly as before. Tick the box to confirm, then choose Unlink server. See Unlink a server.

Your library needs no plan. A Frameleaf Cloud plan adds remote access for everyone on this server and the storage for Cloud Backup, and it needs a Server licence on this server first. Local photos are never locked: if a plan ends, only remote access and cloud backup pause.

The status at the top says No plan on this server, Frameleaf Cloud plan is active with the account and the renewal date, Your plan needs renewing or Your plan has ended. With a plan, Manage subscription opens your Frameleaf account (Update payment when a payment didn’t go through).

What this plan gives spells it out. With this plan: remote access for everyone on this server at a name of your own on frameleaf.net, and 1 TB of Cloud Backup storage. Not part of a plan: cloud processing, which is paid for as you use it from AI credit, and the licence, which is a one-time purchase. What it costs shows the monthly and yearly price for this server. Under them:

  • Your name on frameleaf.net shows the address everyone reaches this server at, with Choose a name… or Change name…. See Remote access.
  • Cloud Backup: the storage comes with the plan, and your licence decides who can use it. Open Backup goes to the Backup area.
  • Buddy Backup needs a Server licence on both servers and a free Frameleaf account. The plan’s only part is letting the two servers connect through Frameleaf when they can’t reach each other directly.
  • More storage: every plan includes 1 TB. If your backups grow past it, another 1 TB is added automatically, billed monthly even on a yearly plan.
  • Cloud processing shows the AI credit left, with Add AI credit. It is paid for as you use it, with or without a plan.
  • Licence says which licence this server has. Keys and licence files are added on the Licence page.
  • Stop using this plan on this server, with Stop using it here…, takes the plan off this server only. Remote access turns off and cloud backups pause here. It does not cancel your subscription, which is managed in your Frameleaf account; use it when moving the plan to another server.
  • Last checked with Frameleaf and Came from (Frameleaf account, or Licence file (offline)) say where the plan was read from. Check for changes now, with Refresh, asks again. Renewals and plan changes arrive by themselves; use it if you have just paid and nothing has shown up.

Without a plan, the page lists what a plan adds and the Monthly and Yearly choices, then Continue to the Frameleaf store. You pay in the Frameleaf store, never on this server, and this server picks up the plan by itself. A server that already has its licence pays less for the yearly plan. What a plan doesn’t include lists cloud processing, the licence and storage past the included 1 TB. For the plans, their prices and what each includes, see Plans and supporter licences.

Frameleaf is free to self-host. Without a licence, your library and everything on this server keep working; only Frameleaf Cloud and backups away from home need one. A licence is one purchase: it never expires, has nothing to renew, and never locks your photos.

What a licence gives lists the same things on every page that mentions them:

  • Lets this server use Frameleaf Cloud. You need a licence, Server or Individual, before you buy a Frameleaf Cloud plan or AI credit. The plan is what adds remote access and the storage for Cloud Backup.
  • A lower price for Frameleaf Cloud plans, with one rate for a Server licence and a smaller one for an Individual licence, for as long as the licence stays on this server. The two are never added together. The rates are shown on the page.
  • Backups away from home. A Server licence adds Cloud Backup and Buddy Backup for everyone on this server. An Individual licence adds Cloud Backup for one account.
  • A Supporter badge beside the name of everyone the licence covers.
  • Yours for life.

See Licences, plans and credit.

Enter a licence key. A licence bought from this server is added by itself. A key from an email or a gift is entered here, and only here. It looks like FL-XXXX-XXXX-XXXX, and Frameleaf tells you which kind it is before anything changes: This is a Server licence, which covers everyone on this server, or This is an Individual licence, which covers your own account only. Then choose Activate. A server with no Frameleaf Cloud address can’t check a key, and installs a licence file instead.

A server with no internet connection installs a Licence file, a file ending in .lic made for this server only. On another device, download the file for this server from your Frameleaf account, using This server’s ID (Copy copies it), then Choose licence file… here. The file can carry a licence and a Frameleaf Cloud plan, and cloud features follow its dates.

Once licensed, Your licence shows the Licence key (the full key is in the email it came in), its Kind, when it was Added, who it covers (Everyone, or one person only), what’s Included, and when it was Last checked with Frameleaf. Frameleaf checks once a day on its own; Check now checks again. If a plan’s renewal didn’t go through, the page says how long remote access and Cloud Backup keep working.

Remove from this server… stops Cloud Backup and Buddy Backup for everyone the licence covered, the supporter badge and the plan discount. Backups already made are kept, the licence stays yours to add again here or on another server, a Frameleaf Cloud plan is not cancelled, and your photos are not affected. Remove your Individual licence… does the same for an Individual licence on your own account. Enter another licence key adds a second one; a Server licence key covers everyone.

Reach this server from anywhere, with nothing to set up on your router. Nobody but you and the people you invited can see inside the connection. Remote access needs a linked server and is part of Frameleaf Cloud. See Remote access for the whole picture, and Remote access without Frameleaf Cloud for a VPN or your own reverse proxy instead.

The status at the top says Remote access is off, Remote access is starting (the server is getting its address and certificate, which takes a minute or two), Remote access is on and working, Remote access is working, but slower once the month’s allowance is used up, or This server can’t be reached from outside your home.

Let people reach this server away from home (frameleafCloud.remoteAccess.enabled, off). People away from home sign in with their Frameleaf account. Turning this off disconnects anyone away from home straight away.

How devices connect (frameleafCloud.remoteAccess.mode) chooses the route:

Choice What it means Value
Always through Frameleaf Works everywhere, at up to 8 Mbit/s: enough to browse and watch. Counts toward your monthly allowance relay
Straight to your home when possible Faster, and doesn’t use your monthly allowance. Frameleaf sets up your router for you. When that isn’t possible, the connection goes through Frameleaf instead relay-and-direct

Under the choice, Right now: says which route is in use, for example that devices connect straight to your home, or that your internet provider doesn’t allow direct connections, so everything goes through Frameleaf. Without a Frameleaf Cloud plan, this server is reached only straight to your home, and the Frameleaf apps don’t work away from home.

This month through Frameleaf is a meter of what you have used of the month’s allowance. If it runs out, remote access slows down until the 1st. It never stops, and connections straight to your home aren’t slowed. See Limits.

Door on your router appears when devices may connect straight to your home. A port is a numbered door on your router; devices away from home come in through it.

  • I set up my router myself (frameleafCloud.remoteAccess.portMapping, off). Turn this on if you forward the port by hand. Frameleaf then stops asking your router to do it.
  • Port you forwarded (frameleafCloud.remoteAccess.directPort, 2443), a number between 1024 and 65535.
  • If your internet provider shares one public address, or the router can’t be reached from the server’s container, the page says so. Remote access keeps working through Frameleaf.

Your public address is the address to share or scan on a phone. It appears once remote access is on and this server has its certificate. Show QR code and Download QR code give it as a code to scan. With a plan, Your name on frameleaf.net lets you choose the name in that address; the technical address still reaches this server and never changes. See Your server’s addresses.

The address in links you share (frameleafCloud.remoteAccess.publicUrl, frameleaf) is used in shared links, emails and when people sign in: Your Frameleaf address or Your own domain. The page shows what links you share will start with.

Use your own domain reaches this server at an address on a domain you own, such as photos.example.com. Frameleaf still carries the traffic and this server still holds the certificate; it comes with a Frameleaf Cloud plan.

  • Custom hostname (frameleafCloud.remoteAccess.customHostname.host, empty) is a subdomain you control. The page lists the two DNS records to add at your domain provider, with their Type, Name and what each Points to: one sends visitors to your server through Frameleaf, the other lets this server renew its own certificate for your domain.
  • Check my domain looks for the two records. Nothing changes until they are found, and DNS changes can take up to an hour. Once verified, the hostname points to this server and its certificate is issued and renewed here. Remove domain goes back to the Frameleaf address.
  • Another address (server.externalDomain) is only for when you run your own gateway in front of this server. Type the full address people should use. It’s saved with your other settings changes, and it’s the same setting as Public server URL in Server name & welcome.

See Use your own domain.

Signing in away from home applies to every connection from outside your home, whichever way it arrives (frameleafCloud.remoteAccess.allowPasswordOverRelay, off):

  • Frameleaf account only (recommended): everyone away from home signs in with their Frameleaf account.
  • Frameleaf account or password: also lets people type this server’s password away from home. Passwords are easier to guess, or to be tricked out of. Keep this only for someone who can’t use a Frameleaf account.

Links you shared publicly still open without signing in. At home, people keep signing in however they do now.

Let people download full-size originals through Frameleaf (frameleafCloud.remoteAccess.allowOriginalsOverRelay, off). Originals are large and use the allowance quickly. Photos and videos always open and play either way.

Connection details has the technical side: the Frameleaf region, the response time, since when the server has been connected, how much was sent through Frameleaf this month, the router mapping in use (UPnP, NAT-PMP or Forwarded manually), and the Certificate, which Renews automatically and is issued to this server only; the private key never leaves it. Run a connection test (or Check it now) checks five things and says which passed: Security certificate, This server is listening, A test request got through, Through Frameleaf and Straight to your home.

Your own computers stay the default, and nothing goes to the cloud without asking. Cloud processing is pay as you go: it needs a linked server and AI credit, but no plan. Each job still shows its model and cost before it starts. See Cloud GPU.

The status at the top says Cloud processing needs a linked server, Cloud processing is off, Cloud processing is on with how much AI credit there is to spend and what was spent today, or AI credit is almost gone. When the processing terms have changed, nothing goes to Frameleaf’s computers until you Review terms.

Use Frameleaf Cloud for chosen jobs (frameleafCloud.cloudMl.enabled, off). Turning this off cancels waiting cloud jobs and returns their held credit. The first time you turn it on, the processing terms open; once accepted, you save to turn cloud processing on.

What leaves this server says it in one line: smaller copies of the photos and videos you choose, with location and camera details removed. Never your originals, faces, or the names you gave people. What is sent, in detail lists what you accepted: Terms (the version accepted, or Not accepted), Names in descriptions (Only names written in a photo, or Left out), Medical signals (Allowed in descriptions, or Never described), Smart search and Faces (whether previews can be sent, or the work is Prepared on this server and Found and recognised on this server). Faces on Frameleaf Cloud are turned on with their own consent in the processing terms, not with a setting (frameleafCloud.cloudMl.faces.enabled is always off). Review terms and features opens them again. See Choose what leaves your server.

What may use the cloud shows which kinds of work may use Frameleaf’s computers and which stay on your own. It’s chosen on one page, together with which of your own computers does what: Change where work runs opens Where work runs on Computers (frameleafCloud.cloudMl.routing). Text, documents & receipts always stays at home. Visual search and Faces & identity can use Frameleaf Cloud only with the same model as this server; see Search and faces on Frameleaf Cloud. Each person can also keep their own photos at home; see Each person’s photos.

Kind of work What it does Key
Descriptions & tags Captions, tags and moments for Library care routing.descriptions
Enhance & upscale Sharper, larger photos from the editor routing.upscale
AI restoration Cleans up and sharpens old videos, in the editor and Studio routing.restoration
Transcripts & captions Turns speech in a video into text and captions routing.studio
Smooth motion Higher frame rates and smooth slow motion for videos routing.interpolation

For a row set to Ask me each time, the place suggested first is frameleafCloud.cloudMl.startWith (This server), set on Computers under Finer choices.

Models. Each kind of work chooses its model on its own settings page, with a slider from lighter to heavier models. A blue model runs on Frameleaf Cloud, and the price shows before anything is sent. Models and prices lists them, and Estimate a cost shows, for a Model and a Quantity, the likely cost, the most it is likely to cost, and what is held until the job settles. You pay for the GPU time a job uses, per second, plus a start fee for each computer that loads the model.

Waiting for Frameleaf Cloud lists work that hasn’t started yet, and why: new photos waiting to join the next batch (waiting for a batch keeps the start fee down), photos waiting because describing new photos automatically is off, because Frameleaf Cloud is turned off, or because it doesn’t offer the model this server uses.

Spending. AI credit is paid for in advance, and you see the price of cloud work before it starts. Nothing is ever charged automatically unless you turn on automatic top-up.

  • AI credit shows what there is to spend and what is set aside for work that is running; whatever isn’t used comes back. Add credit opens a top-up on frameleaf.cloud in a new tab, with card fees included so the full amount becomes AI credit.
  • Daily limit is the most Frameleaf spends in one day, on everything. Work that would pass it waits until tomorrow. Raising it happens in your Frameleaf account; this server can only lower it.
  • Top up automatically adds credit with the payment method saved on frameleaf.cloud when available credit runs low. It’s turned on in your Frameleaf account; this server can only turn it off.
  • Describe new photos automatically (frameleafCloud.cloudMl.autoDescribe.enabled, off). New photos get a description as they arrive, without asking each time. It needs cloud processing on and the current terms accepted.
  • Limit for new photos (frameleafCloud.cloudMl.autoDescribe.dailyBudgetUsd, $2.00 a day) is part of the daily limit, not on top of it. When it’s reached, the rest wait until tomorrow.
  • Allow someone else (frameleafCloud.cloudMl.spenders, nobody). Only administrators can confirm Frameleaf Cloud jobs until you allow other people here, each with an optional monthly limit for the cloud work they start themselves. A monthly limit counts what was settled this month plus the AI credit set aside for their running jobs, and is checked when a job is confirmed.
  • What these add up to says the limits back in plain sentences.

See How you pay and Automatic descriptions.

Describe your library… describes the photos that have no description yet, in batches on Frameleaf Cloud. It shows how many photos, with which model, what it is likely to cost and what is held, before anything is sent.

Recent cloud work lists each job with its estimate next to what it actually cost. Open job manager goes to Background work.

Back up originals and the database to an encrypted bucket that only this server uses. Cloud backup needs a linked server and a Frameleaf Cloud plan; your photos and every local feature keep working without one. Only new or changed files upload, so a photo you have twice is stored once; every file is encrypted on this server before it is uploaded, and you choose at setup who keeps the key; backups from different servers never mix. The status at the top is Off until it is set up. See Cloud backup, and Buddy Backup for backing up to another home server instead.

Set up cloud backup (frameleafCloud.cloudBackup.enabled, off) walks through four steps. The destination and key choice can’t be changed later without starting a new backup.

  1. Destination (frameleafCloud.cloudBackup.target, off): Frameleaf-managed storage (managed), included with your plan, where Frameleaf creates a bucket just for this server; or Your own S3-compatible bucket (byo-s3), an empty bucket with versioning turned on, on a provider that supports customer-provided encryption keys (SSE-C). Backups are encrypted on your server either way; SSE-C only protects the bucket’s claim file. For your own bucket, enter the Storage address (frameleafCloud.cloudBackup.s3.endpoint, HTTPS), Region (frameleafCloud.cloudBackup.s3.region, empty reads it from the storage address or uses us-east-1), Bucket (frameleafCloud.cloudBackup.s3.bucket), Access key ID (frameleafCloud.cloudBackup.s3.accessKeyId) and Secret access key (frameleafCloud.cloudBackup.s3.secretAccessKey, stored on this server and never shown again), then Check bucket.

  2. Encryption key (frameleafCloud.cloudBackup.keyMode, server). New backups are encrypted on this server before upload, with keys the storage provider never receives:

    Choice What it means Value
    Generate a key for me (default) This server creates the key and keeps it next to its identity. You save a recovery kit in the next step. If you lose this server and the recovery kit, the backup cannot be read server
    I’ll maintain my own key, with Keep a copy on this server on A key is created in this browser and you download it. Scheduled backups run unattended; the copy stays on this server and is never sent to Frameleaf Cloud own-stored
    I’ll maintain my own key, with Keep a copy on this server off The key is never saved. After every restart backups pause until someone enters it, and restores always need the key file own-memory

    With your own key you must Download key file and confirm I saved the key file somewhere other than this server before you can continue, and type “I understand” to confirm that a lost key means every backup in this bucket is permanently unreadable. With a generated key, Also keep an encrypted copy with Frameleaf (frameleafCloud.cloudBackup.escrow, off) stores a copy protected by a passphrase of 12 characters or more that only you know; Frameleaf cannot read it, and it helps if you lose this server but still remember the passphrase.

  3. Recovery kit (generated key only) is shown once: the server instance, bucket, key fingerprint and recovery code. Download or Print it and keep it somewhere safe and offline, then confirm I saved or printed the recovery kit.

  4. Turn on backup, or Claim bucket and then Finish setup for your own bucket. Each server uses its own bucket, and a bucket belongs to exactly one server: Frameleaf writes a marker with this server’s instance ID so no other server can use it.

See Choose how the key is kept.

Once set up, At a glance shows the Last backup (how many new or changed files, and their size), when it was Last checked and whether everything could be read back, and where it is Stored in: Frameleaf-managed storage, included with your plan, where Frameleaf can see file names and sizes but never contents; or Your own bucket, whose credentials and key Frameleaf never holds. Storage used is a meter against your plan, with any extra 1 TB blocks added to it, or the size and number of unique files billed by your provider. Back up now starts a run; progress and a Cancel follow here and in Activity. A run that stops shows why, and a key that is not loaded after a restart shows Unlock, which loads the key file for this session only.

Also backed up applies to everyone on this server. Library data (albums, people, edits, tags and settings) is Always backed up, and always the whole library.

  • Thumbnails and previews (frameleafCloud.cloudBackup.include.thumbs, off). Restores show pictures sooner, at the cost of more storage.
  • Transcoded videos (frameleafCloud.cloudBackup.include.encodedVideo, off). Restored videos play straight away, at the cost of more storage.

Older versions let you go back if you deleted or changed something by mistake. Nothing still needed by a kept version is ever removed.

  • Keep daily runs (frameleafCloud.cloudBackup.retention.keepDaily, 7 days), from 1 to 90.
  • Keep weekly runs (frameleafCloud.cloudBackup.retention.keepWeekly, 4 weeks), from 0 to 52.
  • Keep monthly runs (frameleafCloud.cloudBackup.retention.keepMonthly, 12 months), from 0 to 120.

Safety:

  • Check the backups (frameleafCloud.cloudBackup.verifyWeekly, on). Every week a sample of the backed-up files is fetched and checked, and every month each file is confirmed to be there. Anything missing or damaged is uploaded again.
  • Check the backup now, with Verify, reads back a sample of the backed-up files to make sure they can be restored.
  • Recovery file, with Update recovery file: choose your saved recovery file to download it again with your latest backups added. A new server needs this to open your newest backup, so do it after backing up and keep the file somewhere safe.
  • Recovery copy is out of date appears when your backup key changed after the copy with Frameleaf was stored. Update recovery copy stores it again with your passphrase.
  • Get something back, with Restore…, opens the Backup area’s restore page, where you restore photos, albums or the whole library from this backup. See Restore.

When scheduled runs start (frameleafCloud.cloudBackup.schedule.cronExpression, 3:00 every night) is set once for every backup on Backup, then When backups run, together with the database backup; backups run one after another, never at the same time.

The included files, the older versions and the safety check save with your other settings changes. Technical details shows the Encryption (on this server before upload, with keys only you hold), the Bucket, its Region (your own bucket only), which Key choice is in use, the Key fingerprint, and whether a Recovery copy is kept with Frameleaf, protected by a passphrase only you know.

Turn off cloud backup, with Turn off backup…, stops scheduled runs. The bucket and its backups are kept, and you still need this key to read them, so keep your recovery kit or key file. Delete the bucket in your Frameleaf account, or at your storage provider, when you no longer need it.

How people sign in to this server, at home and away. The area has two pages, Sign-in methods and Sign in with Frameleaf. Each person’s own settings are in Your sign-in & privacy under Personal: their password, passkeys, Locked PIN, linked sign-in provider, Always Locked rules, signed-in devices and API keys. What Locked hides, and who can open it, is explained in Locked and private content; an administrator can reset someone’s password or PIN under Users.

The page starts with the answer, such as People can sign in two ways, with which ones, or Nobody can sign in if every way is off. Changes on this page wait in your draft until you select Save changes. When the server’s settings come from a configuration file, every control here is read-only. The full walkthrough, with provider examples, is Sign-in and OAuth.

  • Password (passwordLogin.enabled, on). Each person’s own password. Don’t turn this off until an administrator has signed in another way. While it’s off, the page warns Password sign-in is off: if Frameleaf Cloud or your provider is unreachable, nobody can sign in at home until it’s back.
  • Frameleaf account shows On once this server is linked to Frameleaf, and Off until then. It’s what people use away from home. Open goes to Sign in with Frameleaf.
  • Another sign-in provider (oauth.enabled, off). For a household or organisation that already runs its own sign-in, such as Google Workspace. Most homes leave this off. Turning it on shows the two groups below.

A passkey by itself, or any two of password, emailed code and authenticator code.

Who must (signInPolicy.require, Administrators away from home) also offers Everyone away from home and Everyone, everywhere. Everyone else can still sign in with one step. Choosing Everyone, everywhere needs password sign-in on and a passkey, or a password with two-step sign-in, on your own account first; otherwise saving is refused. reset-sign-in-policy on the command line puts it back to the default.

Apply to older apps too (signInPolicy.applyToOlderApps, off). Older apps and sessions that were signed in before this setting keep working as they did until you turn this on.

What each choice means is in Require a passkey or two-step.

Three things your sign-in provider gives you when you add Frameleaf to it:

  • Provider address (Issuer URL) (oauth.issuerUrl, empty, required). The address your provider gives for sign-in, such as https://accounts.google.com. /.well-known/openid-configuration is added for you if you leave it off.
  • Client ID (oauth.clientId, empty, required). The name your provider knows Frameleaf by.
  • OAuth client secret (oauth.clientSecret) is a credential row: it shows Stored or Not set, never the value. Replace credential saves a new secret on its own, straight away, outside the settings draft; Clear removes it.
  • Check the connection: Check asks the provider to introduce itself, and says Found your provider with its name, or what went wrong. Nothing is saved until it answers.
  • Addresses to allow at your provider lists the three addresses your provider asks for, ready to copy: Signing in on the web, Connecting an account you already have and Signing in on the Frameleaf app.
  • Create accounts automatically (oauth.autoRegister, on). The first time someone signs in through your provider, they get an account here. Off: only people you’ve added can sign in. Creating an account also needs the provider to say the email address is verified; see Verified email addresses.
  • Space for new people (user.newUserStorageQuota, no limit) is set once, under Users, for every way an account is made: Open Users. In the config file, oauth.defaultStorageQuota (empty) can still set a limit in GB for accounts the provider creates when it sends none.
  • Words on the sign-in button (oauth.buttonText, Sign in with your provider). What everyone sees on the sign-in page.

The Advanced group holds the rest. This kind of sign-in is called OpenID Connect, and every setting here already has a value that works with most providers:

  • How Frameleaf proves itself (oauth.tokenEndpointAuthMethod, client_secret_post) appears once a secret is stored: Client secret in the request or Client secret in the request header. Use the method your provider asks for.
  • Information requested (oauth.scope, openid email profile). What Frameleaf asks the provider for, such as name and email.
  • Signature on the sign-in token (oauth.signingAlgorithm, RS256) and Signature on profile details (oauth.profileSigningAlgorithm, none). Use the type your provider asks for; the second is only needed if your provider signs profile details.
  • What the provider asks each time (oauth.prompt, empty). The prompt parameter, for example select_account, login or consent.
  • Sign-out address (oauth.endSessionEndpoint, empty). People are sent to this address when they sign out.
  • Wait for the provider (oauth.timeout, 30 seconds). How long Frameleaf waits for your provider before giving up.
  • Allow a provider without a valid security certificate (oauth.allowInsecureRequests, off). Only for a provider on your own home network. Anyone on the way could read the sign-in, so never use it across the internet.
  • Go straight to the provider (oauth.autoLaunch, off). Skips Frameleaf’s sign-in page and opens your provider’s. To reach the normal sign-in page anyway, see Auto launch.
  • Folder name from provider (oauth.storageLabelClaim, preferred_username) sets the person’s folder name on disk from this claim. See Storage labels.
  • Administrator from provider (oauth.roleClaim, frameleaf_role) makes someone an administrator when this claim says admin. The claim may be user or admin.
  • Space limit from provider (oauth.storageQuotaClaim, frameleaf_quota) sets the person’s space from this claim, a number of GB. See Storage quotas.
  • Account Management URL (oauth.accountManagementUrl, empty). Where in your provider a person can manage their own profile.
  • Sign-in address for an older app (oauth.mobileOverrideEnabled, off). Turn it on when your provider doesn’t allow an app address like frameleaf-auth:///oauth-callback. Mobile redirect URI (oauth.mobileRedirectUri) must then be this server’s /api/oauth/frameleaf-mobile-redirect address, which forwards the sign-in to the app. See Mobile redirect override.
  • Changing to a different provider? Disconnect everyone… disconnects every account from this provider first. Their accounts and photos stay. The page asks you to confirm, because it can’t be undone.

The folder name, administrator and space claims are read when an account is created. Changing them at the provider later doesn’t change the account; edit it under Users instead.

Apps that can ask people on this server for access. Each person chooses what they allow. See Connected apps.

  • Let new apps register themselves (connectedApps.allowRegistration, on). AI assistants such as Claude and ChatGPT add themselves when someone connects them. Each person still has to choose Allow before an app can see anything. Turn this off to allow only apps that are already registered.
  • AI agents (MCP) (connectedApps.allowMcp, on). Lets people connect AI agents to their library through MCP. Turning this off also stops existing agents from using the library.

Whoever can reach the computer Frameleaf runs on can always get back in, and nothing in your library is touched. The page lists the three steps, and Show the commands gives the two commands: frameleaf-admin enable-password-login turns password sign-in back on for everyone, and frameleaf-admin reset-admin-password sets a new password for the first administrator. Then sign in and check which ways to sign in are on. If only one person is locked out, reset their password from Users instead. See Server commands.

Let people sign in with their Frameleaf account, which is what they use away from home. It works alongside passwords and your own provider. This page saves each change by itself, not through the settings draft.

The page starts with who can use it: Everyone can sign in with Frameleaf, how many of the people here can, or Sign in with Frameleaf isn’t available yet until the server is linked (Link this server; see Link a server).

  • Who has linked lists each person as Linked or Not yet. Someone who hasn’t linked Can only sign in at home. Each person links their own Frameleaf account, from their own sign-in settings; Remind emails them a link to those settings (it needs email and a public address for this server), and Link yours opens your own.
  • Where it is used: away from home, people sign in with their Frameleaf account; Change in Remote access opens Remote access. Offer it at home too (frameleafCloud.signIn.showOnLocalLogin, off) adds a “Sign in with Frameleaf” button to the sign-in page at home. Passwords stay available. It reads Link this server first. until the server is linked.
  • Words on the button (frameleafCloud.signIn.buttonText) is what the button on the sign-in page says. Edit it and select Save.
  • Space for people you invite is set once, under Users, for every way an account is made. See Space for new people.
  • Your own OpenID provider opens Sign-in methods above.
  • Signs in through names the Frameleaf service that checks who people are, and Server ID is the same ID shown on Account & link and Licence. There is no client secret to manage: the server proves itself with its own key.

The area lists Emails you receive, every account’s own choice of which emails to get (see Email notifications), What needs your attention, an administrator’s view of a full drive, a missed backup, stopped work or a new version, and Email delivery, the server’s settings below. For setting up each provider step by step see Email.

The page opens on Email status: Email is not set up or Email is turned off (nothing is sent; invitations and album updates appear in the app only), Email stopped working (Google or Microsoft is asking you to sign in again), or Email is set up, with the address this server sends from.

Pick your email provider and Frameleaf fills in the rest. The tiles are Gmail (Gmail and Google Workspace), iCloud Mail (icloud.com, me.com and mac.com), Yahoo Mail (yahoo.com and ymail.com), Microsoft (Outlook.com, Hotmail and Microsoft 365) and Other (enter the details yourself). A tile is only a preset: it fills in the mail server, port and encryption, and the page reads the provider back from those values.

Tile Mail server Port Encrypt from the start
Gmail smtp.gmail.com 465 On
iCloud Mail smtp.mail.me.com 587 Off
Yahoo Mail smtp.mail.yahoo.com 465 On
Microsoft signs in instead
Other yours yours yours

Gmail and Microsoft can also send through their own service: Sign in with Google or Sign in with Microsoft opens that provider’s page in a new tab, where you choose the account and allow Frameleaf to send email from it. Frameleaf can send and nothing else: it cannot read your mail, and no password is kept on this server. Gmail keeps Use an app password instead beside it; Microsoft is sign-in only. Signing in needs a server linked to a Frameleaf account, because Google and Microsoft only let you sign in through a public web address; the account is free. Disconnect… stops sending until an account is set up again. See How connected accounts work.

  • Send email from this server (notifications.smtp.enabled, off). On, welcome emails, album invitations and album updates are sent from this account. Off, nothing is sent; invitations and album updates appear in the app only.
  • Email address (notifications.smtp.transport.username), for a provider tile: the address emails from this server come from.
  • App password (notifications.smtp.transport.password), for a provider tile. Gmail, iCloud and Yahoo don’t let other apps use your normal password; you make an app password on the provider’s own site, and How to make an app password for … opens its guide. The password is write-only: its row shows Stored or Not set, as described under Server credentials.
  • Mail server (notifications.smtp.transport.host), for Other: the address of your email provider’s sending server.
  • Mail account name (notifications.smtp.transport.username), for Other: usually your full email address.
  • Encrypt from the start (notifications.smtp.transport.secure, off). On, the connection is encrypted from the first moment, usual for port 465. Off, the connection is encrypted once it is made, if the mail server offers it, usual for port 587.
  • Sender address (notifications.smtp.from): the address people see emails come from. How it looks in an inbox shows the name and address together.

Advanced holds the rest:

  • Sender name (the name part of notifications.smtp.from): the name people see beside the address. Leave it empty to show the address only.
  • Send replies to (notifications.smtp.replyTo): where a reply to one of these emails goes. Leave empty to use the sender address.
  • How email is sent (notifications.smtp.transport.type, a mail server). After signing in it reads Through Google’s own service or Through Microsoft’s own service, and there is no mail server, port or password to set. Choosing a tile or Other sets it back to a mail server.
  • Port (notifications.smtp.transport.port, 587). Your email provider says which number to use; 465 and 587 are the usual ones. A tile fills it in.
  • Send even if the security certificate can’t be checked (notifications.smtp.transport.ignoreCert, off). Only for a mail server you run yourself. Leave off otherwise.

Check it works sends one email to your own address. A test that works also saves these email settings, and nothing else. Until the page is saved it says Save your changes first, and enter the password. The test uses what is saved.; with sending off it says Turn on “Send email from this server” first. A sent test shows the address and time; if it is not in your inbox, look in the junk folder.

Frameleaf writes a welcome for new people, an invitation when an album is shared, and a note when an album gets new photos. Most households never change them. Change the wording of emails opens one row per email, each saying Standard wording or Your wording, with Edit:

  • Welcome email (templates.email.welcomeTemplate): sent to someone when you make them an account. It can insert the person’s name, their sign-in email, the temporary password and a link to Frameleaf.
  • Album invitation email (templates.email.albumInviteTemplate): sent when someone shares an album with a person. It can insert the person’s name, who shared it, the album name and a link to the album.
  • Album update email (templates.email.albumUpdateTemplate): sent when photos are added to an album shared with a person. It can insert the person’s name, the album name and a link to the album.

The editor shows Insert into the email buttons for those names, a Preview with sample names, Use the standard wording and Use this wording. Leave the text empty to use the standard wording. Each default is empty, meaning the standard wording. See Email templates.

  • First line of an invitation (templates.email.invitationFirstLine, empty): the greeting at the top of an invitation email, for example “Hey [Person’s name]!”. [Person’s name] becomes their name, and [Who shared it] works too. Leave it empty for the standard greeting. If you have written your own wording for the album invitation email, that is sent as written, so this line opens the emails about shared photos instead.
  • Show the Frameleaf name and logo (templates.email.showBranding, on): at the top of every email this server sends.

What this server is called, which version it runs, where its maps come from, and what it records when something goes wrong. The area opens on three groups, This server, Updates & diagnostics and Maps, with the Troubleshooting, Server logs, Custom styling and Copy settings pages kept under Advanced. Server logs is the log viewer, covered in Monitoring and logs. Changes on every page wait in your draft until you select Save changes at the bottom of the settings; Reset this page puts the page back to what is saved. When the server’s settings come from a configuration file, every control here is read-only; see Configuration file.

What this server is called, and what people see before they sign in. Beside the fields, What people will see is a sample of the phone app’s server list and the sign-in page. It follows what you type.

Server name (server.name, empty) is shown in Settings and when people choose a server in the phone app. Without a name it shows as “This server”. Up to 100 characters; the sample suggests something like “The Rivera family photos”.

Welcome message (server.loginPageMessage, empty) is shown to everyone before they sign in. Keep it short. The sample shows it above the email and password fields, or No welcome message while it is empty.

Time zone (server.timeZone, Same as this computer) is used for the times on this server, such as when backups and overnight work start. Same as this computer is the zone of the computer Frameleaf runs on, named beside it once the page has asked the server; the list below it has every zone, west to east. A zone saved from a configuration file that isn’t in the list is kept and shown as typed.

Advanced: Welcome message is (server.loginPageMessageFormat, Plain text) chooses how the welcome message is read:

Choice What it means
Plain text (default) Everything you type is shown exactly as typed
Web formatting HTML, the code web pages are written in, lets you add a link or bold text. A mistake can change the sign-in page. Scripts, pictures and anything from other websites are always left out

Public server URL (server.externalDomain, empty) is the address this server has on the internet. Links in emails and shared links are built from it. It’s the same setting as the one under Remote access, shown here so a server without remote access can set it too.

Let phones on your Wi-Fi find this server (server.lanDiscovery, on). On, the phone app lists this server when it is on the same network. People still have to sign in. Off, people type this server’s address in the phone app. Turning it off only stops the broadcast: direct connections and sign-in work as before. While it’s on, any device on this network can see that a Frameleaf server exists here, and its server name, so choose a name without a person’s name in it. The server only broadcasts when it can see your home network; inside a container on a Docker bridge network it usually can’t, so use host networking if you want discovery from a container. The phone app’s side is in The discovery card.

Allow automations to call devices on my network (server.automationsLocalNetwork, off). Off, workflows send Frameleaf events only to secure (https) addresses on the internet. On, they can also reach devices at home, such as Home Assistant. This computer itself and cloud metadata addresses stay out of reach either way.

People can find each other when sharing (server.publicUsers) has moved: whether everyone can pick other people by name is now with People & sharing. Open People & sharing takes you there; see Sharing.

Ask Frameleaf (help.askEnabled, on) lets people ask questions in the help panel. The question, the conversation so far and this server’s hardware go to frameleaf.app’s Ask service. Help articles stay available either way. What the service receives, and how to use it from this website, is in Ask Frameleaf.

Let people bring in photos from iCloud (icloud.enabled, on). Each person signs in with their own Apple account. While this is off, nothing new comes in from iCloud; photos already here and saved sign-ins are kept. If a sync is running or waiting to run, on any account, Frameleaf warns you first. See iCloud Photos Sync server setup.

Which version of Frameleaf this server runs, and whether there is a newer one. The page opens on the answer. With Look for updates set to Never, it opens on You’re running Frameleaf and the version: the server isn’t looking, so it can’t say yet whether that’s the newest. Select Check now and it changes to is up to date with when it was checked. When the server looks every day or every week, the page opens on is up to date once a check has run. The other answers are that a newer version is available (you decide when to install it) and Couldn’t check for updates when Frameleaf’s release list did not answer; this server keeps working, so try again later. Check now asks straight away, whatever the schedule.

Versions lists Installed and, once a check has run, Newest from Frameleaf with when it was checked. When a newer version is available, two links follow, with a reminder that you install it from where this server was set up, not from this page: What is new opens the release notes for it, and Before you update reminds you to make sure a backup has finished and opens Backup; see Backup and restore.

Look for updates (newVersionCheck.enabled and newVersionCheck.frequency, Never) is one choice:

Choice What it sets What it means
Never (default) enabled off This server does not look. Use “Check now” when you want to know
Every day enabled on, frequency daily This server asks once a day whether there is a newer version
Every week enabled on, frequency weekly This server asks once a week whether there is a newer version

Hear about a new version opens Notifications: What needs your attention lists a new version as soon as Frameleaf finds one. See Command Center.

Two promises are printed on the page. This server asks only Frameleaf’s release list: the list is Frameleaf’s releases page on GitHub, nothing about your library is sent, and no other service is contacted. You decide when to install: Frameleaf tells you about a newer version and never installs one by itself. How to install one, for each kind of installation, is in Upgrading.

Advanced: Get early versions (newVersionCheck.channel, Off (recommended)) chooses which releases count. Early versions arrive sooner and may be less reliable:

Choice What it sets
Off (recommended) stable: only stable releases
On releaseCandidate: stable releases and release candidates

Advanced: Installed says whether this server runs A stable release or An early version, worked out from the installed version’s name. Having a problem? under More opens Troubleshooting to download a report.

Where the map comes from and whether photos get place names. The map’s own page, place search and fixing a location are in Places and the map.

Show photos on a map (map.enabled, on). On, the map pictures come from a map service: the device you view the map on asks it for the part of the world on screen. Your photos are never sent to it. Off, the Map page and the small maps beside photos are hidden for everyone.

Map look (Standard) chooses where the pictures come from. The choice is greyed out while the map is off:

Choice What it means
Standard (default) Frameleaf’s own map, in a light and a dark version
Custom The map is drawn from the style addresses under Advanced

Advanced: map style addresses holds the two addresses, which can only be typed once Custom is chosen. A map style is a file that says how the map is drawn and where its pictures come from. Each address must point to one.

  • Light map style address (map.lightStyle, https://tiles.frameleaf.cloud/v1/style/light.json)
  • Dark map style address (map.darkStyle, https://tiles.frameleaf.cloud/v1/style/dark.json)

The page shows Custom whenever either address differs from the standard one, including after a configuration file set them. Go back to the standard map, with Use the standard map, puts both addresses back to Frameleaf’s own map. Writing your own style, or building one with MapTiler, is in Use your own map style.

Name the places in your photos (reverseGeocoding.enabled, on) turns a photo’s location into a town and country, worked out on this server. Off, new photos get no place names; names already found are kept. How places are named on the page opens Place names stay on your server.

What to send when you need help, and what this server records to help fix a problem. This page is under Advanced on the area’s front page.

Download a report makes one file to send to whoever is helping you. It is made on this device and goes nowhere by itself. What the report includes: the Frameleaf version and which features are on; how much storage is used and free; how much background work is waiting; and this server’s settings, with the mail account and every password left out. It never includes photos, videos, file names or people’s names, and no passwords, keys or sign-ins. If the file can’t be prepared, the page says Could not prepare the diagnostics file.

A running record of what the server did, for finding out what went wrong.

Keep a record of what this server does (logging.enabled, on). On, the record stays on this server. Off, nothing is recorded, so a problem is much harder to find. The other two controls are greyed out while it’s off.

How much to record (logging.level, Normal) is a choice between two levels:

Choice What it sets What it means
Normal (default) log What happened and what went wrong, without the detail
Detailed debug Records much more, which helps whoever is helping you. It can include file names. Go back to Normal when the problem is solved

Advanced: Exact level (logging.level) has six levels, from only the most serious problems to everything. When one of the other four is chosen, How much to record shows it as a third choice and says Set to an exact level under Advanced:

Choice What it sets
Only what stops the server fatal
Errors only error
Warnings and errors warn
Normal activity log (Normal)
Detail for finding a fault debug (Detailed)
Everything verbose

Read the logs yourself opens Server logs, where administrators read, search and download the record in the browser. Where the record is kept, how to read it, and setting the level from the environment are in Monitoring and logs. Nothing in it is sent anywhere; see No telemetry.

The charts in Library analytics are drawn from a history kept on this server. It never leaves it. See Library analytics.

Keep a history for Library analytics (analytics.enabled, on) adds to that history every night. Off, Library analytics has nothing new to draw.

Keep it for (analytics.historyDays, 24 months) is how far back the history goes: 90 days, 12 months or 24 months. A length set from a configuration file that isn’t one of the three is shown as a number of days; anything from 30 to 800 days is accepted.

Change how Frameleaf looks for everyone on this server, with your own style sheet. This page is under Advanced on the area’s front page, and is for people who write CSS.

Use custom styling (theme.customCssEnabled, on). On, the style sheet below changes how Frameleaf looks for everyone. Off, Frameleaf has its standard look, and your style sheet is kept for later.

Style sheet (CSS) (theme.customCss, empty) applies to everyone who opens this server in a web browser, except on settings pages. For example:

p {
color: green;
}

A copy of this server’s saved settings, to keep or to load on another server. This page is under Advanced on the area’s front page. The file is the same shape as a configuration file.

Save to a file downloads the copy; Copy as text puts the same text on the clipboard, and Show the file displays it on the page. What is included: every setting on these Settings pages for the whole server. Never photos, videos, albums or accounts, and never passwords, keys or sign-ins inside an address; those are emptied before the file is made.

Load from a file changes nothing by itself. Each setting that would change is listed under Settings that would change, in the words of its own page, and in the bar at the bottom, and nothing is saved until you confirm there. While settings are waiting, the page says how many, and reminds you they are listed under “Load from a file”. Load from a file is hidden when the server’s settings come from a configuration file; the file itself is what to edit then.

A new server has no administrator. Until it has one, anyone on its home network can claim it; there is no setup code. Set it up soon after installing, before anyone else on your network reaches it.

Who can set it up

  • Only from your home network, never over remote access. A request counts as home when it comes from a private address, or through a trusted local reverse proxy that passes the visitor’s address in X-Forwarded-For. Tries are limited per address.
  • Only while the server has no administrator. Once one exists, setup is over.
  • For a server that isn’t on your home network, such as a rented server, connect through an SSH tunnel or add your network to FRAMELEAF_TRUSTED_LAN_CIDRS.
  • Restore from a backup onto a new server follows the same rules.

Setting up in the browser

Open the server’s address and setup starts on its welcome page. It goes through five chapters: Welcome, Account, Library, Protection and Ready.

  1. Create your admin account. Enter a name, an email and a password of at least 8 characters. This is the server’s own sign-in. It keeps working even when the internet or Frameleaf Cloud doesn’t.
  2. Add a Frameleaf account, if you want one. It’s optional: it links this server to a Frameleaf account so you can reach your library away from home, sign in anywhere and add Cloud Backup when you want it. Your photos stay on this server.
    • Create account and link makes a new Frameleaf account from the name and email you just gave, with a password for it. Frameleaf emails a 6-digit code to confirm the address.
    • I already have a Frameleaf account switches to its email and password, then Sign in and link. An account with an authenticator app asks for its code.
    • Skip for now leaves the server unlinked. You can link it later in Settings, then Frameleaf Cloud.
  3. Carry on through where the library lives and how it’s protected. Nothing is imported during setup.

The server is linked straight away, with no approval page to open on another device. The Frameleaf password is sent once and never stored on the server. If setup can’t reach Frameleaf Cloud, your admin account already works, so skip and link later.

Setting up from the Frameleaf app

The iPhone and Android apps can also set up a new server on your home network and link it to your Frameleaf account. An administrator made that way has no server password at first, and is asked to set one; see A password for the owner of a linked server. A server that’s already linked to a Frameleaf account is never set up or linked again: the apps join it with Sign in with Frameleaf.

See First steps.

Linking to Frameleaf Cloud is optional. FRAMELEAF_LINK_TOKEN links a server when it starts, without a browser, with a single-use link token (fll_…). An administrator can link a server that’s already set up from Settings or the app. See Frameleaf Cloud account.