How it is built.
The long version, for people who want to read before they run. Everything here is in the repository, and every number links to where it was measured.
Two halves. The one that touches your bytes never touches the network.
A Python API owns accounts, permissions, versions, sharing and search. A C++ engine owns hashing, storage and deduplication. Only the API can talk to the engine, over an internal Docker network. Click a box.
Storage: content-addressed, crash-safe, verified
- Name by content. A file is stored at
objects/<first two hex>/<sha256>. Same bytes under any name: one copy. Reference counting lives in PostgreSQL: an object is deleted only when nothing references it, by a trash purge or the opt-in garbage collector. - Write aside, flush, rename. Bytes go to a unique temporary name, are flushed to the disk, renamed into place, and the folder entry is flushed. A power cut leaves the old state or the complete new one, never half.
- Verify before trusting. A put re-hashes the source before moving it (a wrong hash is refused and the source is left alone), and a get re-hashes the stored bytes, so silent disk damage is caught instead of served.
- Confine paths. The engine resolves every path (
..and symlinks included) and refuses anything outside the storage root, and anything insideobjects/unless it is a read.
How it is tested
- 91 engine tests. They include forked processes killed (
_exit) at named points mid-write, simulated full-disk failures, and 16 writers of the same object at once. - Sanitizers. The engine suite also passes under AddressSanitizer, UndefinedBehaviorSanitizer and ThreadSanitizer.
- Fuzzing. A libFuzzer target feeds the JSON parser and path confinement; 660,000 executions ran clean.
- 384 server tests on SQLite by default, and the whole suite can run against a real PostgreSQL (
TEST_DATABASE_URL), using a fake engine that mirrors the real one.
The engine's request parser is a strict flat-object JSON reader (it rejects nesting, duplicate keys, bad escapes and trailing garbage). It handles up to 32 connections at once with a read timeout. docs/storage.md
Performance, with the method
The benchmark script reproduces the line speeds from Gizmodo's and Cloudwards' published Google Drive tests with a token-bucket paced client, and reports the share of the line each transfer used. It runs on the server itself over localhost.
| Test (line speed) | Drive, published | Choud, first run | Choud, after fixes |
|---|---|---|---|
| 500 MB up, 19.69 Mbps | 3:33 (95%) | 3:43 (90.7%) | 3:31 (96.3%) |
| 500 MB down, 187.95 Mbps | 0:24 (89%) | 0:24 (85.6%) | 0:24 (87.8%) |
| 5 GB, 1,045 files, up, 100 Mbps | 7:15 (92%) | 8:54 (74.9%) | 7:57 (83.8%) |
| 5 GB, 1,045 files, down, 100 Mbps | 7:18 (91%) | 6:41 (99.6%) | 7:01 (94.9%) |
What changed between the two Choud columns
- The two upload endpoints were
asyncbut made blocking engine and database calls, so one upload waiting on the disk stalled every other request. The blocking work now runs in worker threads. - Clients send up to three 5 MiB chunks at once.
- The engine no longer reads an uploaded file twice (the backend tells it the engine just hashed it).
- Downloads use a hard link into staging instead of a full copy.
The 5 GB download came out slower on the second run with nothing slower in its path: one run each, so it is most likely noise, and it is reported rather than hidden.
API latency, server-side (first run, before the fixes)
| Call | p50 | p95 |
|---|---|---|
| health check | 15.9 ms | 30.7 ms |
| upload 100 KB | 66.9 ms | 89.5 ms |
| list ~500 files | 133 ms | 217 ms |
| search by name | 23.3 ms | 36.3 ms |
| library index, unchanged (304) | 13.1 ms | 15.8 ms |
| 24 thumbnails, 24 requests | 151 ms | 167 ms |
| 24 thumbnails, one batch | 14.9 ms | 21.9 ms |
Why the thousand-small-files upload is slower than Drive: each small upload costs about 65 ms of server work, including the flush to disk that makes it crash-safe. That is a deliberate trade.
Choud: one run each on the author's home server (Linux Mint, 4 CPUs, v0.5.1), client on the same machine. Drive: Gizmodo's and Cloudwards' published runs, each on its own network. Indicative, not a verdict. Repeat it yourself:
python3 -m venv /tmp/bench && /tmp/bench/bin/pip install httpx pillow CHOUD_PASSWORD=... /tmp/bench/bin/python scripts/benchmark.py --url http://localhost --email you@example.com all
docs/benchmarks.md has every table and source, and the raw output is kept as evidence.
Security model
- Two doors. The private door serves the app and the API. A second door serves only
/s/*share links, and a header it stamps is stripped on the private door. A kill switch pauses every public link at once. - Passwords and tokens. Argon2id hashes, short-lived access tokens with refresh tokens, optional TOTP two-factor login. The share-unlock cookie is signed with a key derived (HKDF) from the JWT secret, never the secret itself.
- Rate limits on login, registration, refresh, uploads, downloads, search, thumbnails, share views and unlock attempts, per client IP.
- Request guards. A body-size limit (413 before the body is read), security headers,
no-storeon auth responses, and CORS off unless you list origins. - Vault. Sealed in the browser: the server stores ciphertext, and still sees how many sealed files there are, their sizes and dates.
- Secrets.
scripts/setup.shgenerates strong random ones; production refuses to start with placeholders.
What it has not had
- No independent security audit.
- No weeks of use on many real phones.
- No multi-machine or multi-tenant hardening: it is built for one household on one machine.
Found something? Report it privately: SECURITY.md. Details: docs/security.md.
The repo, in one screen
server/ FastAPI app, migrations, tests engine/ C++17 storage engine, tests, fuzz target web/ React + TypeScript web app android/ Kotlin app (views built in code) client/ Python desktop sync client scripts/ setup, deploy, backup, restore, benchmark docs/ architecture, storage, security, api, deployment site/ this website (plain HTML, CSS, JS)
Run it for real: scripts/setup.sh then scripts/deploy.sh. Develop on it: make dev, then open http://localhost:8080. Verify: make test, make engine-test, make lint.
Read next
- The guide
- Architecture and non-goals
- HTTP API reference
- How desktop sync resolves conflicts
- Contributing and the roadmap
Questions
Will it run on Windows or a Mac?
To try it, yes: make dev with Docker Desktop. To keep your files, use Linux: Docker Desktop's virtual disk makes every write slow.
Can I reach it away from home?
Over Tailscale. Public share links work from anywhere with scripts/enable-public-links.sh, through the second door.
What if the disk dies?
Nightly verified backups with restore scripts. Point them at a second disk or machine.
Can I import from Google Drive?
No importer yet. Export with Google Takeout and upload the folder.