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

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

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:

  1. 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.
  2. "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 serve lines 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.
    The second and third answers make the plain-http ports listen on this computer only, so only the tunnel or proxy reaches them.
  3. Your email, for the first account.
  4. Back up every night? Yes by default. See backups.
  5. 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

  1. 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.
  2. 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.

OptionDefaultWhat it does
--email <address>The first account. With it, setup is a script.
--org <name>noneAlso makes an org with the first account as its owner. Without it the app asks for the org's name.
--backups on|offoff (guided: asked, Yes)Nightly backups, the newest 14 kept.
--host <address>foundThis computer's address on your network. Say it when the computer has several (a VPN, Docker, a second network card).
--web-port, --api-port54680, 54621The two ports other devices reach.
--db-port54622The database, on this computer only (127.0.0.1).
--listen <address>0.0.0.0Where the two public ports listen. 127.0.0.1 for this computer only.
--web-url, --api-urlhttp://<host>:<port>The public addresses, when a tunnel or proxy serves them over https.
--state <folder>~/.hearth-serverWhere the secrets and the built app live.
--project <name>hearth-serverDocker'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:

PortWhat
54680The web app, served by a small nginx.
54621The 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.

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.

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:

What was tried, and what was not

WhereWhat was seen
macOS, Docker DesktopThe 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 CloudSetup on an e2-medium, and all eight containers coming back after a reboot.
Tailscale answer, public-address answerNot 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 httpsNot run on a server you run.
"Yes" to running agents on the server's own computerNot run.
WindowsNot 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.