All guides
#architecture#how-it-works#nostr#nip-29

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.

5 min read
How Obelisk worksOn a usual chat platform, your account, your data and the rules live on the company's server, between you and your community. In Obelisk you sign each message with your own key and it goes straight to your community's relay, a NIP-29 relay: Obelisk runs a public one, and anyone can run their own. The Obelisk app only signs and shows.A USUAL CHAT PLATFORMYoumessageThe company's serveryour account · your data · its rulesYour communityOBELISKYou, with your keysigned messageYour community's relayObelisk's relayor your ownYour communityUse Obelisk's relay or run your own: your community depends on no one.

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

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

  1. You type a message in a channel on your server.
  2. The app builds a kind 9 event (NIP-29 group message), tagged with the group ID and, for a reply, the event it answers.
  3. The event is signed with your key: by the extension, by the signer app, or in the browser for a pasted or generated key.
  4. The connection manager publishes it to that relay over the WebSocket.
  5. 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 its 39001 admins list.
  • Join / leave: you send a 9021 join request or a 9022 leave request. The relay lets you in (or holds the request for an admin) and updates its 39002 members list.
  • Moderation: admins add and remove people with 9000 (put user) and 9001 (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.

Creating a channel: you become its admin, and it lives on the relay, not on an Obelisk server.25s, no sound

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.

Your name, picture and banner are a Nostr profile event you sign; every Nostr app can read it.30s, no sound

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.