Server Components
bae-desktop is the full system. bae-proxy is its zero-knowledge subset for untrusted cloud hosting.
bae-desktop
Section titled “bae-desktop”bae-desktop (GUI or --headless) is a complete server. When a cloud home is configured, it serves cloud home proxy routes alongside Subsonic, so followers and share link recipients connect directly to it.
What it serves
Section titled “What it serves”- Full Subsonic API (browse, search, stream with decryption)
- 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-desktop --headless runs without the GUI. It starts the Subsonic API server, 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-desktop --headless on any machine with access to your library. A typical setup:
- Run
bae-desktop --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.
Subsonic compatibility
Section titled “Subsonic compatibility”bae-desktop implements the Subsonic API. Any Subsonic-compatible client (DSub, Symfonium, play:Sub, Submariner, etc.) can connect to it and browse, search, and stream your library. No special client needed.
bae-proxy
Section titled “bae-proxy”bae-proxy is a zero-knowledge subset of bae-desktop 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 (bae-desktop, 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”| bae-desktop | bae-proxy | |
|---|---|---|
| Subsonic API | Yes | No |
| 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 |