How to set up Hearth Chat

Hearth is your own private group chat — text, photos, video, reactions, voice/video calls and push notifications, all running on your own SparkBox. No accounts, no company in the middle, and no upload caps because your media lives on your pool. It's a Tom Spark exclusive for Backers. This guide covers how to turn it on, share your join code, choose how it's reached, and install it on your phone.

1. What is Hearth Chat?

Hearth is a self-hosted group chat that lives entirely on your SparkBox. Think of your family or friends group chat — but it runs on hardware you own, so nobody else can read it, mine it for ads, or shut it down. There are no accounts: everyone joins with one shared code and picks a display name. Because the files live on your storage pool, there's no "upgrade for more space" — drop a 4 GB video and it just works.

Hearth is exclusive to SparkBox Backers. It's a thank-you for funding the project. Become a Backer →

2. Turn it on (Backer-only)

Open your SparkBox dashboard in a browser — it's at https://your-box-ip:8443 (the same address you set up SparkBox with; if you're not sure of the IP, it's the one shown when you installed). Then:

1. Open the Apps tab.
2. Find Hearth Chat (it has a gold ✦ Tom Spark badge and a BETA tag).
3. Click Install / Enable.

If you're not a Backer yet, the dashboard will tell you and link you to back the project — Hearth is Backer/Legend only. Enabling takes under a minute while it pulls the app and starts it. SparkBox automatically generates a unique join code for your box at this point — you never share a default with anyone else.

3. Your join code & inviting people

Your join code is the only key to your Hearth — treat it like a password. Anyone with it can join, so only share it with people you want in.

The easy way to invite someone is the Invite people button inside Hearth (in the left sidebar). It copies a link like:

https://your-hearth-address/?join=your-code

Send that link to whoever you want in. They open it, the code is filled in for them, they pick a display name, and they're chatting — no sign-up, no email, no phone number.

4. How to reach Hearth (pick one)

For privacy, Hearth doesn't have a web address until you give it one — so it won't open from your phone until you do this step once. You set it up from the Access button on the Hearth card in your dashboard (Apps → Hearth → Access). Pick whichever option fits; both give you a real https:// link that works on your phone with notifications. If you're not sure, do the first one — it's free and takes about five minutes.

Easiest & free: a DuckDNS web address

No domain of your own? Get a free one:

1. Go to duckdns.org and sign in (Google, GitHub, etc.).
2. Type a name in the box — like yourname — and click add domain. You now own yourname.duckdns.org. Copy the token shown at the top of the page.
3. In your SparkBox dashboard, open Apps, find Hearth, and click Access.
4. Enter yourname.duckdns.org, tick Use a DNS challenge, choose DuckDNS, and paste your token.
5. Click Set up public access. SparkBox fetches the HTTPS certificate for you (a minute or two).

Done — your Hearth now lives at https://yourname.duckdns.org. Share that link (with your join code) and it works from any phone, anywhere. (Tip: with DuckDNS, use the plain yourname.duckdns.org — it doesn't do chat.yourname.duckdns.org-style sub-names.)

If you already own a domain

Same steps, but enter your own address (e.g. chat.yoursite.com). If your domain is on Cloudflare, tick the DNS challenge and choose Cloudflare (paste a scoped API token). Otherwise, just point that domain's DNS at your home IP first, then enter it.

Private, over Tailscale

Tailscale gives you a private link only your own devices can reach — nothing is exposed to the public internet, which is the most private way to run Hearth. One honest heads-up: making Hearth one-click over Tailscale is a feature we're still finishing — right now, when you open Access, Tailscale will tell you it points at your dashboard, not Hearth. So for today, use the DuckDNS option above to get Hearth on your phone; one-tap Tailscale support for Hearth is coming in a SparkBox update. (If you're comfortable in a terminal and already run the Tailscale module, you can point your tailnet at Hearth's port manually in the meantime — ask in d/sparkbox and we'll walk you through it.)

5. Install it on your phone

Hearth works like a real app once you add it to your home screen — that's also what enables push notifications.

• iPhone: open your Hearth link in Safari, tap the Share button, choose Add to Home Screen, then open Hearth from the new icon. When it asks, allow notifications.
• Android: open the link in Chrome, tap the menu, choose Install app, then open it from the icon and allow notifications.

One thing to know on iPhone: notifications only work from the installed app on your home screen, not a Safari tab — so do the Add to Home Screen step.

6. Channels, calls & no limits

Make channels however you want with the + next to "Channels." Share photos and video with no upload cap — they're stored on your pool. React to messages, edit or delete your own, and tap Gather in a channel to start a voice or video call with everyone there. The member list shows who's by the fire right now.

7. Where your data lives

Your messages, uploads, and notification keys live on your storage pool under:

${SB_DATA_DIR}/hearth/   (e.g. /opt/sparkbox/data/hearth)

That keeps big media on your large pool, not the system disk. Backups via the SparkBox dashboard's Backup tile include this directory, so a single restore brings your whole Hearth back on a fresh install.

Next steps