Skip to content

Getting started

Proton Faces runs as three Docker containers: a Proton bridge that talks to your encrypted Drive, an indexer that does the recognition work, and a FastAPI app that serves the web UI. This section walks through installation, your first run, and a tour of the main features.

Choose your path

Quickstart

Install the CLI, sign in once, and reach your first real search in ~10 minutes. Read this first.

Installation

All the knobs: .env, volumes, single-process mode, local dev, GPU-free hardware requirements.

Demo mode

Run the full app with zero Proton credentials. Bundled CC0 photos, auto-created admin user, no session file needed.

Session file

How to get the Proton Drive SDK auth session and keep it safe. Required for the real install.

What you'll need

Minimum Recommended
CPU 4 cores 6+ cores (face detection is CPU-bound)
RAM 4 GB 8 GB (InsightFace buffalo_l + CLIP loaded once)
Disk 2 GB + ~1 KB/photo of thumbs + a few GB of SQLite SSD; the data volume grows with your library
Docker 20.10+ Compose v2
OS Linux, macOS, Windows (with WSL2) Linux for production

No GPU is required — InsightFace and CLIP both run on CPU through ONNX Runtime.

Typical time investment

Step Time
Download the CLI + sign in once (browser) 2–5 min
Export the session to credentials/ 30 s
Pull images and bring up containers 30–60 s
First sync against a 1000-photo library ~5 min
First sync against a 100 000-photo library ~1 day (background, resumable)
Reading the docs (skim) 15 min

The first sync is fully resumable: add photos to Proton and the indexer catches up automatically.


Next: read the Quickstart to see end-to-end usage with screenshots.