Appear online only to your support circle. Invisible to everyone else.

---

What is hearth?

Discord shows your status to everyone you share a server with, and to all your friends. There's no built-in way to say "I'm here, but only for certain people."

Hearth fixes that. Turn it on and you're visible to a small circle you choose. To everyone else, you look offline.

How it works

Discord only syncs presence between users who share a server. Hearth manages a private server whose membership is your circle. Run /status on and the bot sends you a one-time invite to join. Once you're in, your circle members can see your real status natively. Run /status off and the bot removes you from the server. You disappear.

If you enable /notify on, you'll get a DM when someone in your circle comes online.

Bring your own server

Don't want to rely on the shared hearth server? Run /host invite to get a link that adds hearth to a server you already control, with zero permissions requested. The moment it joins, that server becomes its own private circle: anyone who's a member there and opted in with /status on is mutually visible to everyone else in it. No setup, no claiming step required.

What hearth cannot do

If you share other servers with someone, or they're on your friends list, Discord will still show them your status. Hearth controls who is in one private server, not Discord's presence system directly. For full invisibility, use Discord's built-in invisible mode.

---

Self-hosting

Prerequisites

• Node.js 22.12.0+
• A Discord application with a bot user (Discord Developer Portal)
• Privileged intents enabled in the portal: Server Members Intent and Presence Intent
• A private Discord server to use as your hearth server (optional - users can also bring their own via /host, see below)

Installation

git clone https://github.com/MPZ-00/hearth.git
cd hearth
npm install
cp .env.example .env

Configuration

Edit .env:

DISCORD_TOKEN=your_bot_token
CLIENT_ID=your_application_id
HEARTH_GUILD_ID=your_private_server_id
DB_PATH=./data/hearth.db

HEARTH_GUILD_ID is optional. Leave it unset if you only want users bringing their own server via /host.

Running

# Register slash commands (run once, or whenever you change commands)
npm run deploy

# Start the bot
npm run dev        # development, with live reload
npm start          # production (after npm run build)

Generate your install link

Users add hearth to their Discord apps, not to a server. The install URL uses integration_type=1 (user install):

https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&integration_type=1&scope=applications.commands

Replace YOUR_CLIENT_ID with your application ID from the Developer Portal. You can also generate this link from the portal under Installation → Install Link.

Setting up your hearth server (optional, shared mode)

1. Create a new Discord server. Keep it private and disable the default invite link.
2. Invite the bot (needs Create Instant Invite and Kick Members permissions).
3. Copy the server ID into HEARTH_GUILD_ID in your .env.
4. When someone runs /status on, the bot generates a one-time invite and sends it to them so they can join.

Skip this section entirely if you'd rather have users bring their own server via /host invite (zero bot permissions required). Both modes can run side by side.

---

Commands

Command	Description
/status on	Get a one-time invite to the hearth server so your circle can see you
/status off	Leave the hearth server and go offline to everyone
/add @user	Add someone to your circle
/remove @user	Remove someone from your circle
/list	Show your current circle
/notify on	Get a DM when a circle member activates hearth
/notify off	Turn off notifications
/host invite	Get a zero-permission link to add hearth to a server you control
/host claim	Manually register the current server as a circle gate (usually automatic)
/host unclaim	Stop using the current server as a circle gate

---

If hearth is useful to you, consider sponsoring to help keep it going.

---

Contributing

Issues and PRs welcome. Open an issue before starting something large so we can talk through the approach first. For quicker back-and-forth, join the dev server.

License

MIT