Self-Hosted Setup

With the self-hosted plan, your photos live on hardware YOU control — a Raspberry Pi, NAS, mini-PC, or any computer with spare disk. We host the family UI, you host the bytes.

How it works

  1. You install a small program — the agent — on your device.
  2. The agent makes one outbound WebSocket connection to family-heirloom.org. No port forwarding, no dynamic DNS, no public IP required.
  3. When your family uploads a photo, we route the bytes through that connection to your agent, which writes them to disk.
  4. When someone views a photo, the agent streams the bytes back through the connection to us, then on to the browser.
⚠️ Your device must stay online 24/7.
If your device is off — no one in your family can view or upload photos. They'll see a "device offline" screen instead of the photo grid. Plan accordingly: UPS recommended, reliable internet recommended.

Bandwidth + overage

Photo bytes flowing from your device, through our VM, to a family member's browser count toward bandwidth. Each family gets 1 TB per month included. Beyond that we charge $1.50 per TB, billed as a line item on your next regular subscription invoice — no surprise charges, no separate bills.

Cloudflare aggressively caches photos at the edge so repeat views (the common case) are free for everyone. Typical family usage runs well under 100 GB/month. You'd have to be serving many TB of fresh, never-seen-before photos to hit the overage line. The admin panel and your family page both show your current month's usage so there are no surprises.

Hosted plans (the ones with our managed storage) don't have this overage at all — those bytes go direct from Cloudflare to the browser without touching our infrastructure, so we don't meter them.

Hardware recommendations

  • Minimum: any computer running Linux, macOS, or Windows, with enough disk for your archive.
  • Recommended: Raspberry Pi 4 (8 GB) or better, NAS (Synology, QNAP, Unraid), or a small x86 box like an Intel NUC. UPS for power blips. Wired ethernet preferred over wifi.
  • Disk + backup: plan for 2-3× the photos you have today. Run RAID-1 or rsync to an external drive for local redundancy. For off-site backup, copy the storage dir to your cloud of choice (rclone to B2/S3/etc.) — we recommend a weekly cron. Self-hosters own their backup story.

Step-by-step

1. Pick your allocation

In the setup wizard you'll choose how much disk to make available — your storage cap. Uploads stop at that number. You can resize later in the family page, but only upward unless current usage allows shrinking.

2. Install the agent

