ImageStoria
Sign in Start free trial

Run a worker

A worker is a program on a computer of your own that reads your pictures. It writes a caption for each one, finds the faces, and lets you search by what a picture shows. A gaming PC does it well.

Your library works without one. A worker only adds to it, and you can stop it whenever you like.

Your computer calls the library. The library never calls your computer.

The worker asks for work, fetches the pictures it is given, and sends back what it found. Nothing has to be opened on your router. No picture goes to an outside service.

What you need

  • A computer with Windows 10 or 11, or Linux.
  • An NVIDIA graphics card with a current driver is best. The setup below was measured on a card with 16 GB of memory.
  • Without an NVIDIA card it still runs, on the processor, slowly.
  • About 8 GB of free disk for the models.

You will type a few commands into a terminal. On Windows that is PowerShell, which you can find in the Start menu.

What each task adds

TaskWhat you get in the library
captionA caption, the kind of scene, what is in the picture, and any text that can be read in it.
embedSearch by meaning, More like this, and a filter for near duplicates.
facesFaces to group and name. Only in spaces where you have turned people recognition on.
placeA guess at where a picture with no location was taken. It stays a guess until you accept it.

What a machine said is shown in blue. What a person said is shown in amber. A person's correction always wins, and reading the library again never undoes it.

The steps

  1. Install Ollama and fetch the model

    Ollama runs the model that describes pictures. On Windows, run OllamaSetup.exe from ollama.com. On Linux, follow ollama.com/download.

    Then fetch the model. It is 6.6 GB, so give it a while.

    $ ollama pull qwen3.5:9b-q4_K_M

    Set Ollama's context length to 8192. Its default on most cards is 4096, which is tight for a picture and its answer. On Windows, add an environment variable named OLLAMA_CONTEXT_LENGTH with the value 8192, then quit Ollama and start it again.

  2. Get the worker and install it

    The worker is in the worker folder of the ImageStoria source. Download it from GitHub (Code, then Download ZIP) and unpack it, or clone it with git. Open a terminal in the worker folder.

    On Windows:

    $ powershell -ExecutionPolicy Bypass -File install.ps1

    On Linux:

    $ sh install.sh

    This sets up everything the worker needs inside its own folder. With no NVIDIA card, add the word cpu: sh install.sh cpu.

  3. Make a token in your library

    Open your library. Go to People and settings, open Workers, name the machine and press Make a token.

    The token is shown once. Copy it now. It lets this machine ask for work in your library, and it opens nothing else.

  4. Put the address and the token in worker.toml

    The install made a file named worker.toml in the worker folder. Open it in Notepad or any text editor and fill in the first two lines. Nothing else needs changing.

    site = "https://yourname.imagestoria.com"
token = "the token you just copied"

  5. Check it

    On Windows:

    $ .\run.ps1 check

    On Linux:

    $ sh run.sh check

    It tells you whether the library, the token, Ollama and the graphics card are all there. Fix whatever it names before going on.

  6. Run it

    The same command without the last word: .\run.ps1 on Windows, sh run.sh on Linux.

    One line appears for every picture it reads. Stop it with Ctrl + C. It finishes the picture in hand and gives the rest back.

    The first run fetches two more sets of models, about 630 MB together, for search by meaning and for faces.

How long it takes

On a 16 GB NVIDIA card a caption takes about 3.4 seconds, and the other tasks well under a second. A library of about 1,100 pictures took about an hour for captions and a few minutes for the rest. A bigger library takes longer in proportion.

To have it work only at night, set working hours in worker.toml:

hours = "22:00-07:00"

Keeping it running

The worker keeps nothing on your disk that matters. Turn the computer off whenever you like. When the worker starts again it asks for work and carries on.

To start it by itself when you sign in to Windows, run this once, with the real path to your worker folder:

$ schtasks /Create /TN "ImageStoria worker" /SC ONLOGON /TR "powershell -WindowStyle Hidden -ExecutionPolicy Bypass -File C:\path\to\worker\run.ps1"

On Linux it runs as a user service. The README has the file to copy.

Watching and stopping it

The Workers section of your library shows each machine, when it last checked in, and how much is waiting.

  • Pause stops a machine taking work.
  • Revoke ends its token for good.
  • Read everything again puts the whole library back in line for one task. Use it after changing to a better model. What a person corrected by hand is kept.

People in the pictures

Finding faces is off until you, the owner, turn it on, one space at a time, under People in the pictures in People and settings. The worker then finds the faces and you name them. Only the owner and editors see names and face outlines.

Face data is sensitive. Read the section on it in our privacy page before you turn it on.

More detail

The worker's README on GitHub covers other model servers, choosing a model by testing it on your own photos, moving the worker to another machine, and the licences of the models.

No spare computer? A cloud AI key can write the captions instead.

Connect your Space Use a cloud AI key