HexOS
Frameleaf runs on HexOS through Frameleaf Manager. You install Manager as a HexOS app, and Manager then installs the photo library, keeps database backups and handles Frameleaf updates. HexOS gives Manager its own folders inside the storage locations you already use, so there’s nothing to type in apart from your Manager password.
Today you install it with a Custom Install script. A one-click listing in the HexOS app catalog is coming soon: it’s waiting for approval from HexOS.
| Custom Install script | App catalog (coming soon) | |
|---|---|---|
| How | Turn on experimental features, then paste the Frameleaf script into Custom Install | Apps, search for Frameleaf, Install |
| Manager version | The newest Manager release at the time you install or update | The release listed in the HexOS catalog |
| Updates | HexOS offers an update when a newer Manager image is published | HexOS offers each new Manager release |
| Best for | Everyone today, and anyone who wants the newest Manager straight away | Most people, once Frameleaf is listed |
Both install exactly the same Manager with the same folders, so you can move from one to the other later without losing anything. See Switch between the two.
Before you begin
Section titled “Before you begin”Storage locations. Frameleaf uses three of the locations in HexOS Settings → Locations. If one isn’t set yet, HexOS asks you to choose it before it installs anything.
| HexOS location | Frameleaf folder | What’s kept there |
|---|---|---|
| Applications (performance) | frameleaf/manager |
Manager’s settings, your Manager administrator and its operation history |
| Applications (performance) | frameleaf/databases |
The Frameleaf database. Manager creates a new directory here for each library and never reuses an old one |
| Photos | frameleaf |
Your original photos and videos, with thumbnails, encoded videos and other files Frameleaf creates |
| Applications (capacity) | frameleaf/backups |
Encrypted database backups and recovery settings |
The performance location is usually on SSDs, which keeps the database fast. The capacity location is usually your large hard-drive pool, so database backups end up on different disks from the database itself. HexOS creates every folder for you.
Hardware. Allow at least 4 processor cores, 8 GB of memory and 10 GB of free space for the apps, plus room for your library. Face recognition and smart search need more. See Requirements.
Ports. Manager starts on port 2282. If another app already uses it, HexOS gives Manager the nearest free port, and Launch in HexOS opens it. The photo library normally uses 2283, and you can choose another port during setup. If Immich is installed on this server through HexOS, it already uses 2283, so pick a different port for Frameleaf, such as 2284.
Docker access. Manager installs Frameleaf’s server, database and optional machine learning as separate containers, so it needs access to Docker on your server. Manager drops every other privilege when it starts. Keep Manager on your home network and don’t forward Manager’s port to the internet.
Install with a Custom Install script
Section titled “Install with a Custom Install script”Every Frameleaf Manager release includes frameleaf-manager.hexos.json, a HexOS install script that always runs the newest Manager image.
1. Download and check the script
Section titled “1. Download and check the script”-
Open the newest Frameleaf Manager release from the link above.
-
Under Assets, download
frameleaf-manager.hexos.jsonandSHA256SUMSinto the same folder. -
Check the download. On a Mac or Linux computer, run this in that folder:
Terminal window shasum -a 256 --check --ignore-missing SHA256SUMSIt prints
frameleaf-manager.hexos.json: OK. On Windows, runGet-FileHash .\frameleaf-manager.hexos.jsonin PowerShell and compare the hash with theframeleaf-manager.hexos.jsonline inSHA256SUMS. If it doesn’t match, download the file again and don’t use it.
The release’s signed manager-manifest.json records the script’s exact contents. To check that signature too, follow Verify Manager installers.
2. Turn on Custom Install
Section titled “2. Turn on Custom Install”In HexOS, go to Settings → Preferences and turn on Experimental features. If your HexOS also shows Expert mode under Advanced Settings, turn that on too. This adds Custom Install to Apps. You only need to do this once.
3. Paste the script and install
Section titled “3. Paste the script and install”- Open
frameleaf-manager.hexos.jsonin a plain text editor, such as TextEdit, Notepad or VS Code. Select all of it and copy it. - In HexOS, open Apps and choose Custom Install.
- Click in the script editor, select everything already there and delete it, including any leftover
{ }. Then paste the Frameleaf script. - Select Install. If a location isn’t set yet, HexOS asks you to choose it.
- Wait for Frameleaf to show as running, then continue with Open Manager and set up your library.
If the editor shows an error, the paste was probably cut short. Copy the whole file again and replace the editor’s contents.
Install from the HexOS app catalog (coming soon)
Section titled “Install from the HexOS app catalog (coming soon)”Once Frameleaf is listed:
- In HexOS, open Apps and search for Frameleaf.
- Select Install. HexOS checks that your Applications and Photos locations are set and offers to set any that are missing.
- Follow the install progress in the activity center. HexOS creates the Frameleaf folders and starts Frameleaf Manager. The first start can take a few minutes while HexOS downloads Manager.
- Once the app shows as running, continue with Open Manager and set up your library.
Open Manager and set up your library
Section titled “Open Manager and set up your library”- From a device on your home network, open the Frameleaf app in HexOS and select Launch, or go to
https://<your-server's-address>:2282. If HexOS gave Manager another port, use Launch. - Your browser warns that the connection isn’t private. Manager makes its own certificate for your home network, and browsers don’t know it yet. Continue to the page: in Chrome or Edge choose Advanced and then Proceed, in Safari choose Show Details and then visit this website, and in Firefox choose Advanced and then Accept the Risk and Continue.
- On Secure your Manager, enter your name and a password of at least 14 characters, then select Create administrator. This only works from your home network, and only until Manager has an administrator, so do it soon after installing. See Create your Manager administrator.
- On Choose how to begin, select Set up Frameleaf under Set up a new library. Manager has already filled in your HexOS folders:
- Media location: the
frameleaffolder in your Photos location. - PostgreSQL appdata location: the
frameleaf/databasesfolder in your Applications location. - Database backup destination: the
frameleaf/backupsfolder in your capacity location.
- Media location: the
- Choose the Frameleaf port, normally
2283, and a Frameleaf release. Turn on Machine learning if you want face recognition and smart search. - Tick the startup checkbox. HexOS and Docker start Frameleaf when the server starts, so nothing else needs to.
- Select Check this server, fix anything it lists, then select Review installation and Install Frameleaf. You can close the page while Manager works. See Check this server on HexOS.
When Manager shows All done, carry on with Finish your photo account and phone setup and Save your recovery information. Your photo library opens at http://<your-server's-address>:2283, or the port you chose.
If you have a Frameleaf backup from another server, choose Restore a backup on Choose how to begin instead. See Backup and restore.
Check this server on HexOS
Section titled “Check this server on HexOS”Check this server looks at Docker, your folders, the port, the network, the signed release and memory before anything is downloaded, and lists every problem at once with steps for HexOS. See Check this server.
- Docker is too old. Update HexOS to the latest version, then open Manager again.
- Manager can’t use Docker. Check Applications are running in HexOS, or restart the server.
- Not enough room in Docker’s storage. Free some space on the drive that holds your applications, or remove apps you no longer use.
- Manager can’t reach a folder. Check the Applications location you chose for Frameleaf is on a drive inside this server. If you changed that location, choose it again for Frameleaf in HexOS.
- This server has less than 8 GB of memory. Frameleaf still works, but faces and smart search can run out of memory. Select Turn off faces and smart search, or carry on.
For every message and its fix, see Problems Check this server can report.
Fast drives on HexOS
Section titled “Fast drives on HexOS”HexOS chooses the drives for you. The database goes in your Applications (performance) location, which is usually on SSDs, and thumbnails stay with your photos in the Photos location. Manager’s Storage page shows where each one is, how much room it uses and how much is left on its drive. See Move data to another drive.
Keep your library safe
Section titled “Keep your library safe”- Database: use Make one now on Backups in Manager. Backups go to the
frameleaf/backupsfolder in your capacity location, encrypted. Manager also saves a recovery point before every Frameleaf update. - Photos and videos: Manager’s backups don’t include them. Back up the whole
frameleaffolder in your Photos location, includingthumbs, which also holds edited versions that can’t be recreated. - Recovery information: export Manager’s configuration and recovery key and keep them away from this server. Without them, a backup can’t be restored on a new server.
- Snapshots: before HexOS updates the Frameleaf app, it takes a snapshot of Manager’s folder and the database folder and keeps the three most recent. They help HexOS support roll back a failed update. They don’t replace backups, because they’re stored on the same disks.
See Backup and restore.
Updates
Section titled “Updates”There are two things to update, and each has its own place:
- Frameleaf Manager: HexOS shows Update on the app’s Application info card when a new Manager is available. The app has to be running to update. Your Manager settings, administrator and library stay as they are.
- Your photo library: Manager installs new Frameleaf versions automatically and saves a database recovery point before each one. To choose when yourself, turn Install updates automatically off under Updates. See Upgrading.
Switch between the catalog and Custom Install
Section titled “Switch between the catalog and Custom Install”Once Frameleaf is listed in the HexOS app catalog, you can move your Custom Install over to it. HexOS won’t install a catalog app while a custom app with the same name is installed, so:
- In Manager, open Services, choose Stop stack and confirm Stop services.
- In HexOS, uninstall the Frameleaf app. This removes Manager’s container only. Your folders and everything in them stay.
- Install Frameleaf from the catalog as above.
- Open Manager. It finds its saved settings, so sign in with your existing Manager password. On Services, choose Start stack.
The same steps work in the other direction.
Remove Frameleaf
Section titled “Remove Frameleaf”- In Manager, open Services, choose Stop stack and confirm Stop services.
- In HexOS, uninstall the Frameleaf app.
HexOS leaves the Frameleaf folders in your locations. Only delete them once you’re sure you have a copy of your photos and videos elsewhere: the frameleaf folder in your Photos location holds your originals.
Switching from Immich on HexOS
Section titled “Switching from Immich on HexOS”The HexOS install gives Manager access to Frameleaf’s own folders only. It can set up a new library or restore a Frameleaf backup, but it can’t import an Immich app that HexOS installed. Leave Immich running on its own port while you try Frameleaf, and keep it until your photos are in Frameleaf.
To bring an Immich library over on another kind of server, see Switch from Immich.
Troubleshooting
Section titled “Troubleshooting”HexOS says a location is missing. Set it in Settings → Locations, then select Install again.
Manager isn’t on port 2282. Another app had that port when you installed, so HexOS chose the nearest free one. Open Manager with Launch in HexOS.
Manager won’t let you create the administrator. Open Manager from a device on the same home network as the server, not over a VPN or the internet. If an administrator already exists, sign in with its password instead.
Manager refuses the Frameleaf port. Another app, often Immich, is using it. Choose a different port, such as 2284.
The photo library doesn’t open after a server restart. Open Manager. Services shows each part of Frameleaf and its health. Use Start stack if it’s stopped, or check its logs from there.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.