Documentation
P-Sphere Docs
How the app works, how to get started, and what to expect.
Overview
P-Sphere is a self-hosted photo library. The goal is to give you everything a cloud photo service offers — backup, search, albums, AI — without your photos ever leaving devices you control.
Right now, the Android app is working. It backs up your camera roll and syncs photos between devices on your local Wi-Fi with no server required. The rest of the platform is in active development.
What works today:
- Automatic camera roll backup to another device on your network
- P2P sync between Android phones on the same Wi-Fi
- Hash-based delta sync — only new photos transfer
- Background sync via Android WorkManager
Installing the app
P-Sphere is not on the Google Play Store yet. You install it by sideloading the APK file directly. Full step-by-step instructions are on the download page. In short:
- Download the APK from the releases page
- Enable "Install unknown apps" for your browser or file manager
- Tap the APK file and confirm installation
- Open P-Sphere and grant the required permissions
Permissions
P-Sphere requests two permissions:
- Photos / Media access — Required. Needed to read your camera roll for backup and sync.
- Notifications — Optional. Used to show sync progress and completion notices.
P-Sphere does not request location, contacts, microphone, or camera permissions. No data is sent to any external server.
Photo backup
When another P-Sphere device is on your network — currently another phone, eventually the core server — the app backs up your camera roll automatically in the background.
- Runs on a configurable schedule, default every 6 hours
- Only runs on Wi-Fi by default; mobile data can be enabled in settings
- Skips backup when battery is low
- Can be triggered manually from the app at any time
P2P sync
P2P mode lets two Android phones running P-Sphere sync photos directly over the same Wi-Fi network. No server or internet connection is needed.
How discovery works
P-Sphere uses Android's Network Service Discovery (NSD / mDNS) to broadcast its presence on the local network. Any other P-Sphere device on the same network appears in the device list automatically. No IP addresses or pairing codes are required.
How transfer works
Once you initiate a sync, P-Sphere exchanges a list of SHA-256 photo hashes with the other device, identifies which photos each device is missing, then transfers only those files over a direct TCP connection. The first sync of a large library takes time; every sync after that takes seconds.
Security
Connections are local-network only and require explicit authorization on both devices the first time. P-Sphere does not expose any port to the internet.
Delta sync
Every photo is identified by its SHA-256 content hash, not its filename or date. This means renaming or moving a photo doesn't cause it to re-upload, duplicates are detected and skipped automatically, and if a photo already exists on the receiving device under a different name, it won't transfer again. Repeated syncs stay fast even for large libraries.
Core server
In development
The core server is a self-hosted Node.js backend that acts as the permanent home for your photo library. Once available, it will store photos on disk and serve them to connected devices, run the AI pipeline in the background, serve the web dashboard, and manage device tokens and sync state.
You'll be able to run it on any always-on machine: a spare PC, a Raspberry Pi, a NAS, or a small VPS.
Tech stack: Node.js 20, Express, PostgreSQL, Redis, BullMQ.
Web dashboard
In development
The web dashboard is a React app served by the core server. You'll be able to access it from any browser on your local network. Planned features include a photo timeline, album management, AI search, face cluster labelling, and sync status.
AI features
In development
All AI in P-Sphere runs locally. Nothing is sent to an external API.
- Natural language search — powered by a local LLM via Ollama, LM Studio, or any OpenAI-compatible endpoint you run yourself
- Smart albums — clusters your photos into Trip, People, Pets, and Place albums
- Face detection — runs ONNX models offline, groups similar faces across your library
- Object tagging — identifies objects and scenes for richer search
FAQ
Does P-Sphere work without the internet?
Yes. The Android app and P2P sync work entirely over your local Wi-Fi network. No internet connection is required for any currently available feature.
Do I need an account?
Not currently. The Android app works without any account or registration. When the core server is released, you'll create a local account on your own server — there's no central account system.
Is my data safe?
P-Sphere stores photos on the devices involved in the sync. Data safety depends on the health of those devices. We strongly recommend keeping independent backups — P-Sphere is alpha software and data loss is possible.
Can multiple people use P-Sphere on the same network?
Each phone runs its own independent instance. Multi-user support with shared libraries and per-user accounts is planned for the core server release.
Is the source code available?
P-Sphere is currently proprietary software. License terms are on the License page. We may release under an open-source license as the project matures.
How do I report a bug?
Open an issue on the GitHub repository. Include your Android version, the app version, and a description of what happened.
Privacy
P-Sphere is designed so your photos never leave your devices. No external servers are involved in any currently available feature, the app collects no analytics or telemetry, no crash reports are sent automatically, and P2P sync happens directly between your devices over your local network. No account means nothing to track you with.
When the core server is released, that server will also be self-hosted on hardware you own. We will never operate cloud infrastructure on your behalf or have access to your photos.