Workers and where jobs run
Cloud GPU in Frameleaf: fast AI jobs, a price before you start, and your approval Watch on YouTube
Put the graphics card in your desktop to work for your photo library. Frameleaf can hand heavy work such as faces, search and descriptions to other computers on your network, so it finishes faster and your server stays responsive. You decide, for each kind of work, where it runs and how heavy a model it uses, and work only ever runs where you’ve sent it.
Heavy work goes to the machine learning container that ships with the server, to other computers on your network, and to Frameleaf Cloud if you choose it. Open Settings, then Computers & background work, then Computers. The page has two views, chosen at the top:
- Everyday shows your computers and who does what: the list of computers, whose photos each one works on, and Where work runs, the table that chooses which computer does each kind of heavy work
- Advanced has each computer’s details, finer choices, limits for each person, checks, the order to try and history
For the jobs that run inside the server itself, see Jobs and queues.
Check your hardware first
Section titled “Check your hardware first”Settings, then Computers & background work, then Graphics card check tells you whether a graphics card is speeding up video, search and recognition, and how to fix it if not. Measure this server’s speed runs a test of a few seconds to a few minutes on this server that times search, a video transcode and descriptions. Restoration and Smooth motion speeds come from a restoration worker’s own measurement, when you have one. See Hardware acceleration.
Two kinds of worker
Section titled “Two kinds of worker”Library analysis and restoration never share a worker.
| Work | Runs on | Image |
|---|---|---|
| Library analysis: faces, smart search and similarity, text recognition, descriptions | The machine learning container, or another one on your network | frameleaf-machine-learning |
| Restoration: restoring and upscaling photos and video (Faithful and Creative) | A restoration worker on this server or your network | Built from source; see below |
Studio helpers, computers running Frameleaf’s Studio helper, handle Studio exports and previews.
The server enforces these rules:
- A destination on this server or your network may do library analysis or restoration, not both. Ticking one kind in the form closes the other.
- A restoration is refused, never moved, if its destination is still allowed both kinds of work from before this rule, or points at an address that library analysis is routed to.
- Destinations saved before the rule that allow both kinds keep running library analysis, and are listed under Computers allowed both kinds of work until you limit them to one.
Computers
Section titled “Computers”When a computer isn’t answering, Computers says so at the top. Below it is a card for each place work can run: This server, which is built in and can’t be removed, each computer that helps it, and Frameleaf Cloud. A computer is listed once, with one state:
| State | Meaning |
|---|---|
| Ready | It answered and can take its work |
| Not answering | The last check got no answer. Work set to run there waits for it; nothing moves on its own |
| Switched off | It’s turned off |
| Not asked yet | Frameleaf hasn’t checked it yet. The server asks when work arrives |
Each card also says where the computer is (Built in for this server and the Studio worker that ships with it, At home for another computer), what it helps with (Search and recognition, Studio and restoration) and how many kinds of work are set to run there. Details opens the computer’s own details. A computer running Frameleaf Desktop says Frameleaf Desktop is helping with search and recognition., or asks you to open the app on it to help again.
Add a computer
Section titled “Add a computer”A computer with Frameleaf Desktop needs no setup here: sign in to this server in the app and the computer joins Your computers by itself, once it has checked the models you’ve chosen. Members’ computers wait for an administrator’s approval. See Help with AI processing.
Add a computer, the last card in the list, offers two more ways to connect one:
- For search and recognition: connect by address. For a computer already running Frameleaf’s AI service, including Linux. Choose Connect by address, and in Add computer give it a Name, its URL, for example
http://192.168.1.40:3003, an Access token if it has one, and tick its Allowed work. - For Studio exports and AI restoration: connect with a code. For a computer running Frameleaf’s Studio helper. Choose Get a connection code, name the computer, and enter the code, shown once, on that computer. It connects to this server by itself.
Whose photos each computer works on
Section titled “Whose photos each computer works on”A computer at home with Frameleaf Desktop works on the photos of the account signed in on it. To let one graphics card help the whole home, let it work on everyone’s photos.
Whose photos each computer works on appears on Computers once a Frameleaf Desktop computer has joined. It has one row for each of them, with two choices:
| Choice | What it does |
|---|---|
| Only the account’s name | The computer works only on the photos of the account signed in on it. This is how every computer starts. |
| Everyone’s | The computer works on everyone’s photos at home, whoever is signed in on it. It counts as home, so it also does the photos of people who keep theirs at home. |
The change is saved as soon as you choose it.
- Locked photos stay with their owner. Another account’s Locked photos never go to a computer set to Everyone’s. The Locked photos of the account signed in on it are handled as before.
- Changing the choice stops work given out under the old one. A computer that was helping everyone can’t hand back results for other people’s photos after you set it to one account.
- This choice covers Frameleaf Desktop computers. A computer you added by address, and this server itself, already work for everyone.
Details
Section titled “Details”In Advanced, Each computer lists what each one does, with Manage to open it. Under the list, Addresses, connection codes and what each computer reported is closed until you need it:
- Studio helpers and their connection codes manages Studio helpers.
- AI helpers: addresses, access tokens and limits opens the Processing computers card, which edits each AI computer and its limits.
- This server’s AI service and how each computer answered shows the full inventory.
The inventory shows, for each computer:
| Field | What it shows |
|---|---|
| State | Not checked, Turned off, Not answering, No models ready, CPU only or Model ready |
| What this computer can run, GPU memory and acceleration | As the computer reported them. A restoration worker reports each GPU’s memory; the machine learning container reports only its execution providers, so its GPU memory shows as unknown |
| Credentials | No credentials in the URL, Token stored on the server, or for a Studio helper Enrolled; only a hash is kept. Tokens are never shown after they’re saved |
| Routed here and Admission | Which kinds of library work go to this computer, and what the server would answer for each, from the last check |
| Load | Jobs running and waiting for this computer |
A computer shows as ready once a check confirms it, not just because it has an address.
Further down, Library analysis routes lists each kind of library work and the computer it goes to; a kind with no route is shown as refused. Render computers lists Studio helpers by when they last checked in (they call the server, so there’s no address to show). Persistent video computers, when you have any, lists the restoration workers apart from library analysis, and Restoration runners on this server lists the server processes holding restoration jobs right now.
The inventory refreshes every 30 seconds while the page is open. If a refresh fails, the last snapshot stays on screen with its age. Check what it can run checks that one computer now and contacts nothing else.
Also in Advanced:
- Limits for each person sets how much Studio work one person can have running at once: exports, restoration and edits. Add an exception gives one person a different limit.
- Connections sets how this server checks the computers that help it: Keep checking computers, Check each one every (30 seconds by default) and Wait for an answer for (2 seconds by default). With no answer after that long, the computer shows as not answering. Order to try is here too; see below.
- History records every time a computer is added, removed, refused or stopped at a limit. It never records a code, a key or a file’s location.
Machine learning addresses
Section titled “Machine learning addresses”Machine-learning endpoints, in the inventory under Details, edits the list of machine learning addresses, the same list as in Settings, then Search & intelligence, then Advanced: the computer’s address.
- Use each worker’s base address, over HTTP or HTTPS, without a password, query or fragment.
- You can add up to 32, and at least one must remain. The default is
http://frameleaf-machine-learning:3003. - The server creates a destination for each address and sends any library work that has no route yet to the first one. The order sets nothing else.
- When an address leaves the list, its destination is turned off: work routed there is refused, not moved, until you route it elsewhere. Add the address back and the destination is turned on again.
- Removing an address doesn’t stop the worker itself, and existing restorations keep their destination.
To run the machine learning container on another computer, see Remote machine learning.
Choose where each kind of work runs
Section titled “Choose where each kind of work runs”Where work runs, on the Computers page, is one table, What runs where, with a row for each kind of heavy work: Visual search, Faces & identity, Text, documents & receipts, Descriptions & tags, Enhance & upscale, AI restoration, Transcripts & captions, Smooth motion and Studio export. Each row says whether it works on this server, and you pick where it runs:
- First available, in order, so the row follows Order to try.
- This server, or a computer at home by its name. A computer that isn’t answering shows (not answering).
- Frameleaf Cloud, paid with AI credit. The cost is shown before each job starts.
- Ask me each time, when the work can run both at home and on Frameleaf Cloud. You choose when you start each job, and When you’re asked each time, suggest, under Finer choices in Advanced, sets the place suggested first.
- Nowhere (keep this off), so the feature doesn’t run.
Choose Save changes to keep your choices, or Undo changes. New work follows them; work already started stays where it is.
Order to try, under Connections in Advanced, is a list of places: This server, Your computers (computers at home with the Frameleaf Desktop app, and any you added by address) and Frameleaf Cloud. Each shows whether it’s ready, not answering, not set up, turned off or needs your permission. New work goes to the first place on the list that can take it. If none can, it waits and starts when one is back. Work never goes anywhere that isn’t on the list, and Frameleaf Cloud takes only work you allow there, within your spending limit. Move a place up or down to change the order.
When a computer at home isn’t answering appears once another computer helps. It decides what happens to work set to run on it:
-
Wait and tell me: the work waits, and starts when the computer is back. You get a notification.
-
Stop and tell me: the work stops, and you get a notification to choose another place.
-
Always at home: Text, documents & receipts may move to another computer at home, never to Frameleaf Cloud. Studio export isn’t chosen here: it runs on a computer with a graphics card that is connected for Studio, never on Frameleaf Cloud.
-
Search and faces on Frameleaf Cloud: Visual search and Faces & identity can run on Frameleaf Cloud. See Search and faces on Frameleaf Cloud below.
-
Finer choices: in Advanced, Individual pets normally follows Faces & identity, and Creative restoration follows AI restoration. Give one its own place only if you need to.
-
Set somewhere else: description quality is in Descriptions & tags, and linking, AI credit and spending limits are in Frameleaf Cloud.
Each person’s photos
Section titled “Each person’s photos”Each person chooses whether AI work on their own photos may use Frameleaf Cloud: At home or on Frameleaf Cloud, which follows your choices on this page, or Only at home. They set it in Settings, then Your preferences, then Where your photos are processed; see Where your photos are processed.
When Frameleaf Cloud is in use, Each person’s photos on Computers lists every account with its choice. You can see each choice here; only that person can change it. Change your own choice opens your own preference.
For someone who keeps their photos at home:
- Work set to Frameleaf Cloud runs on this server or a computer at home for their photos instead, or waits. The row in What runs where names the people this applies to.
- A row set to Ask me each time never offers Frameleaf Cloud for their photos.
- Visual search and Faces & identity read their photos at home with the same model, so results stay one set.
- Photos they share keep the choice: a photo in a shared album, or seen by a partner, follows its owner’s choice, whoever looks at it.
- Work that already started on Frameleaf Cloud finishes there. The choice affects new work only.
Search and faces on Frameleaf Cloud
Section titled “Search and faces on Frameleaf Cloud”Visual search and Faces & identity offer Frameleaf Cloud only when both of these are true:
- Frameleaf Cloud carries the same model this server is set to use. The model is chosen in Search & intelligence, and the Cloud never swaps in another.
- The feature is turned on in the Cloud processing terms: Prepare smart search on Frameleaf Cloud and Find and recognise faces on Frameleaf Cloud.
The server sends a preview of each photo, never the original, with location and camera metadata stripped first. It accepts a result only when the model that made it matches its own. Frameleaf Cloud doesn’t identify anyone: grouping faces into people and naming them happen only on this server. What you search for is also read only on this server and never leaves it. The work is paid for with AI credit as photos are read.
Each of the two runs in one place only, never Ask me each time, because one index has to come from one model. If you change the model, every photo is indexed again.
Choose how heavy a model to use
Section titled “Choose how heavy a model to use”Settings, then Frameleaf Cloud, then Cloud processing has a Models card with a slider for each kind of work, from lighter to heavier models. The colour of each stop shows where it can run:
- White: runs on the processor
- Green: fits your GPU, as the last graphics card check found it
- Blue: runs only on Cloud GPU
Run the graphics card check to see which stops fit your GPU; until then every local stop is white. Models that need more GPU memory than you have, or CUDA on a GPU without it, are crossed out with the reason. Models whose licence doesn’t allow commercial use never run in the cloud.
Visual search, People, Descriptions, AI restoration and Studio also have a slider of their own on their settings pages, marked from good to best. Changing the visual search or people model reads your library again, and a new face model looks for faces again from the start, so pick it before a big import if you can. For visual search, an administrator can also enter a public model from Hugging Face by name; Frameleaf downloads only its model files, and refuses it with a plain message if it can’t load.
A Cloud stop starts the work on Frameleaf Cloud. If something is still missing, such as linking your account, accepting the terms or adding credit, one sheet lists just those steps and takes you back to the job with a fresh estimate. When Frameleaf Cloud is chosen for descriptions, enhance, restoration, smooth motion, search or faces, that work runs only on the Cloud, even if a computer at home could run it.
Choosing a white or green stop for descriptions changes the description model setting, saved with the settings bar. Ordinary online workers download a missing model before its first job, which can take several minutes. With staged local inference, download and verify models before you start the isolated worker, because it doesn’t fetch models itself. Restoration workers bring their own models.
A separate restoration container
Section titled “A separate restoration container”From a source checkout, start it next to the regular services with the overlay file:
docker compose -f docker-compose.yml -f docker-compose.restoration.yml up -dThen add a home network destination at http://frameleaf-restoration:3004, allowed restoration only, with the token from FRAMELEAF_RESTORATION_TOKEN if you set one.
| Variable | What it sets | Default |
|---|---|---|
FRAMELEAF_RESTORATION_GPU |
The GPU the restoration worker uses | None; you must set it |
FRAMELEAF_RESTORATION_TOKEN |
A bearer token the worker requires. Store it on the destination | Empty (no token) |
FRAMELEAF_RESTORATION_CONFIG |
Folder with the model manifest and qualification record, read-only | ./restoration/config |
FRAMELEAF_RESTORATION_WEIGHTS |
Folder with the model weights, read-only | ./restoration/weights |
Keep library analysis responsive
Section titled “Keep library analysis responsive”- Separate GPUs: set
FRAMELEAF_RESTORATION_GPUto a GPU the machine learning container doesn’t use, and pin that container to its own GPU withdevice_idsinhwaccel.ml.yml. - One GPU for both: tick This computer shares a GPU with library analysis on the restoration destination. Full restorations then wait while face, search, text and description jobs have work, and start when it’s done. Previews still run, because someone is waiting for them and they’re short. A paused library queue doesn’t hold restoration back.
- On the server: each server process runs at most one restoration at a time on its own loop, so a restoration never takes a job queue’s slot.
Long jobs keep going
Section titled “Long jobs keep going”Start a long job and walk away. Studio renders, edits, restorations, bulk changes, description runs, Library Care scans, imports and physical deduplication keep running when you close the browser, and carry on after a server restart.
- A failed attempt is retried once automatically after 30 seconds.
- A failed attempt leaves the previous good result in place.
- Jobs belong to the person who started them. Administrators see how many there are, not what’s in them.
For scripts
Section titled “For scripts”GET /api/admin/workers returns the inventory to administrators. It reads stored state only: loads are counts, runners are process names, and no owner, item or credential is returned. Destinations, routes and checks use the /api/ml-destinations endpoints.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.




