🗄️ hoardarr

A full self-hostable cloud stack for media of any kind.

Leverage S3 object storage at its real strength — multi-cloud, multi-region, multi-cluster, hybrid — behind one fast access layer and one visual face.

---

Note

This is a proof of concept — and the possibilities are essentially endless. What you see here is the smallest complete, working slice: one storage node, one library, one player, on a single Proxmox host. But the stack underneath is built for distributed, multi-cloud object storage. This POC is the seed of a full self-hostable cloud for media of any kind — movies, TV, music, books, audiobooks, anything you can put in a bucket.

💡 The idea in one picture

flowchart TB
    subgraph faces["🖥️  Visual layer — watch anywhere"]
        J1["Jellyfin + GPU<br/>(living room)"]
        J2["Jellyfin + GPU<br/>(laptop)"]
        J3["Jellyfin + GPU<br/>(another site)"]
    end

    subgraph access["🧭  Access layer — one library, cached"]
        JFS["JuiceFS<br/>POSIX mount /mnt/hoard<br/>+ local memory/disk cache"]
        META["Postgres<br/>file → chunk index"]
    end

    subgraph storage["🗄️  Object storage — offline-first, multi-master"]
        G1["Garage node A"]
        G2["Garage node B<br/>(other region)"]
        G3["Garage node C<br/>(other cloud)"]
    end

    J1 & J2 & J3 --> JFS
    JFS <--> META
    JFS --> G1 & G2 & G3
    G1 <-.multi-master sync.-> G2
    G2 <-.multi-master sync.-> G3

    classDef s fill:#1f6feb22,stroke:#1f6feb;
    classDef a fill:#8957e522,stroke:#8957e5;
    classDef f fill:#2ea04322,stroke:#2ea043;
    class G1,G2,G3 s
    class JFS,META a
    class J1,J2,J3 f

Store once, anywhere. Access everywhere. Watch on any screen.

🧱 The stack, in three layers

Layer	Component	Its strength
🗄️ Storage	Garage	Offline-first, multi-master S3 object groups that span clouds / regions / clusters and keep serving when links drop.
🧭 Access	JuiceFS	A universal POSIX access layer over all your storage, with a memory + disk cache so hot content is served at local speed.
🖥️ Visual	Jellyfin	The visual layer — displays and streams the content, transcoding on the GPU where it's watched.

Tip

A read of /mnt/hoard/movies/… becomes: JuiceFS asks Postgres which chunks, fetches those chunks as S3 objects from Garage, and caches them locally so the next read is instant. The first watch pulls from object storage; every watch after is local-disk fast.

✨ Why it's compelling

• 🌐 Object storage at its strength — multi-cloud, multi-region, multi-cluster, hybrid. Not one central bucket you're tethered to.
• 🔁 Store the library once — not N copies across N players.
• ⚡ Feels local, lives distributed — the JuiceFS cache hides the network.
• 🎮 GPU transcoding per player — scales with viewers, not library size.
• 🧩 Runs on plain Proxmox LXCs — no Kubernetes required for the core path.
• 🔓 Self-hostable, open components — single binaries, systemd, no lock-in.

🚀 Quickstart

This repo is docs + sanitized config templates, capturing a build that was stood up and verified end-to-end (real object reads from the store, real VAAPI transcode on the player).

Important

Every value in <ANGLE_BRACKETS> is a placeholder you replace with your own. Nothing here contains real hostnames, IPs, or secrets — see SECURITY.md. A secret-scanning linter + pre-commit hook keep it that way.

📚 Read in this order

#	Doc	What it gives you
1	💡 rationale.md	The idea, the origin, who it's for, why it's a POC, the roadmap
2	🏗️ architecture.md	What each piece does and why (technical deep-dive)
3	🧰 install-proxmox.md	Build it on Proxmox, step by step
4	➕ add-a-player.md	Runbook: add another Jellyfin / GPU device
5	🛠️ operations.md	Grow storage, back up metadata, every failure mode
6	🔌 platform-integration.md	Run it on an identity-overlay + secrets platform
7	🗺️ ROADMAP.md	Where this is going

📁 Repo layout

hoardarr/
├── README.md                 you are here
├── SECURITY.md               public-repo secrets policy
├── ROADMAP.md                the forward plan
├── docs/
│   ├── rationale.md          the idea & the why
│   ├── architecture.md       the how & the trade-offs
│   ├── install-proxmox.md    step-by-step build
│   ├── add-a-player.md       add-a-device runbook
│   ├── operations.md         run it / fix it
│   └── platform-integration.md   overlay + secrets platform
├── templates/                sanitized configs (placeholders only)
│   ├── garage/               object store: config + layout
│   ├── juicefs/              access layer: mount unit + format
│   ├── jellyfin/             player: encoding + systemd
│   └── proxmox/              LXC GPU passthrough
└── scripts/
    └── lint-secrets.sh       secret / private-info scanner

🔭 Where this goes next

timeline
    title hoardarr roadmap
    Now (POC)        : Single Garage node : JuiceFS + Jellyfin : Proxmox LXC : GPU transcode
    Next             : Multi-platform (Docker / Nomad / cloud) : Custom tunnel agent for cross-firewall, cross-cloud links
    Then             : Redundancy on demand : Metadata HA
    Vision           : Multi-region / multi-cluster tiered storage : One library, any node, anywhere

Note

Coming soon: custom-built tunnel components to bridge firewalls and clouds — identity-based, unblockable connectivity so Garage replicas, JuiceFS clients, and players find each other across any network without opening public ports. That is what turns this single-LAN POC into a true distributed, self-hosted media cloud.

🔗 schmutz (the tunnel agent) — a device enrollment agent for zero-trust overlay networks. Open source: KontangoOSS/schmutz. See ROADMAP.md and platform-integration.md.

🔒 Security

Public repo. Zero secrets, by construction. All sensitive values are placeholders; a linter (scripts/lint-secrets.sh) + pre-commit hook block private IPs, keys, DSNs, and internal names from ever landing here. See SECURITY.md.

📄 License

MIT — © 2026 Kontango.