# Remote machine learning

Source: https://frameleaf.app/docs/admin/remote-machine-learning/

Got a small server, such as a Raspberry Pi, and a more powerful desktop or laptop nearby? Run Frameleaf's machine learning container on the bigger computer and get faster smart search and face detection without upgrading your server. The server sends image previews to that computer for processing, and the machine learning container doesn't keep them or link them to a user.

Smart search and face detection use the remote container. Grouping faces into people doesn't, because it works from results already saved in the database.

:::danger
Image previews are sent to the remote computer, so use a computer you trust rather than a shared machine or a paid cloud service. Keep the worker on a trusted network and restrict which hosts can reach it. To require authentication, set `FRAMELEAF_ML_AUTH_TOKEN` on the worker and the same value as its destination's **Access token**. Use HTTPS across untrusted networks.
:::

## Set it up

1. Install Docker on the remote computer.
2. Save this as `docker-compose.yml` on the remote computer:

```yaml
name: frameleaf_remote_ml

services:
  frameleaf-machine-learning:
    container_name: frameleaf_machine_learning
    # For hardware acceleration, add one of -[armnn, cuda, rocm, openvino, rknn] to the image tag.
    # Example tag: ${FRAMELEAF_VERSION:-latest}-cuda
    image: ghcr.io/frameleaf/frameleaf-machine-learning:${FRAMELEAF_VERSION:-latest}
    # extends:
    #   file: hwaccel.ml.yml
    #   service: # set to one of [armnn, cuda, rocm, openvino, openvino-wsl, rknn]
    volumes:
      - model-cache:/cache
    restart: always
    ports:
      - 3003:3003

volumes:
  model-cache:
```

3. Start it with `docker compose up -d`.
4. On your Frameleaf server, go to **Settings**, then **Search & intelligence**, and open **Advanced: the computer’s address**.
5. Click **Add address**, enter the remote container's address, for example `http://192.168.1.50:3003`, and select **Save changes**.

You can also add it in **Settings**, then **Computers & background work**, then **Computers**: under **Add a computer**, choose **Connect by address**. In **Add computer**, fill in:

- **Name**, required, for example `Office desktop`. **Where work runs** and the list of computers use it.
- **URL**, the remote container's address, for example `http://192.168.1.50:3003`.
- **Access token**, the value of `FRAMELEAF_ML_AUTH_TOKEN` on the worker, if you set one. It's stored on the server and never shown again.
- **Allowed work**, the kinds of work it may run, for example **Visual search** and **Faces & identity**.

Then choose **Save**. Each address becomes a destination you can route work to and check. See [Workers and where jobs run](https://frameleaf.app/docs/admin/workers/#machine-learning-addresses).

To use a GPU on the remote computer, also add `hwaccel.ml.yml` and follow [Hardware acceleration](https://frameleaf.app/docs/admin/hardware-acceleration/#set-it-up).

:::caution
Keep both computers on the same Frameleaf version. Update the remote container whenever you upgrade the server.
:::

## Route work to the remote computer

Each address in the list becomes a computer you can send work to. Library work that has no route yet goes to the first address in the list; the order sets nothing else. To send work to the remote computer, choose it for each kind of work (faces, visual search, text, descriptions) in **Settings**, then **Computers & background work**, then **Computers**, under **Where work runs**. See [Workers and where jobs run](https://frameleaf.app/docs/admin/workers/).

:::note[No automatic fallback]
Work goes exactly where you route it. If the remote computer is off, work routed to it waits until it's back, and **Where work runs** shows **Waiting** for it; nothing moves to the local container on its own. With **When a computer at home isn’t answering** set to **Stop and tell me**, the work stops instead and you get a notification to choose another place. Until then, smart search and face detection don't run for new photos, and neither do duplicate detection and face grouping, which depend on them. If you remove the computer, work set to run only there goes back to **First available, in order**.
:::

If everything runs on the remote computer, you can remove the local address and the `frameleaf-machine-learning` service from your server's Compose file to save resources. At least one address must stay in the list.

## Several machine learning computers

Each kind of work goes to one computer. To share one kind of work across several computers, put a load balancer in front of them and use its address for that work. That also lets you mix configurations on one computer, for example an OpenVINO container next to a CUDA one, or a CPU container alongside a GPU one to use both.

One machine learning container can serve several Frameleaf servers, even if they use different models, though that raises peak memory use.

## Whose photos it works on

A computer added by address works on everyone's photos, like the server's own machine learning container. A computer that joins through [Frameleaf Desktop](https://frameleaf.app/docs/apps/desktop/) starts with only the photos of the account signed in on it; see [Whose photos each computer works on](https://frameleaf.app/docs/admin/workers/#whose-photos-each-computer-works-on). Either kind counts as home, so it also takes the photos of people who chose **Only at home** in [Where your photos are processed](https://frameleaf.app/docs/using/account-settings/#where-your-photos-are-processed).

## Where the models come from

The remote container downloads each model the first time a job needs it, from the same model source as the server's own container, and keeps it in its `model-cache` volume. To point it at a mirror of your own, see [Where models come from](https://frameleaf.app/docs/admin/environment-variables/#where-models-come-from). To run it with no internet access, see [Model staging](https://frameleaf.app/docs/admin/model-staging/).
