Server Components
The desktop app is the full system. bae-proxy is its zero-knowledge subset for untrusted cloud hosting.
Desktop app
Section titled “Desktop app”The desktop app (GUI or --headless) is a complete server. When a cloud home is configured, it serves cloud home proxy routes so followers and share link recipients connect directly to it.
What it serves
Section titled “What it serves”- Cloud home proxy routes (
/cloud/*,/share/*) for followers and share links - Library images
- Sync loop (pulls and pushes changesets to the cloud home)
- Library management (import, edit, delete)
Headless mode
Section titled “Headless mode”bae --headless runs without the GUI. It starts the cloud home proxy routes and sync loop, then runs until stopped with Ctrl+C.
This is for running bae on a home server, NAS, or VPS.
CLI flags
Section titled “CLI flags”| Flag | Purpose |
|---|---|
--headless | Run without the GUI |
--port | Port to listen on |
--bind | Address to bind to (e.g., 0.0.0.0) |
Deployment
Section titled “Deployment”Run bae --headless on any machine with access to your library. A typical setup:
- Run
bae --headlesson a VPS or home server - Point a domain at it (reverse proxy with nginx, Caddy, etc.)
- The server syncs from your cloud home and serves the library
This gives you a public URL for share links and follow connections.
For users without a static IP or custom domain, options include Tailscale Funnel, ngrok, Cloudflare Tunnel, or UPnP port forwarding.
bae-proxy
Section titled “bae-proxy”bae-proxy is a zero-knowledge subset of the desktop app for untrusted cloud hosting. It proxies encrypted blobs between clients and S3 storage. It never has keys, never decrypts. All decryption happens on the client (the desktop app, bae-web, or bae-mobile).
How it works
Section titled “How it works”bae-proxy reads a YAML registry file that maps hostnames to S3 prefixes. When a request comes in, it looks up the Host header, finds the corresponding S3 location, and proxies the request.
This registry is generated by the bae-cloud control plane. Each library gets its own hostname, scoped to its own S3 prefix. Libraries cannot access each other’s data.
Multi-tenant routing
Section titled “Multi-tenant routing”A single bae-proxy instance handles many libraries. Routing is by Host header — each library has its own subdomain. The proxy scopes all S3 operations to the library’s prefix, enforcing isolation.
What it serves
Section titled “What it serves”- Encrypted release files (audio, images, etc.)
- Encrypted database snapshots and sync changesets
- Encrypted library images
- Share link data (bae-web fetches encrypted share data through bae-proxy, decrypts in the browser)
- Cloud home data for follow connections
What it does not do
Section titled “What it does not do”bae-proxy has no knowledge of your library contents, metadata, or encryption keys. It cannot read, search, or index your music. It is a storage proxy, nothing more.
Comparison
Section titled “Comparison”| Desktop app | bae-proxy | |
|---|---|---|
| Cloud home proxy | Yes | Yes |
| Share links | Yes | Yes (via bae-web) |
| Follow connections | Yes | Yes |
| Decryption | Yes (has keys) | No (zero-knowledge) |
| Multi-tenant | No (single library) | Yes (Host header routing) |
| Typical deployment | Home server, NAS, VPS you trust | bae cloud, untrusted VPS |