How Obelisk works
Obelisk is a web app with no backend of its own. It signs Nostr events with your key and sends them straight to your server, which is a NIP-29 relay, and to the other relays it needs. Here's what happens when you log in, send a message or join a group.
The shape of the app
Obelisk has two moving parts: the web app in your browser, and the relays it talks to.
┌───────────────────────┐ signed events ┌──────────────────────┐
│ Obelisk web app │ ──────────────► │ Your server │
│ (your browser; │ ◄────────────── │ (a NIP-29 relay) │
│ your key signs) │ └──────────────────────┘
│ │ profiles, DMs ┌──────────────────────┐
│ │ ◄─────────────► │ Other Nostr relays │
└───────────────────────┘ └──────────────────────┘
A community's server, the thing the app's Server settings configure, is a NIP-29 relay. It stores the channels, the messages and the roles, and it enforces who may do what. Nothing sits between you and it: there is no Obelisk database, no account service and no session server. Your key stays with you (in a browser extension, in a signer app, or sealed on your device) and signs every event. One connection manager in the app keeps a WebSocket open to each relay and sends the signed events straight there; to read, the same app subscribes to the relay's stream.
The site itself is served by a small Next.js server: the pages, their security headers, link previews (so a link you only look at never reaches a third-party preview service) and the public note and profile pages. It holds no accounts, no keys and no messages.
What happens when you log in
-
The login screen offers these ways in:
- Browser extension (NIP-07): Alby, nos2x and the like sign through
window.nostr. The key never leaves the extension. - Signer app (NIP-46): scan a QR code or paste a bunker link from Amber, nsec.app or another remote signer. The key stays in that app, and Obelisk asks it to sign.
- nsec: paste a private key. Before it is saved on this device it is sealed with a key the browser cannot export, so it is never stored in the clear.
- Generate: create a brand-new keypair right there, and back it up.
- Browser extension (NIP-07): Alby, nos2x and the like sign through
-
The app derives your pubkey, fetches your kind 0 profile from profile relays, connects to your server, and you're in. There is no account, no password and no token from us: the key is your identity, and the session record on your device is encrypted. If the browser cannot keep that record safely, the login lasts only while the tab is open.
What happens when you send a message
- You type a message in a channel on your server.
- The app builds a kind 9 event (NIP-29 group message), tagged with the group ID and, for a reply, the event it answers.
- The event is signed with your key: by the extension, by the signer app, or in the browser for a pasted or generated key.
- The connection manager publishes it to that relay over the WebSocket.
- The relay checks that you may post there, stores the message, and everyone subscribed to that channel sees it land.
There is no "send to Obelisk's server" step. Your server is the relay.
What happens when you join or create a group
Groups are NIP-29 groups. The relay holds them, not us.
- Create: the app sends a
9007(create group) event. The relay records you as the group's first admin in its39001admins list. - Join / leave: you send a
9021join request or a9022leave request. The relay lets you in (or holds the request for an admin) and updates its39002members list. - Moderation: admins add and remove people with
9000(put user) and9001(remove user); the relay enforces them. - Channels, metadata, admins, members: all standard NIP-29 events the relay publishes itself:
39000(metadata),39001(admins),39002(members).
Groups belong to the relay you are browsing, so switching relays is switching servers. The app doesn't care which relay it is, as long as it speaks NIP-29.
What about profiles and DMs?
Profiles and direct messages don't live on your server. The app reaches other Nostr relays for them itself:
- Profiles (kind 0) and social feeds come from profile and feed relays you can change in settings, never from your server.
- DMs are off until you turn them on in settings. Obelisk sends them as NIP-17: "gift-wrapped" and encrypted with NIP-44, delivered to the recipient's inbox relays, so a relay sees neither the sender nor the content. It still reads older NIP-04 messages (kind 4), so existing conversations show up.
Both are end-to-end encrypted: only the sender and the recipient hold the keys to decrypt.
What about voice?
Voice channels use WebRTC, set up with Nostr events. In an ordinary voice channel, up to four people connect straight to each other (a mesh). For bigger rooms, a channel admin can make it an SFU channel, routed through a mediasoup SFU the admin picks or hosts. Audio and video never pass through an Obelisk server.
What about Lightning zaps?
Zaps are NIP-57:
- The app signs a zap request (kind 9734) and sends it to the recipient's LNURL server, which answers with a Lightning invoice.
- Your wallet pays it: a browser wallet through WebLN, or a wallet you connect with Nostr Wallet Connect (NIP-47).
- The recipient's LNURL server publishes the zap receipt (kind 9735) to the relays named in the request, so everyone sees the sats moved.
No platform takes a fee. Your wallet, the recipient's wallet, no middleman.
What we don't do
- We don't host your messages: your server's relay does.
- We don't have a user database or accounts.
- We don't issue login tokens or session cookies. The only cookie remembers your language.
- We never see your key, so the app can't lock you out: your identity works on any relay that speaks NIP-29.