Windows and macOS: the setup wizard gives you a one-click installer — download it, double-click, and it installs the agent, pairs this device, and runs it as a background service. No terminal. (The download is personalized: on Windows the pairing code is baked into the file so you don't type anything.) See the note below about the first-run security warning while these installers are unsigned.

Linux / Docker / advanced: we also provide static binaries and copy-paste install commands. Download from family-heirloom.org/releases.

Linux (systemd)

# Download
curl -fsSLo familyheirloom-agent \
  https://family-heirloom.org/releases/familyheirloom-agent-linux-amd64
chmod +x familyheirloom-agent
sudo mv familyheirloom-agent /usr/local/bin/

# Pair (one-time, with the code from the wizard)
familyheirloom-agent pair ABC1234

# Create a systemd unit
sudo tee /etc/systemd/system/familyheirloom-agent.service <<'EOF'
[Unit]
Description=Family Heirloom node agent
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/familyheirloom-agent run
Restart=on-failure
RestartSec=10
User=fh-agent

[Install]
WantedBy=multi-user.target
EOF

# Create the user that runs the agent
sudo useradd -r -s /bin/false fh-agent

# Enable + start
sudo systemctl daemon-reload
sudo systemctl enable --now familyheirloom-agent

# Check status
systemctl status familyheirloom-agent
journalctl -u familyheirloom-agent -f

Docker (Synology / Unraid / Portainer)

docker volume create fh-storage
docker volume create fh-config

# Pair (one-time)
docker run --rm \
  -v fh-config:/config \
  -e FH_CONFIG=/config/agent.json \
  familyheirloom/agent:latest pair ABC1234

# Run continuously
docker run -d --name familyheirloom-agent \
  -v fh-storage:/storage \
  -v fh-config:/config \
  -e FH_STORAGE_DIR=/storage \
  -e FH_CONFIG=/config/agent.json \
  --restart unless-stopped \
  familyheirloom/agent:latest run

macOS (launchd)

# Download
curl -fsSLo familyheirloom-agent \
  https://family-heirloom.org/releases/familyheirloom-agent-darwin-arm64
chmod +x familyheirloom-agent
mv familyheirloom-agent /usr/local/bin/

# Pair
familyheirloom-agent pair ABC1234

# Create a LaunchAgent plist at
#   ~/Library/LaunchAgents/com.familyheirloom.agent.plist
# (template available in the GitHub repo). Then:
launchctl load ~/Library/LaunchAgents/com.familyheirloom.agent.plist

Windows (Service)

# In PowerShell
Invoke-WebRequest `
  -Uri https://family-heirloom.org/releases/familyheirloom-agent-windows-amd64.exe `
  -OutFile C:\fh\familyheirloom-agent.exe

C:\fh\familyheirloom-agent.exe pair ABC1234

# Install as a service using nssm (https://nssm.cc):
nssm install FamilyHeirloomAgent C:\fh\familyheirloom-agent.exe run
nssm start FamilyHeirloomAgent

3. Pair

The pairing code is 7 characters and lasts 10 minutes. Type it into the agent and it'll exchange the code for a long-lived device token, stored in the agent's config file. After that, the agent reconnects on its own across reboots.

4. Set up your own backup

With self-hosted you own the backup story. Belt-and-suspenders options that pair well with the agent:

  • RAID-1 on the storage device for live mirror — survives a single disk failure.
  • Weekly rclone sync of the storage dir to a separate cloud bucket (Backblaze B2, AWS S3, Wasabi).
  • Daily rsync to an external drive plugged into the same machine for quick recoveries.

A note on the installer warnings

The Windows and macOS installers are not code-signed yet. Code-signing certificates are an annual cost we're deferring until closer to a public launch, so for now your OS will show a scary-looking warning the first time you run the installer. It's expected — here's how to get past it, and why it's safe.

Windows (SmartScreen)

You'll see a blue box: "Windows protected your PC." Click More info, then Run anyway. (If you don't see "More info", the publisher just hasn't built up SmartScreen reputation yet — that comes with a signed build.)

macOS (Gatekeeper)

macOS may say the app is "from an unidentified developer". Instead of double-clicking, right-click (or Control-click) the app → Open, then click Open in the dialog. You only need to do this once. If that's blocked, you can clear the quarantine flag from Terminal:

xattr -dr com.apple.quarantine "/Volumes/Family Heirloom/Family Heirloom Installer.app"

Is it safe?

The warnings mean "this software isn't signed", not "this software is malicious". The binaries are built by our public CI from the source in this repository, and every download's integrity is checked against a SHA-256 hash recorded in the release manifest. If you'd rather skip installers entirely, use the Linux/manual binary route above — the raw binaries trip no such warnings. We'll switch to signed installers (Apple notarization + a Windows certificate) before general availability; the build pipeline is already set up for it.

Keeping the agent updated

When we ship a newer agent, your family's storage page shows an "Update available" badge next to the device. The owner clicks Update now and we push the update to your device over its existing connection — it verifies the download, swaps itself, and restarts on the new version in a few seconds. No re-download, no reinstall.

Nothing updates on its own — the agent only updates when an owner asks it to. Power users can also run familyheirloom-agent update on the device to pull the latest build manually (restart the service afterward).

Operations cheat sheet

# Systemd
systemctl status familyheirloom-agent
journalctl -u familyheirloom-agent -n 50
sudo systemctl restart familyheirloom-agent

# Docker
docker logs familyheirloom-agent --tail 50
docker restart familyheirloom-agent

# Agent self-check (any platform)
familyheirloom-agent status

Troubleshooting

"Device offline" screen shows up
Your agent isn't connected. Check the service is running, internet is reachable, no firewall is blocking outbound 443, and the agent logs for a specific error.
"Pairing failed: invalid pairing code"
The code expired (10-minute lifetime) or was typed wrong. Refresh the wizard and try again.
Uploads succeed but disappear
Almost always a permissions issue on the storage directory (the agent user can't write). Check the agent logs for "permission denied" and fix the dir ownership.

Security model

  • Photos never touch our object storage. Bytes flow through the WebSocket but aren't persisted on our servers.
  • The device token is stored hashed on our side (SHA-256). A DB leak doesn't compromise device control.
  • You can revoke the token at any time from the family page ("Unpair device") — the old agent is immediately disconnected and can't reconnect without a fresh pairing.

Stuck? Email [email protected] with your family ID and the last 50 lines of agent logs.