Host it yourself
Run Hearth's server on a computer you own. Everything is stored there and nowhere else. No account with us, no licence key, and no price.
Before you start: the code is not public yet
This guide starts from a copy of Hearth's code, and today that copy is private. The code's address and its licence go here once the repository is public. Until then you can read the steps, and nothing below needs an account with us.
Where this guide says it did not run something, it means that: the steps were tried on the systems named, and the rest follow what the code does.
What you need
- A computer that stays on while you use Hearth. A desk computer, a small server or a cloud machine.
- Docker with Compose v2 (
docker compose versionworks). Docker Desktop on macOS or Windows, Docker Engine on Linux. Give Docker at least 2 GB of memory. The server uses about 0.5 GB when idle. The machine itself wants 4 GB, because setup builds the web app on top of what Docker uses. - bun 1.4.4 or newer and git. Setup builds the web app from the code you cloned.
- About 6 GB of free disk for a new server. The images are about 4 GB and are pulled the first time.
You do not need the Supabase command line, an account anywhere, or a mail server. Hearth sends no mail from a server you run.
On Linux
- Install
unzipfirst (sudo apt install unzip). bun's installer needs it, and a stock Debian 12 does not have it. - The bun installer adds bun to your PATH only through
~/.bashrc. Open a new shell, or runsource ~/.bashrc, beforebun install. - Setup's first step looks up
public.ecr.aws(where the images come from) andgithub.com. If either fails, setup stops before it pulls anything and says DNS is broken on this machine.
Set it up
git clone address of the code, once it is public hearth && cd hearth
bun install
bun run server setup
With no options, at a terminal, on a new server, setup is a guided walk. It is a front on the real setup steps, not a second installer. It asks five things:
- It checks this computer first, before it writes anything. bun, Docker with Compose v2 and that it is running, Docker's memory (2 GB at least), free disk, and that the web, API and database ports are free. A check that fails says what to do (start Docker, give it more memory, free a port or pick another with
--web-port) and setup stops with nothing written. - "Who needs to reach this server?"
- Only devices on this network. Plain http. No phone notifications.
- My own devices, anywhere (Tailscale). Setup reads Tailscale's status, takes the https name from it, runs the two
tailscale servelines itself and builds the app for those addresses. If Tailscale is not installed, not signed in, has HTTPS off for the tailnet, or already serves something else on port 443 or 8443, setup says so and offers the first answer for now. It never replaces what Tailscale already serves. - People I invite, anywhere. A public https address you already have. It asks for the web app's and the API's https addresses. Setup does not get a certificate for a domain name yet.
- Your email, for the first account.
- Back up every night? Yes by default. See backups.
- Run agents on this computer too? Yes by default on a desk computer. No on a Linux machine with no display, or over SSH, which is what a cloud server is. Yes builds the helper at the end and signs it in; the next section says what that is.
Then it sets up, which takes a few minutes the first time because of the downloads. It makes every secret itself, starts the database, the sign-in service, live updates and the web server, applies the migrations, deploys the server functions, checks the timers are running, and builds the web app for this server's address. It checks that both addresses answer from this computer, and ends with a link that works once, for 30 minutes:
Finish in your browser. This link works once, for 30 minutes; you choose your password there:
http://192.168.86.24:54680/welcome#<key>
The page asks for a password and signs you in. No password is made or printed. If the link runs out or is lost, bun run server link on the server's computer makes a fresh one. It is also how someone who forgot their password gets back in. Anyone who opens a link before its person does can set that password, so give it to the person directly.
Then, in the browser
- Choose your password. Hearth then asks you to name your first org. An org holds your boards, cards and computers. It starts with only you in it.
- Add a computer, set up Claude Code on it, add Hearth to Claude Code, and make your first card. Home shows these as steps and ticks each one when it is true.
Sign-ups on this server are closed once the first account exists: the database lets in only the email addresses it was told to expect. People you invite get a link from inside the app.
Setup with options
Every question has an option, so setup can run from a script. A first run with --email, or --yes, or with no terminal, is not guided. It asks nothing and prints the first password once, so write it down.
| Option | Default | What it does |
|---|---|---|
--email <address> | The first account. With it, setup is a script. | |
--org <name> | none | Also makes an org with the first account as its owner. Without it the app asks for the org's name. |
--backups on|off | off (guided: asked, Yes) | Nightly backups, the newest 14 kept. |
--host <address> | found | This computer's address on your network. Say it when the computer has several (a VPN, Docker, a second network card). |
--web-port, --api-port | 54680, 54621 | The two ports other devices reach. |
--db-port | 54622 | The database, on this computer only (127.0.0.1). |
--listen <address> | 0.0.0.0 | Where the two public ports listen. 127.0.0.1 for this computer only. |
--web-url, --api-url | http://<host>:<port> | The public addresses, when a tunnel or proxy serves them over https. |
--state <folder> | ~/.hearth-server | Where the secrets and the built app live. |
--project <name> | hearth-server | Docker's project name, so two servers can share one computer. |
If a setup stops part way, an image would not pull, say, run it again. It says An earlier setup stopped at …. Carrying on from there., keeps the answers it already has and asks only for what is missing. Running setup again also changes the address or the answers and keeps your data. Setup refuses to run when a Hearth database for the same project already exists in Docker but the state folder has no server.env: that database was made with other secrets. It writes nothing and says what to do.
Add a computer that runs agents
The server holds cards, comments and proof. The agents that do the work run on computers of yours, each with its own Claude Code and its own repos. A computer runs a small program, the helper, which signs in to your server and starts Claude Code when a card is ready.
If you answered Yes to "Run agents on this computer too?", this computer is done: type the code the helper shows into Home once you have chosen your password.
For another computer, there is no installer yet: the helper is built from the code. On that computer, with the repository cloned and bun installed:
bun install
bun run --filter hearth build
bun apps/helper/dist/cli/main.js login --url http://192.168.86.24:54621 --key <public key> --web http://192.168.86.24:54680
bun apps/helper/dist/cli/main.js run
Setup prints the login line for your server with its real addresses and key; copy that one. Type the code login shows into the web app (Home, Enter the code). The helper's state goes to ~/.hearth on that computer.
That computer also needs Claude Code installed and signed in. You pay Anthropic for model use on your own plan; Hearth has no part in it.
Who can reach it
Two ports, both TCP, must be reachable from the devices that use Hearth:
| Port | What |
|---|---|
54680 | The web app, served by a small nginx. |
54621 | The API: sign-in, the database's functions, live updates (a WebSocket on the same port) and the server functions. Browsers, phones and every helper talk to this. |
The database port (54622) listens on 127.0.0.1 only, so only the server computer reaches it. Nothing else is published. On macOS the first start may ask whether Docker may accept incoming connections: allow it. On Linux open the two ports in your firewall (sudo ufw allow 54680/tcp and 54621/tcp). Your router needs nothing for use inside your own network.
Two networks. If your computers are on two networks (a double NAT: one router behind another), put the server on the outer network, the one both can reach. Check from each device: curl http://<server address>:54621/auth/v1/health answers 401 with "No API key found" when it reaches the server.
Plain http, and what does not work on it
On your network the server speaks plain http. That is enough for the web app and for the helpers, with two things missing, because browsers allow them only on https: web push (notifications on a phone while the app is closed) and Add to Home Screen as an installed app on iPhone. Sign-in, the board, live updates and everything else work. Traffic on your network is not encrypted: anyone on the same Wi-Fi who can watch traffic could read it. Anywhere you do not trust the network, use https.
https, and reach from outside
Setup's second and third answers do this. By hand it is the same thing. Pick one:
Tailscale, for devices you own, private. Install Tailscale on the server and on every device, sign them in to your tailnet, turn on HTTPS certificates in the admin console (DNS, Enable HTTPS), then on the server:
tailscale serve --bg --https=443 http://127.0.0.1:54680
tailscale serve --bg --https=8443 http://127.0.0.1:54621
bun run server setup --web-url https://<machine>.<tailnet>.ts.net --api-url https://<machine>.<tailnet>.ts.net:8443
Only devices in your tailnet reach it. If you use Tailscale access rules, they must allow ports 443 and 8443 to this machine. This is the one to choose unless you need people outside your tailnet.
Cloudflare Tunnel, for a public address on a domain you have on Cloudflare. Install cloudflared, run cloudflared tunnel login and cloudflared tunnel create hearth, and route two host names to http://127.0.0.1:54680 and http://127.0.0.1:54621 in its config. Then:
bun run server setup --web-url https://hearth.example.com --api-url https://hearth-api.example.com
This puts the sign-in page on the public internet. Keep sign-ups closed (they are, by default) and consider Cloudflare Access in front of the web address.
After either, setup rebuilds the web app for the new addresses and Auth learns its new address. Log each helper in again with the new --url and --web. Adding --listen 127.0.0.1 keeps the plain-http ports off your network if you want only the tunnel.
Phone notifications
With an https address, open Hearth on the phone, go to Settings, Notifications and tap Turn on notifications on this device. The browser asks once. Send a test checks the whole path. On an iPhone or iPad, add Hearth to the Home Screen first (Safari, Share, Add to Home Screen; iOS 16.4 or later), open it from there, and turn notifications on inside it.
- Setup makes the server its own VAPID key pair the first time and keeps it in
server.env. Do not change it. Every phone subscribed with the public key, and a new key would silently cut them all off. - The server needs a way out to the internet for this. A push goes from your server to the browser maker's push service (Google's, Mozilla's, Apple's or Microsoft's), which delivers it to the phone. With no way out nothing is lost: the notice goes to a computer instead, about three minutes late, and Settings says why the push was not reached.
- The push names a contact,
mailto:push@hearth.invalidby default, so the push services learn nothing about whose server this is.--push-contact mailto:you@example.comsets yours.
Upgrade, back up, restore, move
Run these in the folder you cloned, on the server's computer:
git pull && bun install
bun run server setup # upgrade: new migrations and functions, a rebuilt web app; your data and secrets are kept
bun run server status # what runs, migrations applied, when each timer last ran, how many accounts
bun run server check # checks the running server against what it should be
bun run server down # stop; the data stays in Docker volumes
bun run server up # start again
bun run server backup # a full pg_dump to ~/.hearth-server/backups/hearth-<time>.dump
bun run server restore <file> --yes
bun run server logs [auth|db|kong|rest|realtime|functions|web]
bun run server psql
A new server follows numbered releases rather than the newest change on the main branch. The containers restart by themselves after a reboot when Docker starts, unless you stopped them with down.
A server serves the helper and the web app of the release before it, so an upgrade does not have to wait for every computer's helper to move. A helper that is behind keeps working and says it is older than the server; one that is too far behind is refused with "Update the helper".
Nightly backups
Answer Yes at setup (or pass --backups on) and a small container beside the server dumps the database every night at 03:00 on this computer's clock into ~/.hearth-server/backups/, as hearth-nightly-<time>.dump. It keeps the newest 14. A backup you took by hand, or the one an upgrade takes first, is never removed. A computer that was off at 03:00 takes one when it is back. bun run server logs backup says what happened.
Back up two things, and keep both as private as each other: the dump files and ~/.hearth-server/server.env. The dump holds every account and card. The env file holds the keys every signed-in device and helper relies on. Copy them off the computer, because a disk's own failure takes both.
Proof pictures, recordings and output samples are kept in the database, not in a file store, so backup, restore and upgrade carry them with everything else. They are capped: 900 KB a picture, 24 MB a session, 1 GB an org, and they are removed 60 days after their card's check is decided.
Restore
bun run server restore <file> --yes takes a backup of what is there first, makes a fresh database, applies the migrations the backup was made with, puts in the backup's rows and runs setup for any newer migrations. A backup from a newer checkout than yours is refused. People sign in with their password as before. A helper keeps its sign-in if the secrets are the same (the same server.env); otherwise it runs login again.
Never run docker compose down -v or docker volume rm on hearth-server_db-data. That is the database.
Move to another computer
# On the old computer
bun run server backup # prints the dump's path
# copy that dump and ~/.hearth-server/server.env to the new computer
# On the new computer (Docker running, the code cloned at the same or a newer version, bun install done)
bun run server move <the dump> --from <the old server.env> [--state <folder>] [--host <address>]
move keeps the old server's secrets, so every helper's sign-in keeps working. It asks for the new web and API addresses, starts a new database, restores the dump into it and runs setup. Then, on each computer that runs agents, run login --move --url <new API address> --web <new web address> and restart its helper: it stays the same computer, with no new code to type. Each phone and browser opens the new web address and signs in again, and turns notifications on again. When the new one works, run bun run server down on the old computer.
Closing a person's account
Removing someone from an org takes them out of the org, not off the server. To close their account from the server, make someone else an owner of any org they alone own, then run these two lines at bun run server psql, with their email:
update private.callers set revoked_at = now() where user_id = (select id from auth.users where email = 'them@example.com');
update auth.users set banned_until = now() + interval '100 years' where email = 'them@example.com';
The first makes the database refuse every request of theirs at once, even with a sign-in they already hold. The second stops new sign-ins. Write the date as shown, never 'infinity': the sign-in service cannot read it and then fails for every account. Set revoked_at and banned_until back to null to open it again.
On a cloud server
A Debian 12 virtual machine on Google Cloud ran this once. An e2-medium (2 vCPU, 3.8 GB) was enough for a few people: memory peaked at about 1.5 GB during setup and sat near 1.1 GB at rest. The web build took about 17 seconds, the image pulls about 108 seconds. After a reboot all eight containers came back. A 2 GB machine is smaller than what was tried. Install Docker Engine, unzip and bun first (see "On Linux" above), then run the same bun run server setup.
A cloud server needs the Tailscale or public-address answer. "Only this network" means nothing there.
- Open: only 443 (and 80 if your certificate tool needs it), through a reverse proxy with https (Caddy or nginx with Let's Encrypt) in front of ports 54680 and 54621 on 127.0.0.1, with
--listen 127.0.0.1 --web-url https://… --api-url https://…. Or open no public port at all, and use Tailscale or your provider's identity-aware proxy. - Never expose: 54622 (the database), 54621 and 54680 over plain http, or SSH to the whole world. The firewall of the machine and the provider's firewall are two separate gates; check both.
- Keep
server.envand the backups off the machine too, in a bucket with restricted access or on your own computer. A disk snapshot of the machine holds the secrets as well. - What the operator of the machine can read: everything in the database. That is the reason to run your own server at all. Run it on a machine only you control.
A cloud machine has no helper, so it runs no agents. Add your own computers as above. Upgrading is over SSH: git pull, bun install, bun run server setup.
Windows
Not run on Windows yet. What the setup does differently there is written to handle these cases, but none was seen on a real Windows machine:
- Use Docker Desktop with the WSL2 back end, and give it at least 2 GB. Docker's volumes live inside WSL2, so back up with
bun run server backup. - Run the commands in PowerShell from the folder you cloned.
- Windows reserves blocks of ports around the defaults, and reserves them again at each boot. Setup names any port that is reserved or in use before it starts, and suggests
--web-port 8480 --api-port 8421 --db-port 8422. On Windows use those from the start. - Allow Docker on Private networks only, or add rules:
New-NetFirewallRule -DisplayName "Hearth web" -Direction Inbound -Protocol TCP -LocalPort 54680 -Profile Private -Action Allow, and the same for the API port. - With several network adapters (WSL's and Hyper-V's), pass
--host <address>. - Set Docker Desktop to start when you sign in, or the server will not come back after a reboot.
What was tried, and what was not
| Where | What was seen |
|---|---|
| macOS, Docker Desktop | The guided setup from a terminal, a second setup as an upgrade, backups, and signing in from the one-time link. |
| Linux, Debian 12 on Google Cloud | Setup on an e2-medium, and all eight containers coming back after a reboot. |
| Tailscale answer, public-address answer | Not run on a live system. The lines setup would run are held by tests, and the first outside run is still to come. |
| Phone notifications over https | Not run on a server you run. |
| "Yes" to running agents on the server's own computer | Not run. |
| Windows | Not run. |
If you try one of these and it does not go as written, that is worth knowing: it is how this guide gets better.