Looscid runs on Rem. This is the public spec: any app can be a Rem client, not just the Looscid app. Everything here is what the server in this repo actually does.
The name lives in one place in code (PROTOCOL in public/js/rem-core.js): name is what people read,
key is the envelope field, base is the API path, live is the WebSocket path.
- Key-first identity. Your LooscidID is a secp256k1 key pair, the same kind Nostr uses. Any Nostr key works as a LooscidID, and every LooscidID has an npub. The secret key stays on your device.
- Everything is a signed object. A Dream, a like, a follow, a Chat: each is a small JSON object signed by the LooscidID that made it. The server checks every signature and cannot make or change objects for you.
- Local-first, syncs through the Looscid server. Clients keep their own copy and work offline. The home server
is the meeting spot: it keeps copies so friends get your things while you are away, and so a new device gets
everything back (
GET /sync). - A home is accountable. Invite-only, 13+, blocks that work both ways, reports and moderators.
- Accessibility is in the protocol. Images without alt text are refused by the server. Content warnings and "how to read this aloud" are fields, not hacks.
{ "rem": 0,
"type": "dream",
"by": "<32-byte public key, hex>",
"at": 1761948000000,
"body": { "text": "hello", "audience": "public" },
"id": "<sha256 hex>",
"sig": "<64-byte BIP-340 Schnorr signature, hex>" }id= sha256 of the UTF-8 bytes ofcanonical([0, by, at, type, body]).- canonical JSON: like
JSON.stringify, but the keys of every object (at every depth) are sorted, no spaces,undefinedvalues left out. Arrays keep their order. sig= BIP-340 Schnorr signature of the 32 bytes ofid, by the keyby(same math as Nostr events).atis Unix time in milliseconds and must be within 10 minutes of the server's clock (except for/import, below).- Max 64 KB per object.
| type | body | notes |
|---|---|---|
profile |
{ name, bio, pronouns, avatar?: media, chats_from: "mutuals"|"nobody" } |
newest at wins |
dream |
{ text, cw?, speak?, lang?, audience: "public"|"followers", reply_to?, quote?, media?: [media], poll?: { options: [2-4 strings], closes_at }, tags?, post_at? } |
post_at = scheduled (up to 30 days) |
redream |
{ of: dreamId } |
public Dreams only |
react |
{ of: dreamId, r: "like" } |
v0: like only |
edit |
{ of: dreamId, text, cw?, speak? } |
your own Dreams; history kept |
delete |
{ of: objectId } |
a Dream, react, redream, vote or Chat of yours |
follow / unfollow |
{ who: pubkey } |
|
block / unblock |
{ who: pubkey } |
private; also removes follows both ways |
vote |
{ of: dreamId, choice: index } |
one vote per poll, can change until it closes |
chat |
{ to: pubkey, box: "<NIP-44 v2 payload>" } |
mutuals only, see Chats |
report |
{ of: dreamId | pubkey | chatId, reason, note?, evidence? } |
reasons: spam, bullying, sexual, self_harm, violence, other |
role_answer |
{ invite: roleInviteId, accept: true|false } |
answers an admin/moderator invite |
leave |
{} |
deletes your account and everything you made on this home |
media = { url, alt, mime?, w?, h? }. url must be an image uploaded to this home (POST /media) by you.
alt is required (1-1500 characters). Limits: text 1000 characters, content warning 200, 4 images, 5 MB per image.
altis required on every image. Without it the server answers422 {"code":"alt_required"}.cwis a content warning. Clients show the warning first and hide the rest until it is opened.speakis how the Dream should be read aloud. If it is missing and the text has links or emoji runs, the server addsspeak_hintto items (links become "link to site", runs of 3+ same emoji are counted).- Events carry names a client can attach sounds (earcons) to:
dream.new,reply.new,like.new,redream.new,follow.new,chat.new,alert.mention,role.invite,role.answer. - Clients should never move focus or insert above the reader when something arrives live: show "3 new Dreams" and let the person choose.
Base: https://<home>/rem/v0. JSON in and out. CORS is open (*) so any web client can connect.
Sign-in uses a Bearer token, never cookies. Errors are { "ok": false, "code": "...", "message": "..." };
message is plain English that a screen reader can read as-is.
Discovery: GET /.well-known/looscid (and GET /rem/v0/) gives the protocol, limits, invite rules and paths.
POST /join{ invite, handle, name?, pubkey, age_ok: true, sig }→{ token, expires, me }sigsigns the textrem-join:<home>:<INVITE>:<handle>(sha256 of the UTF-8 text, Schnorr-signed). Handles: 2-20 of a-z, 0-9, _. The owner's handle is reserved (see Owner).POST /auth/challenge{ pubkey }→{ nonce, sign }POST /auth/login{ pubkey, nonce, sig }→{ token, expires, me }wheresigsigns the text insign(rem-login:<home>:<nonce>). Tokens last 30 days; the server keeps only their hash.POST /auth/logout,GET /me
POST /objectsa signed object →{ ok: true, id, seq }(must be signed by the signed-in LooscidID).POST /mediathe image bytes as the body,Content-Type: image/jpeg|png|webp, alt text in theX-Rem-Altheader (URL-encoded); ormultipart/form-datawithfileandalt. →{ media: { url, mime, alt, w, h } }. The server keeps only the image data: location (GPS), camera, dates, XMP and comments are removed. JPEG keeps only its orientation.
Lists are paged: ?before=<next>&limit=20 → { items, next }.
GET /feed/dreamlineDreams and ReDreams from you and people you follow, newest first, no algorithm.GET /feed/discoverpublic Dreams on this home.GET /objects/:id,GET /dreams/:id/thread,GET /dreams/:id/history(original + edits).GET /dreamors/:handle-or-pubkeyand/dreamors/:handle-or-pubkey/dreams.GET /notifications(same as/alerts),POST /alerts/seen.GET /chats,GET /chats/:pubkey(signed, encrypted Chat objects; decrypt on the device).GET /search?q=&type=all|dreams|dreamors,GET /trending(tags and most-active public Dreams, 24 hours).GET /invites,POST /invites→{ code, invite_link }.GET /sync?since=<cursor>every object you made, plus Chats and deletes addressed to you, oldest first →{ objects, cursor, more }. This is how a new device gets everything back: sign in, call/syncfrom 0.GET /exportthe same, as one download.
Items look like { id, by: { pubkey, npub, handle, name, ... }, at, text, cw, speak, speak_hint, media, link, poll, counts: { replies, redreams, likes }, me: { liked, redreamed }, ... }.
Reads need sign-in on this home (it is members-only) unless the home sets public_read.
POST /import { objects: [signed dream objects] } (up to 200 per request). For people who used Looscid on
their device before joining the server. Nothing is uploaded unless the person chooses it in their app.
- Each Dream must be signed by the signed-in LooscidID and keeps its original
at(any past time since 2020). - Same
idalready on the server = skipped (safe to retry). - Replies keep their thread: a Dream with
reply_to(orquote) is imported only when that Dream is already on the server (send parents first; one request is handled in order). Otherwise it comes back inrefusedwith codeparent_missingand stays on the device. It is never turned into a loose Dream. - Imported Dreams appear on the profile in their original time order; they are not pushed into anyone's Dreamline as new.
- A Dream whose images have no alt text is not dropped silently: it comes back in
needs_altand stays inGET /import/flagsuntil the person adds alt text, signs again and imports again, or dismisses it (POST /import/flags/dismiss { id }). - Images must be uploaded with
/mediafirst (so the server can check and clean them).
Answer: { imported: [ids], skipped: [...], needs_alt: [{ id, images, message }], refused: [{ id, code, message }] }.
The Looscid app and this web client save and restore the same backup file (public/js/looscid-backup.js): your profile,
Dreams, replies, Chats, likes, follows, settings and your LooscidID key in one file, locked with a passcode you choose.
Outside: { "looscid_backup": 1, "kdf": { "name": "PBKDF2", "hash": "SHA-256", "iterations": 600000, "salt" }, "cipher": { "name": "AES-GCM", "iv" }, "data" } (base64; AES-GCM 256-bit with additional data looscid-backup-v1).
Inside: { looscid_backup_data: 1, from: "app"|"home", key: { nsec, pubkey }, profile, server, dreams, rem_objects, app, home }.
Nothing is readable without the passcode, and nobody can recover a forgotten one. Restoring on a home signs in with the
key, imports the signed Dreams (/import, original times) and signs follows and likes again with the same key.
wss://<home>/rem/v0/live. Send {"op":"auth","token":"..."} first (within 15 s).
Client → server:
{"op":"sub","streams":["dreamline","discover","alerts","chats"]}(all four by default){"op":"send","ref":"x","object":{...}}same asPOST /objects, answered byokorerrwith the sameref{"op":"ping"}
Server → client:
{"op":"hello","me":{...},"unseen_alerts":3}{"op":"item","stream":"dreamline"|"discover","event":"dream.new"|"reply.new"|"redream.new","item":{...}}{"op":"update","item":{...}}(an edit, a link card arrived, a poll changed),{"op":"remove","id":"..."}{"op":"alert","event":"like.new",...,"alert":{...}}{"op":"chat","event":"chat.new","object":{...}},{"op":"chat_deleted","id":"..."}{"op":"ok",...},{"op":"err","code","message"},{"op":"pong"}
The server pings every 30 seconds. Reconnect with a short delay if the line drops; then fetch the lists again.
- Only between mutuals (you both follow each other), never with someone you blocked or who blocked you, and not if the other person turned Chats off.
- End-to-end encrypted with NIP-44 v2 (the same as Nostr): conversation key from ECDH of the two LooscidIDs, ChaCha20 + HMAC-SHA256, padded.
- The plaintext inside
boxis itself a signed object:{ type: "chat_message", body: { to, text } }signed by the sender. So a person who reports a Chat can attach it asevidence, and moderators can check it is real without being able to read anyone's Chats. - The server stores the locked box so it arrives when the other person is offline. It can see who chats with whom and when, not what they say.
- Invite-only. Each code makes one account. Members earn 3 invites after 7 days (both numbers are settings); the owner, admins and moderators can make more. The home remembers who invited whom.
- 13+ only (a checkbox). No email, phone, birthday or location is asked for or stored. IP addresses are used only in memory for rate limits and never written down.
- Blocks work both ways: no seeing each other's Dreams, replies, follows, mentions or Chats. They are not told.
- Rate limits: 20 Dreams an hour for accounts newer than 7 days (60 after), 50 follows a day, 30 uploads an hour.
- Reports go to the moderators' queue.
owner (one per home), admin, mod, member. Roles are offered, never forced:
- The owner (any role) or an admin (moderator only) calls
POST /mod/action { action: "invite_role", target: handle-or-pubkey, role: "admin"|"mod" }. - The person gets a
role_invitenotification (live, and in/notifications) with the invite id. - They answer with a signed
role_answer { invite, accept }. Accepting grants the role. - The owner can take a role away:
{ action: "revoke_role", target }. Everything is inGET /mod/log.
GET /mod/reports?status=open|resolved,GET /mod/stats,GET /mod/tree(members and who invited them),GET /mod/log.POST /mod/action { target, action, note? }withaction:hide/unhide(a Dream),suspend/unsuspend(an account),revoke_invites,resolve/reopen(a report),invite_role,revoke_role,remove_account(owner only).
The owner's handle (default 2three1y, a setting) is reserved. Nobody gets it by asking: a join with that
handle and no owner code is only written down as a pending claim. The person running the home holds an owner
code (the server keeps only its hash) and binds the handle to a LooscidID:
GET /admin/owner-claims(headerX-Rem-Owner-Code) lists pending claims with their npubs.POST /admin/owner { pubkey: npub-or-hex, name? }(same header) makes that LooscidID the owner. If it is not a member yet, the account is created.replace: truemoves ownership to a new key (for a lost key).- Joining with the owner code as the invite and the owner handle also works, once.
GET /admin/backup(owner token or theX-Rem-Backup-Keyheader): a.tar.gzwith a consistent copy of the database (VACUUM INTO) and all media.
A LooscidID is a Nostr key, so the same person can use both. The bridge (importing old Looscid Nostr notes, mirroring public Dreams out, a read-only Nostr relay on the home) is planned for later and is off in v0.
Federation between homes (/rem/v1/inbox, signed by the sending home), circles, private accounts with follow
requests, mutes, audio Dreams, moving an account to a new key, a Nostr bridge.