PhotoDrop — Run Guide

A zero-cable LAN photo-transfer tool. Run it on the computer you want photos on; it shows a QR code; a phone on the same Wi-Fi scans it and taps to upload photos, which land in a local folder and appear in a live desktop gallery. It is self-contained and access-controlled: the interface is inlined (no CDN), the QR is generated locally, and a per-session token gates every page and data request.

Clinical use case: capture high-quality intraoral/clinical photos on a phone and get them onto the operatory computer's imaging folder with no cables, no email, no app — the photos land in a local directory the imaging software can import, and nothing leaves the local network.

Status: ✅ Verified — the whole server-side flow was exercised end-to-end: the server starts, serves the desktop and mobile pages, refuses page and data requests without the access token (403), accepts a raw-binary upload (POST /api/upload → Success), lists it (/api/list), and serves the image back (HTTP 200) — with a locally-generated QR and zero CDN refs confirmed. The one part that can't be automated is the physical phone QR-scan — that's a manual check.

Sensitive data: none. No secrets, no accounts, no config. Uploaded photos land in a local ./dropped_photos/ next to the script.

What it is

A single ~330-line Python file (photodrop_secure.py) — Python standard library plus one small pure-Python dependency, segno, used to generate the pairing QR locally. The entire responsive web UI (desktop + mobile) is embedded as a string, with hand-written CSS and emoji icons, so it renders with no internet. It auto-detects the machine's LAN IP, serves on port 8000, and opens the desktop view in your browser. Every request carries a per-session access token (it rides inside the QR); a request without it gets a 403.

Prerequisites

Python 3.8+ and one small package:

pip install segno

(New machine? Install Python per ../SETUP.md.) No virtualenv or Docker needed.

Run it — this is the whole recipe

python photodrop_secure.py            # add --https for TLS (see Encryption below)

It prints the Desktop URL (which carries the access token), opens your browser to it, and shows a QR code. On your phone (same Wi-Fi): scan the QR → Tap to Select Photos → they upload and appear in the desktop gallery, saved to ./dropped_photos/. Ctrl-C to stop.

• Pin a fixed token instead of a random per-session one: PHOTODROP_TOKEN=some-token python photodrop_secure.py.
• Change the port with --port 9000; change the save folder by editing UPLOAD_DIR at the top of the file.

Why there's no prebuilt-image / Docker tier

Deliberately omitted — it would add friction for zero benefit ("if it isn't needed, don't include it"). PhotoDrop must present the host's LAN IP and be reachable from phones on the LAN, so a container would need host networking and still gain nothing over python photodrop_secure.py. One file, one command is the distribution.

Verify

pip install segno
PHOTODROP_TOKEN=testtok python photodrop_secure.py &                        # start it; token pinned for this check
curl -s "http://localhost:8000/?token=testtok" | grep PhotoDrop             # desktop page
curl -s "http://localhost:8000/?mode=mobile&token=testtok" | grep "Tap to"  # mobile upload page
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/             # → 403 (no token = denied)
curl -s -X POST "http://localhost:8000/api/upload?name=t.png&token=testtok" --data-binary @some.png   # → Success
curl -s "http://localhost:8000/api/list?token=testtok"                      # → the file appears

Then the real acceptance test: open the desktop page, scan the QR with a phone, and upload a photo.

Encryption — --https (built in)

The token blocks other devices, but plain HTTP means someone sniffing the same Wi-Fi could still capture the token/photos. There is a built-in self-signed TLS mode:

pip install cryptography              # (or just have `openssl` on PATH) — used to generate the cert
python photodrop_secure.py --https    # auto-creates cert.pem/key.pem, serves over https://

On first run it generates a self-signed cert for your LAN IP (reused afterward), wraps the socket with stdlib ssl, and the QR switches to https://. Real encryption — the one cost is a one-time "not private" warning on the phone (self-signed isn't CA-trusted); tap through. Bring your own cert with --cert / --key.

Warning-free alternative: use mkcert / your own CA to issue a cert for the LAN IP and install the CA root on each device once — green-lock HTTPS, no warnings, but per-device setup. A public CA (Let's Encrypt) is impractical for a bare LAN IP (needs a public domain name).

Caveats & clinical notes

• Plain HTTP unless you pass --https. The access token stops other devices on the Wi-Fi from viewing or uploading, but without TLS a determined sniffer on the same network could still capture traffic. Use --https for anything sensitive.
• Self-signed TLS is real encryption but not CA-trusted — expect a one-time "not private" warning on the phone (or install your own CA root; see above).
• Single-machine, single-uploader scope. One blocking server; it's a personal utility, not an audited product.
• Port 8000 must be free (--port to change).

Earlier version

The repo also keeps photodrop.py — the original quick pass. Same tool, same flow, but it loaded its UI (Tailwind, icons, a font) and the QR image from CDNs (so it needed internet and sent the LAN URL to a third party) and ran open over HTTP with no token. photodrop_secure.py supersedes it; run the secure one — photodrop.py is kept only for reference.

Provenance

No datasets, no model, no training, no external accounts, no secrets — a self-contained stdlib script plus one small pure-python dependency (segno, for the offline QR). Built with an LLM, Jan 2026.