Self-hosted photo server for Windows: an iPhone sends new photos over home Wi-Fi through Apple Shortcuts, no app needed, and an optional native Android app does the same, with a verified-hash cleanup and a gallery.
For detailed usage, see How It Works, Performance, Limits, and Full API Reference.
- Runtime Prerequisites: Python 3.10 or newer (standard library only). Optional:
pip install pillow pillow-heiffor HEIC thumbnails and camera details. - Canonical Regression Shield Gate:
python -m unittest discover -s tests -t . - Try it now (from this folder): double-click
Harbor.pywand press Start server, then Open photo browser (or double-clickOpen Photo Browser.url). From a console:The first time, choose Sign in with a key instead and paste the main key shown in the window (or printed bypython -m photo_harbor serve
serve), then set a password under Setup → My account. When Windows Firewall asks, allow Python on Private networks so the iPhone can reach it.
| Role | Command |
|---|---|
| Status, task and gates | python aikit.py status photo-harbor |
| Phase 4: every gate | python aikit.py check photo-harbor |
| Repair memory and map, then check | python aikit.py fix photo-harbor |
| Resume an interrupted task | python aikit.py resume photo-harbor |
photo-harbor/
├── .aikit/ <- project memory: record, ledger, decisions, state machines
├── .gitignore
├── Harbor.pyw <- double-click: the Harbor window (Start/Stop server)
├── LICENSE <- Aegean License 1.1 (AL-1.1): free personal use
├── LICENSES/ <- REUSE license texts
├── REUSE.toml <- Machine-readable SPDX metadata
├── Open Photo Browser.url <- double-click: the gallery at http://localhost:8642
├── README.md
├── assets/
├── android/ <- native Android client, build.py and install page source
├── COMMERCIAL.md
├── docs/ <- extended documentation
│ ├── API.md <- HTTP API reference
│ ├── HOW_IT_WORKS.md <- detailed feature descriptions
│ ├── LIMITS.md <- known limitations
│ ├── PERFORMANCE.md <- performance benchmarks
│ └── STRUCTURE.md <- full project structure
├── photo_harbor/
│ ├── __init__.py <- package version
│ ├── __main__.py <- `python -m photo_harbor` commands
│ ├── app.py <- wires storage, APIs and the web page into routes
│ ├── atomic_file.py <- temp + fsync + replace, and exclusive placement
│ ├── accounts.py <- password hashes, sessions, wrong-password brake
│ ├── activity_api.py <- read-only recent journal events
│ ├── albums.py <- personal albums and favorites; no files move
│ ├── albums_api.py <- albums and favorites API
│ ├── archive.py <- per-person hidden photos; no files move
│ ├── archive_api.py <- archive/restore API
│ ├── auth.py <- home-network check; key/session sign-in
│ ├── autostart.py <- start with Windows (per-user Run key)
│ ├── backup.py <- mirror to a second drive, daily thread
│ ├── backup_api.py <- owner-only backup status
│ ├── body_readers.py <- Content-Length and chunked request bodies
│ ├── catalog.py <- index of stored originals by SHA-256
│ ├── copies.py <- whose folder holds which photo, and where
│ ├── config.py <- settings file with the library key
│ ├── control_panel.py <- the Harbor window (tkinter)
│ ├── database.py <- SQLite file and its format version
│ ├── details.py <- file facts and optional EXIF
│ ├── downloads.py <- one-off stored ZIPs with size limits and tokens
│ ├── downloads_api.py <- prepare and serve downloads
│ ├── errors.py <- the Error/Why/Fix triad
│ ├── exif_dates.py <- capture date from EXIF, when Pillow is installed
│ ├── folders_api.py <- read-only person/year/month folder tree
│ ├── geo.py <- GPS point from EXIF, when Pillow is installed
│ ├── http_server.py <- HTTP handling, byte ranges, security headers
│ ├── importer.py <- copy photos in from disk, skip-list
│ ├── journal.py <- uploads, finished syncs, photos reported missing, scans
│ ├── layout.py <- person folders, guide file, old-layout migration
│ ├── library_api.py <- status, outline, filtered photo list, originals, previews
│ ├── messages.py <- Request and Reply values, JSON body reading, Range parsing
│ ├── naming.py <- safe file names, month folders, media types
│ ├── phash.py <- optional perceptual difference hash
│ ├── pillow_support.py <- optional Pillow and HEIC loading
│ ├── profiles.py <- people, folder ids and keys
│ ├── profiles_api.py <- list, add, rename and re-key people
│ ├── records.py <- frozen value objects
│ ├── router.py <- method + path routing
│ ├── runner.py <- start and stop a server in the background
│ ├── scan.py <- keeping up with File Explorer; weekly file check
│ ├── selection.py <- bulk hash parsing and validation
│ ├── setup_api.py <- address and key for the Setup tab
│ ├── sidecar.py <- read-only JSON/XMP sidecar ZIPs
│ ├── similar_api.py <- read-only perceptual-hash groups and scan
│ ├── similar_builder.py <- background cached-group rebuild
│ ├── store.py <- hash-verified ingest and re-verification
│ ├── sync_api.py <- the endpoints the Shortcuts call
│ ├── tags.py <- personal tags and their photo marks
│ ├── tags_api.py <- list, create, rename, delete and mark tags
│ ├── thumbs.py <- optional Pillow previews, background warmer, cache pruning
│ ├── trash.py <- move a copy aside, restore through ingest, delete forever
│ ├── trash_api.py <- list, move, restore, delete and empty the trash
│ └── web/ <- gallery, icons, PWA sw.js and android install page
└── tests/
├── __init__.py
├── library_fixture.py <- a throwaway library for tests
├── test_activity.py <- recent journal events and visibility
├── test_albums.py <- personal albums, favorites and migration
├── test_archive.py <- per-person archive and migration
├── test_cameras.py <- camera EXIF and filtering
├── test_dates.py <- date-range narrowing
├── test_details.py <- file facts and optional EXIF
├── test_downloads.py <- ZIP names, tokens and expiry
├── test_http.py <- server over real socket
├── test_folder_view.py <- read-only folder tree and visibility
├── test_folders.py
├── test_hashes.py <- select matching across filters
├── test_lenses.py <- lens filtering
├── test_messages.py
├── test_naming.py
├── test_parts.py
├── test_places.py <- GPS extraction and filtering
├── test_profiles.py
├── test_runner.py
├── test_scale.py
├── test_records.py
├── test_search.py <- multi-word search
├── test_sidecar.py <- JSON/XMP sidecar ZIPs
├── test_similar.py <- perceptual hashes and grouping
├── test_sort.py <- newest, oldest, largest, smallest order
├── test_storage.py <- whole-library and per-person storage totals
├── test_store.py
├── test_tags.py <- personal tags and migration
└── test_trash.py <- move, restore, delete and migration
Library layout: <Person>\<YYYY>\<YYYY-MM>\<original name> holds the originals untouched, next to READ ME - Harbor.txt. Libraries from earlier versions (photos\...) are moved into this layout file by file the first time the server starts. The hidden .harbor\ holds config.json, catalog.sqlite3 (format 13; an older catalog is upgraded in place after a copy to catalog.sqlite3.v<N>.bak), incoming\, thumbs\ and trash\.
See Performance for detailed benchmarks.
See Limits for known limitations.
Free for personal use under the Aegean License 1.1 (AL-1.1); see LICENSE. Any commercial use needs the Aegean Commercial License 1.0 (ACL-1.0); see COMMERCIAL.md.
AI-Generated Brand Artwork. The banner and logo are AI-generated brand assets. They are illustrative and may not literally depict every feature or the full project scope.
commit c73fa38 · 2026-11-03 · viewport 1440x900 · first-run gate; gallery views withheld (personal library, no demo mode — ADR-030)

