Everlock One server for your digital life

Documentation

Last updated: 2026-07-27

Getting started: Image backend

This guide walks through a local first run of Everlock's image backend:

  • start Everlock with one image instance bound to localhost
  • create a user through the admin SSH console
  • log in to the gallery in a browser
  • upload a photo and view it back

This guide uses the image service in its normal single-instance local setup:

  • one image instance selected by vhost
  • the embedded apimeister-photos (ami) gallery, Immich API compatible
  • login backed by Everlock users
  • access scoped to the image instance

1. Start Everlock with the image backend enabled

The two parts that trip people up:

  • --backend-image-http enables the backend. On its own, --backend-image-http-vhost only names the instance — without the enable flag the backend never starts and you only get the admin SSH surface.
  • All runtime flags go after the serve subcommand. A bare everlock --backend-image-http-... fails with unexpected argument.

For a local first pass, grab the binary for your platform from the download page, then start Everlock with one image instance on localhost:

./everlock serve \
  --backend-image-http \
  --backend-image-http-vhost localhost \
  --backend-image-http-store everlock-image-local \
  --admin-user admin \
  --admin-password change-me

What this does:

  • starts Everlock with the HTTP frontend on its default 0.0.0.0:8080 (auto-enabled because an HTTP backend is on)
  • enables one image instance reachable as localhost:8080
  • stores image data in the everlock-image-local Everlock store
  • bootstraps an admin user for the SSH admin console

The image backend is host-routed, so the vhost matters. localhost is used here so the browser reaches it with no extra setup. For a custom host like photos.example.com you would map it in DNS (or /etc/hosts for local testing) so the browser sends the matching Host header.

2. Open the admin console

Connect over SSH:

ssh -p 2222 admin@localhost

Enter the bootstrap password:

change-me

You should land in the Everlock admin REPL:

Everlock Admin
>

Create a normal user that will own the gallery:

/users add alice change-me

Grant the user owner on the image instance:

/users grant alice http/image/default owner

A few things to know about access on the image backend:

  • The bootstrap instance created by --backend-image-http-vhost is named default, so its access path is http/image/default.
  • Roles map to HTTP methods: Reader covers GET/HEAD, Writer adds uploads (POST/PUT/PATCH), Owner adds DELETE.
  • Inside the gallery, Everlock Owner maps to ami Admin; every other role maps to Guest. So grant owner for the person who runs the gallery, and writer for contributors who should upload but not administer.
  • A user needs at least Reader to log in at all. Public anon access is not implemented for the image backend today.

You can also manage instances entirely from the admin console:

/image list                          list image instances
/image create photos vhost=photos.example.com   add another instance
/image set default vhost=img.local              add a vhost to an instance

Open the instance in a browser:

http://localhost:8080/

You'll be redirected to the login page. Sign in with the user you just created:

  • username: alice
  • password: change-me

Login authenticates against the Everlock user registry — there is no separate gallery password store.

5. Upload and view a photo

From the gallery UI, upload an image (drag it in or use the upload control). The asset is stored in the everlock-image-local Everlock store, with its canonical metadata embedded as XMP in the original file — there is no secondary database. Once the upload finishes, the photo appears in your timeline.

Because ami is Immich API compatible, you can also point an Immich-compatible mobile or desktop client at http://localhost:8080 and log in with the same Everlock credentials.

If the upload succeeds and the image renders back, your image backend is working end to end:

  • HTTP frontend
  • host dispatch by vhost
  • Everlock auth
  • the embedded ami gallery
  • Everlock store-backed persistence

6. What is happening under the hood

Current behavior:

  • frontend-http accepts the request on port 8080
  • backend-image-http selects the instance by Host: localhost
  • Everlock validates alice and maps the request to http/image/default
  • the embedded apimeister-photos (ami) router handles the gallery
  • assets are stored in the everlock-image-local Everlock store, metadata embedded as XMP in the original files

If backend-ai-ssh is also enabled, the image backend reuses that already loaded everlock-ai-runtime model to generate captions — there is no second model load.

7. Operator notes

  • Image instances are managed through /image ... in the admin SSH console.
  • Multi-instance setups are stored in config/image-http.toml; once that file exists it becomes the source of truth and the CLI bootstrap flags are no longer needed.
  • Adding or removing a vhost on an instance hot-reloads; creating or deleting an instance requires a restart.
  • The backend is store-backed, so large image traffic creates many store commits.
  • A usable image instance requires at least one configured vhost.
images gallery getting-started