- commit
- b831e5404ee2e629db688c3deb2def6e02284e00
- parent
- 57888af38258148d1ccbe4dae365004cae7838cd
- author
- Dami <dami.etoile@gmail.com>
| M | docs/ | 138 | ++++++------------------------ |
@@ -7,37 +7,35 @@ audience: user
77 88 bind.ws gives you a nostr relay at a name you choose. You claim it with your nostr key. There is no account, password or email.99 10-You need a nostr key and something that signs with it: a browser extension such as Alby, nos2x or Nostash, or a remote signer app such as Amber or nsec.app, which the relay's page connects to (NIP-46). Any nostr client works with the relay once it exists.10+You need a nostr key and something that signs with it: a browser extension such as Alby, nos2x or Nostash, or a signer app such as Amber or nsec.app on your phone. Any nostr client works with the relay once it exists.1111 12-## Claim a name13-14-1. Open `https://<name>.bind.ws/` in your browser. Names are three to 32 lowercase letters, digits or hyphens.15-2. If the page says the relay is unclaimed, click **Claim**. Your extension asks you to sign one request.16-3. The page becomes your relay's console. You are the owner.12+## Try one1713 18-If the page shows someone else's name, the relay is taken. Pick another.14+Not sure about a name yet? Click **Try one now** on the front page, or ask from a script:1915 20-## From a phone16+```17+curl -X POST https://bind.ws/lease18+```2119 22-No extension is needed. Open the relay's page, choose **Use a remote signer**, and tap **Open in your signer app**. The app asks you to approve the connection and the page continues where you left off, claiming or signing in. On a computer, paste the `bunker://` URL your signer app gives you instead. The relay itself carries the signer traffic, so this works on a relay nobody has claimed yet.20+You get a relay at a memorable name, such as `wss://brave-otter.bind.ws`. Anyone can read and write to it for 14 days. Then everything on it is deleted and the name is freed. Its page says when.2321 24-The page remembers the connection until you sign out.22+To keep it, open its page and click **Claim this relay** before then. The events and files stay, and you are the owner. The page then offers to switch to the default rules, since a temporary relay keeps events for 14 days only.2523 26-## Try one first24+If you sign the request with your key (a signed request, NIP-98), only that key can claim the relay.2725 28-Not ready to pick a name? Click **Try one now** on the front page, or ask for one from a script:26+## Claim a name2927 30-```31-curl -X POST https://bind.ws/lease32-```28+1. Open `https://<name>.bind.ws/`. Names are three to 32 lowercase letters, digits or hyphens.29+2. If the page says nobody owns the relay, click **Claim this relay**. Your extension asks you to sign once.30+3. The page becomes your relay's console. You are the owner.3331 34-You get a relay at a memorable name, such as `wss://brave-otter.bind.ws`. Anyone can read and write to it for 14 days. Then everything on it is deleted and the name is freed. Its page says when.32+If the page shows someone else's name, the relay is taken. Pick another.3533 36-To keep it, open its page and click **Claim** before it expires. The relay converts in place: the events and files stay, and you are the owner. The page then offers to switch to the default rules, since a temporary relay lets anyone write and keeps events for 14 days only.34+## From a phone3735 38-If you sign the request with your key (NIP-98), only that key can claim the relay. Agents and scripts with a key get a relay that nobody else can take from them.36+No extension is needed. Open the relay's page, choose **Use a remote signer** and tap **Open in your signer app**. The app asks you to approve the connection, and the page continues where you left off. On a computer, paste the `bunker://` URL your signer app gives you and click **Connect**.3937 40-To keep the events but not the name, claim the name you want and pull the temporary relay into it. See [Bring events in](#bring-events-in).38+The relay carries the signer traffic itself, so this works on a relay nobody has claimed yet. The page remembers the connection until you sign out.4139 4240 ## Connect a client4341 @@ -51,102 +49,24 @@ That is all. The relay speaks the standard protocol, so Damus, Amethyst, noStrud
5149 5250 ## Tell your clients5351 54-A relay only helps once your clients know about it. On the Identity tab, **Tell your clients** has one row per list: your relay list (NIP-65), your DM inbox (NIP-17), your search relays and your Blossom servers. Each row fetches the newest copy of that list from this relay and a few well-known indexers, puts this relay first, and asks you to sign the result once. The merged list is sent here, to the relays it names, and to the indexers, so nothing you had listed is lost. **Remove me** publishes the list without this relay.55-56-## Share your relay57-58-Every relay has a card: `https://<name>.bind.ws/card.svg` is a picture with the name, who may read and write, the fuel state and a QR of the group address, and `/card.json` has the same facts as data. The **Share** block on the Identity tab shows the card, the group naddr with a copy button, and an embed snippet for a profile or a page.59-60-## Your own domain61-62-Your relay can answer at a hostname you own, such as `wss://relay.example.com`. On the Identity tab, under **Your own domain**, add the hostname. The page shows one record to create at your DNS: a CNAME from your hostname to the address it gives you. Once the record resolves, the certificate is issued on its own and **Check** turns green. Up to three hostnames per relay. Everything else stays the same: same events, same members, same console, reachable by either name.63-64-This needs the host to have switched custom domains on. If they have not, the block says so.52+Clients find your relay through the lists you publish: your relay list, your DM inbox, your search relays and your Blossom servers. On the Identity tab, **Tell your clients** has one row per list. **Check** finds your newest copy here and on a few indexers. **Add me** puts this relay first, asks you to sign once and publishes the merged list here, to the relays it names and to the indexers. Nothing you had listed is lost.6553 6654 ## Invite people6755 68-A new relay accepts writes from its members only. To add someone:69-70-- **Invite link.** On the People tab, mint an invite. Share the link. The person opens it, signs once and becomes a member.71-- **Add by key.** Paste a pubkey or npub on the People tab.72-73-To let anyone write, set **Rules > Writes** to *anyone*. To let only yourself write, set it to *only me*.74-75-Members can bring people in too, if you let them. On the People tab, under the invites, set how many hops from you the tree may reach and how many live invites each member may hold. A member then sees a **Your invites** section on the relay's page. The People tab shows who invited whom, and removing a member can take everyone they invited along.76-77-## Moderators78-79-On the People tab, set a member's role to *moderator*. A moderator can add and remove members, ban, delete events, mint invites and work the reports queue, from the relay's page or from a group-aware client. Rules, identity, storage and fuel stay with you.80-81-## Hand it over82-83-On the Owner tab, **Transfer ownership** gives the relay to a member. You stay on as a moderator. The relay's key, events, files and fuel do not change.84-85-## If you lose your key56+A fresh relay lets anyone write. To keep it to your people, set **Rules > Writes** to *members*. Then, on the People tab:8657 87-Keys get lost. On the Owner tab, under **If I lose my key**, name a member as your heir and pick how long you can be away: three months, six, or a year. If you do not sign in for that long, the relay writes to you once a week for a month, in your own inbox and on your DM relays. If you still do not show up, it hands itself to the heir and keeps you on as a moderator. Any signed action on the relay, a console visit, a post, a signed request, resets the clock. Nothing else changes: the relay's key, events, files and fuel stay as they are.58+- **New invite link** mints a link. The person opens it, signs once and becomes a member.59+- Paste a pubkey or npub in the top row to add someone directly.8860 89-## Groups in clients61+Members can have a name at your relay, such as `alice@<name>.bind.ws`. Set it in their row, or they set it in their profile.9062 91-Your relay is also a NIP-29 group, one group per relay, so clients that understand groups (Flotilla, Chachi, 0xchat, Coracle) show it as a community: name and picture, who is in it, a join button and moderation. The group id is the relay's name. Who may read and write follows your Rules tab: members-only reads make the group private, and anything but open writes makes it closed, so joining needs an invite code.92-93-## Names94-95-Members can have a name at your relay, such as `alice@<name>.bind.ws`. Set it on the People tab, or a member sets it in their profile's NIP-05 field. Clients show the name next to the person.96-97-The relay has a profile of its own, made from the name, description and icon on the Identity tab, so it appears like a person where clients show relays.98-99-## Media100-101-Your relay stores images and files too. Clients that support Blossom upload to `https://<name>.bind.ws` and get a link by hash. A client can ask first whether an upload would be accepted, and can have the relay copy a file from another server by URL instead of uploading it again. Set the maximum upload size on the Rules tab.102-103-Clients that speak NIP-96 instead find the same store through `/.well-known/nostr/nip96.json`. The two doors share one bucket and one file list, so a file uploaded through either is served, listed and deleted through both, and every answer carries the file's NIP-94 tags.104-105-To report a file, send a signed NIP-56 report that names its hash to `PUT /report`. It lands in the owner's reports queue next to reported events. Deleting a reported file also blocks its hash, so it cannot be uploaded again.106-107-## Pages and feeds108-109-Every name is a site as well as a relay. A note has a page at `https://<name>.bind.ws/e/<id>` and an article at `/a/<d>` (yours) or `/a/<npub>/<d>` (anyone's), with the tags link previews need, so a link to your relay unfurls in chat apps and on social sites. `/feed.xml` is an Atom feed of the relay's notes and articles; add `?kinds=30023` for articles only or `?author=<hex>` for one person.110-111-Pages exist only while **Rules > Reads** is *anyone*. On a members-only relay they answer 404, so nothing leaks.112-113-## Scripts114-115-If you write scripts, the relay has an HTTP door. Sign a request with your key (NIP-98) and post to `/events`, `/query` or `/count`. No websocket needed.116-117-## Bring events in118-119-The Data tab has a **Jobs** block: work your relay does on its own, in the background, in small rounds, so it keeps going while the relay sleeps between them.120-121-- **Pull** copies what another relay has and yours lacks, by NIP-77 sync. Run it again later and only new events come over. Files come along when the other relay is on bind.ws. Pick an interval and it becomes a standing mirror that keeps your name in sync every hour, six hours or day.122-- **Fetch my history** pulls your own events from every relay in your relay list (kind 10002), if a client has published it here. Or give it relays to fetch from.123-- **Rebroadcast** sends what your relay holds to other relays, like a blaster. Choose kinds and a day window, or leave both blank for everything. As a standing job it forwards only what arrived since the last run. Events only their author may publish are left out, and a members-only relay never rebroadcasts private messages.124-125-Jobs spend awake time, which fuel counts. Up to five standing jobs per relay.126-127-Your bans and kind rules apply to what arrives. Your write rule does not: you asked for these events.128-129-## Notifications130-131-The relay can write to you. On the Health tab, switch on what you want to hear about: a report arriving, fuel running low, a pull finishing. Each is a NIP-17 private message signed by the relay's own key, stored on your relay as your inbox and pushed to your DM relays when your kind 10050 is here. It shows up in whatever client you already use for messages.132-133-## One name per job134-135-Names are cheap, so a relay does not have to do everything. Two ways to spread a life over several names:136-137-- **Presets that mirror.** On the Rules tab, the `search`, `articles`, `media` and `dm` presets turn a name into a single-purpose relay. `search` and `articles` take a source relay and keep a standing pull of their kinds from it, every six hours or daily, so `alice-search` stays a read-only copy of `alice` that clients can point search at. `media` is a file host whose only events are profiles and Blossom server lists. `dm` is an inbox for private messages that only members can read.138-- **Fork this relay.** On the Data tab, a fork leases a new name, copies this relay into it (everything, only your events, or chosen kinds, with or without the people) and reserves the claim for a key: yours, to split a name by job, or someone else's, to hand a community its own relay with its history. The new name is temporary until it is claimed, and one fork an hour is allowed.139-140-## Leave141-142-Your data is yours. Any relay that supports sync (NIP-77) can pull everything from your relay:143-144-```145-nak sync -a <your-pubkey> wss://<name>.bind.ws wss://<other-relay>146-```63+## What it costs14764 148-Or download a dump. On the Data tab, turn on **Dumps** and the relay writes every event as one JSONL file daily or weekly, keeping the last few. **Dump now** writes one on the spot. Downloading takes your signature; the files are never a public link.65+Nothing until the relay passes its monthly free allowance. Past that, use is paid in sats, and anyone can zap the relay to top it up. See [Understanding fuel](02-understanding-fuel.md).14966 150-## What it costs67+## Where next15168 152-Nothing until you pass the free allowance. See [Understanding fuel](02-understanding-fuel.md).69+- [Relay configuration](01-relay-configuration.md): the console, tab by tab.70+- [People and groups](03-people-and-groups.md): invites, moderators, groups in clients, handing the relay over.71+- [Data and names](04-data-and-names.md): pulls, mirrors, dumps, presets and forks.72+- [Your relay on the web](05-your-relay-on-the-web.md): pages, the feed, the card, your own domain and media.