For AI agents: a documentation index is available at https://www.plungeai.com/docs/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. Setup instructions for agents are at https://www.plungeai.com/docs/agents.md. One ozk_ key opens every plane, models included.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.
Feedback

The real-time hub of the PlungeAI platform: one Rust Worker (wss://realtime.plungeai.com) that speaks Supabase Realtime's wire protocol (broadcast, presence, postgres_changes; phoenix vsn 1.0.0 and 2.0.0). The official supabase-js and @supabase/realtime-js clients connect to it unchanged. Your data lives in an Ocean Base database (base.plungeai.com); its row changes and its messages reach your app through this hub.

Each Ocean Base database has its own hub, as each Supabase project has its own Realtime. You connect with the database's publishable key, your users sign in with Ocean Base, and the database's YAML holds the settings and the create policy statements of its private channels. Where Ocean Realtime differs from Supabase, PARITY.md here lists every difference and the live gate that proves each feature.

Ocean Realtime is the platform's WebSocket service for apps; there is no separate one. A client opens one WebSocket (wss://realtime.plungeai.com/realtime/v1/websocket), joins channels on it, and sends and receives broadcast, presence and row changes. An app that only wants a socket for its own messages joins a channel and uses broadcast.

Connect with a publishable key

Every Ocean Base database has one publishable key (obp_…), shown when the database is created and on the console. It may sit in a browser or an app. Give supabase-js the hub's address as the project URL and the publishable key as the anon key:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://realtime.plungeai.com', process.env.OCEAN_PUBLISHABLE_KEY)

supabase
  .channel('lobby')
  .on('broadcast', { event: 'cursor' }, ({ payload }) => console.log(payload))
  .subscribe()

Only the realtime part of supabase-js is served here: .channel(), .realtime, .removeChannel(). Rows, auth and files are Ocean Base's own routes.

@supabase/realtime-js works the same way (2.101.1 and 2.119.0 are the versions the gates run):

import { RealtimeClient } from '@supabase/realtime-js'

const rt = new RealtimeClient('wss://realtime.plungeai.com/realtime/v1', {
  params: { apikey: process.env.OCEAN_PUBLISHABLE_KEY },
  vsn: '2.0.0', // or '1.0.0'
})

The key may also come in the x-api-key header, which wins over apikey= as on Supabase. The socket URL carries the key; the hub never logs it.

Credentials

The credential is read once, when the socket opens:

You sendYou areUse it from
apikey=obp_…, the database's publishable keyanonymous, in that database onlya browser or an app
the publishable key, and an end user's obu_… session as the channel's token (supabase-js's accessToken option)that end usera browser or an app
apikey=obt_…, a database tokenthe database's service role (a read token cannot send, track or persist)your own server
an org's ozk_… key, or the console's cookie, with db=<database id or name>the database's service roleyour own server, the console

The service role is not judged by policies: it may join, read and send on every topic of the database. With realtime-js, db= is a parameter beside the key: params: { apikey: process.env.PLUNGE_API_KEY, db: 'shop' }.

A socket without any credential is refused 401 before the upgrade. A rotated publishable key, a revoked token or a deleted database stops opening new sockets within about 60 seconds; the hub re-checks connected sockets every 5 minutes and closes those whose key no longer works. When Ocean Base cannot be reached the upgrade answers 502 (asking Ocean Base failed; try again), never 401, so a client keeps its good key.

End users

An end user signs in with Ocean Base (email code, Google, GitHub, Apple, or anonymously) and gets a session obu_…, valid 30 days. Ocean Base's guide (ocean-code/base/README.md, "End users") has the sign-in routes. Hand the session to the realtime client with supabase-js's accessToken option:

const supabase = createClient('https://realtime.plungeai.com', process.env.OCEAN_PUBLISHABLE_KEY, {
  accessToken: async () => session, // the obu_… string Ocean Base returned
})
await supabase.realtime.setAuth() // once, before the first subscribe: supabase-js does not wait for its first read

Not supabase.realtime.setAuth(session): from supabase-js 2.119.0 on, a token set that way holds only until supabase-js's next token refresh, which puts the publishable key back in the session's place. With the accessToken option supabase.auth is not usable on that client, which is right here: sign-in is Ocean Base's. On a bare @supabase/realtime-js RealtimeClient, rt.setAuth(session) stays the way.

Each channel then carries it as its access_token. Without a session a channel is anonymous: supabase-js sends the publishable key itself as the token when nobody is signed in, and the hub reads that as anonymous too. A session that Ocean Base does not know refuses the join. When the user signs out or the session ends, the hub closes that user's channels at its next 5-minute check (The token provided is not a valid JWT).

Broadcast

Send and receive messages on a topic, as on Supabase:

const room = supabase.channel('lobby', { config: { broadcast: { self: true, ack: true } } })
room
  .on('broadcast', { event: 'cursor' }, ({ payload }) => console.log(payload))
  .subscribe(async (status) => {
    if (status !== 'SUBSCRIBED') return
    const answer = await room.send({ type: 'broadcast', event: 'cursor', payload: { x: 1, y: 2 } })
    console.log(answer) // 'ok', or the ack's error
  })

self sends your own messages back to you; ack makes send() wait for the hub's answer. On vsn 2.0.0 a payload may be bytes. An acked send answers payload_size_exceeded when the payload is over the database's max_payload_kb, and unauthorized when the channel may not send (a private topic without the insert policy). A message's meta.id, when it has one, is its id.

Topics

A channel's name is its topic (realtime: is added by the client): printable ASCII, at most 255 bytes. A public topic is open when the database's YAML lists it under channels:: an exact name (lobby), a prefix (room:* matches room:42), or "*" for every topic. A public topic that is not listed can be joined for row changes only; a join asking broadcast or presence on it is refused:

Unauthorized: <topic> is not listed in the schema's channels:. Join it with private: true, or add it to channels:

A private topic is any Ocean Base topic name (1 to 100 of a-z, 0-9, _, : and -, starting with a letter or digit); its policies decide who may join. Public and private are two rooms of one topic: a message sent on the public room:1 never reaches the private room:1, as on Supabase.

Presence

const room = supabase.channel('room:1', { config: { presence: { key: userId } } })
room
  .on('presence', { event: 'sync' }, () => console.log(room.presenceState()))
  .subscribe(async (status) => {
    if (status === 'SUBSCRIBED') await room.track({ name: 'Ada' })
  })

The first track on a channel joined without presence turns presence on and sends you the presence_state; a track identical to the last one changes nothing; a payload that is not an object is refused (Presence track payload must be a map). A tracked meta is at most 2 KB: a larger one closes the channel with Track message size exceeded.

Row changes

Every committed change of an Ocean Base database reaches its hub. Subscribe with postgres_changes, as on Supabase; the schema is public (the database's name, its id and * mean the same here), the table is the collection:

supabase
  .channel('posts-feed')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'posts', filter: 'title=eq.hello' }, (c) => {
    console.log(c.eventType, c.new, c.old)
  })
  .subscribe()
  • event is INSERT, UPDATE, DELETE or *; table absent or * is every collection. Up to 20 bindings a channel. select: ['id', 'title'] keeps only those columns (and the primary key) in new, old and columns.
  • After the join a system message says Subscribed to PostgreSQL. A binding that does not parse leaves the join ok, sends one system error naming it, and that channel then gets no row changes. With postgres_changes_options: { wait: true } such a join is refused instead.
  • A change too large arrives cut: past 1,048,576 bytes only its fields of at most 64 bytes are kept, with errors: ["Error 413: Payload Too Large"]. Read the row from Ocean Base.
  • Delivery is at most once, in commit order. To catch up after a disconnect, read Ocean Base's GET …/changes?since=<the last seq you saw>.

Filters

filter is Supabase's: column=operator.value with eq, neq, lt, lte, gt, gte, in (id=in.(1,2,"a b"), at most 100 values), like, ilike, match, imatch (a regular expression), is (null, true, false, unknown) or isdistinct, any of them negated with not. (status=not.eq.done), several joined by commas as AND, a value with a comma or a parenthesis in double quotes. eq.null compares with the text null; use is.null. Filters apply to DELETE too, on the old row.

Pattern filters (like, ilike, match, imatch) never look at a value over 65,536 bytes. Their work is budgeted, 100 ms a change and 1 s a commit, shared among the sockets that hold them. When a channel's pattern filters run over their share, the rows they could not judge are not sent, never sent by mistake, and the channel gets one system error for that commit (Row changes were skipped: …); it stays joined. match and imatch use the regex-lite flavour: ASCII character classes and ASCII case folding.

Access to rows

Each change is judged against its collection's access: before it is sent:

AccessWho receives the row's changes
ownerthe end user the row's owner names, and the service role
public-readanyone connected to the database, anonymous included
privatethe service role only

An UPDATE that takes a row out of a subscriber's view arrives as a DELETE with only the primary key; one that brings it into view arrives as an INSERT. Policies decide channels, never rows.

Private channels and policies

A private channel is joined with private: true. Who may join it, send on it and track presence on it is decided by create policy statements on realtime.messages, the same statements a Supabase migration writes, kept in the database's YAML under realtime.policies. This database lets a user read, send and track presence on a room when a rooms_users row makes the user a member of it:

kind: database
name: chat
collections:
  rooms_users:
    access: private
    columns: {user_id: text required, room_topic: text required}
    indexes: [user_id, room_topic]
auth:
  methods: [anonymous]
channels: [lobby, "room:*"]
realtime:
  enabled: true
  policies:
    - |
      create policy "authenticated can listen to broadcast and presence on topic"
      on "realtime"."messages"
      for select
      to authenticated
      using (
        exists (
          select
            user_id
          from
            rooms_users
          where
            user_id = (select auth.uid())
            and room_topic = (select realtime.topic())
            and realtime.messages.extension in ('broadcast', 'presence')
        )
      );
    - |
      create policy "authenticated can send broadcast and presence on topic"
      on "realtime"."messages"
      for insert
      to authenticated
      with check (
        exists (
          select
            user_id
          from
            rooms_users
          where
            user_id = (select auth.uid())
            and room_topic = (select realtime.topic())
            and realtime.messages.extension in ('broadcast', 'presence')
        )
      );

The member's client carries the session (End users) and joins with private: true:

const supabase = createClient('https://realtime.plungeai.com', process.env.OCEAN_PUBLISHABLE_KEY, { accessToken: async () => session })
await supabase.realtime.setAuth()
const room = supabase.channel('room:42', { config: { private: true, broadcast: { ack: true, self: true } } })
room.on('broadcast', { event: 'note' }, ({ payload }) => console.log(payload)).subscribe()
  • What a policy says. for select lets a client receive (broadcast, presence), for insert lets it send and track, for all both. realtime.messages.extension is broadcast, presence or persistence (the last decides whether a send may be stored, below). to anon is a client without a session, to authenticated any end-user session (anonymous sign-ins included), to public both, the default. Permissive policies (the default) are OR'ed, as restrictive ones AND'ed, and no permissive policy that applies means denied. for update and for delete are refused: Realtime never reads them.
  • What a condition may use. Ocean Base's SQL over the database's own tables, with realtime.topic(), auth.uid(), auth.role(), auth.jwt() (sub, role, email, is_anonymous, user_metadata) and realtime.messages.topic / .extension. A public. before a table name is dropped. Postgres-only syntax (::json, ~~, current_setting(…)) is refused when the YAML is applied, with the fix: write (auth.jwt() ->> 'email') like '%@example.com'. Each policy runs once on an empty copy of the declared tables when the YAML is created or applied, so an unknown table or column fails the apply, not a join. At most 20 policies, each at most 2,000 bytes.
  • When it is judged. At a private join the hub asks Ocean Base once; the database runs the caller's policies read-only and answers five grants: broadcast read, write and persist, presence read and write. They hold for the channel's life and are judged again on a new token. A join without broadcast read is refused: Unauthorized: You do not have permissions to read from this Channel topic: room:42. A new token that loses read closes the channel: You no longer have permission to read from this Channel topic: room:42. When the policies change, the hub judges every joined private channel again from its next sweep, taking at most 60 seconds; a socket it cannot judge in that time is closed 1012 and reconnects.
  • What it costs. Each private join runs the caller's policies as one read batch on the database, and a session is checked once per join: both are billed to the database as reads.
  • When Ocean Base cannot answer, the join is refused with UnableToConnectToProject: Realtime was unable to connect to the project database; the socket and its other channels stay.
  • With realtime.public_channels: false every public join is refused: PrivateOnly: This project only allows private channels.

The console's Realtime page has an access check that shows the five grants a given end user, or an anonymous client, would get on a topic, without signing in as that user.

Broadcast from the database

Supabase sends messages from the database with a trigger (realtime.broadcast_changes) or with realtime.send in a transaction. Ocean Base has no triggers; it offers the same two another way.

A broadcast: rule under a collection sends one message for each change:

collections:
  feed:
    access: private
    columns: {room: text required, body: text}
    broadcast:
      - topic: "feed:{room}"

The payload is Supabase's: {id, schema: "public", table, operation, record, old_record}; the event is INSERT, UPDATE or DELETE (or the rule's event:). A rule is private by default (only listeners the policies admit), may name on: [insert, update, delete], and a collection has at most 5. A public rule (private: false) is accepted only on a public-read collection. Ocean Base's guide has the whole rule.

A broadcast op in a batch is sent only if the batch commits, as realtime.send in a transaction:

curl -s -X POST https://base.plungeai.com/v1/databases/$DB/ops -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H "Content-Type: application/json" -d '{"ops": [
    {"op": "rows_insert", "collection": "messages", "row": {"room_id": 7, "body": "hi"}},
    {"op": "broadcast", "topic": "room:7", "event": "typing", "payload": {"who": "ana"}}]}'

private defaults to true; "binary": "<base64>" in place of payload sends bytes, which vsn 2.0.0 listeners receive as a binary broadcast. A batch that fails or rolls back sends nothing. Ocean Base's broadcast route (POST …/channels/<topic>/broadcast) takes JSON or application/octet-stream and private too.

Replay and persisted sends

A database's hub keeps, for 72 hours, the private messages that come from the database (rules, the batch op and the broadcast route) and the sends a client asks to persist. Each carries meta.id. A private channel joined with replay and broadcast read gets up to 25 of them, oldest first, each with meta.replayed: true, right after its join reply:

const room = supabase.channel('feed:42', {
  config: { private: true, broadcast: { replay: { since: Date.now() - 3_600_000, limit: 25 } } },
})

since is a time in milliseconds; limit is held to 1 to 25. A public channel with replay is refused (UnableToReplayMessages: Replay is not allowed for public channels).

A client's send is stored when it asks and a persistence policy allows it:

await room.send({ type: 'broadcast', event: 'note', payload: { text: 'hi' }, persist: true })

persist: true keeps it 72 hours, persist: { ttl: <seconds> } from 1 to 259,200 seconds. Without the persistence grant the ack answers persistence_unauthorized and nothing is stored. A persisted send needs vsn 2.0.0 (realtime-js 2.119.0 sends it). A policy that allows persisting on one topic:

create policy "persist on keep-1"
on "realtime"."messages"
for insert
to authenticated
with check ((select realtime.topic()) = 'keep-1' and realtime.messages.extension in ('persistence'));

A message from the database that arrives while the events rate is over its limit, or past max_payload_kb, is stored and not delivered live; it is still replayed.

REST broadcast

Two routes, as Supabase's, both answering 202 and both callable from a browser (CORS):

  • POST /realtime/v1/api/broadcast with {"messages": [{"topic", "event", "payload", "private"?, "id"?}]} (realtime-js's httpSend in 2.101.1, and send() before a channel has joined). A message that may not be sent (a private topic without the insert policy, a public topic channels: does not list) is skipped.
  • POST /realtime/v1/api/broadcast/<topic>/events/<event> with one message: a JSON object (application/json) or bytes (application/octet-stream, a binary broadcast for vsn 2.0.0 sockets); ?private=true, ?id=<uuid>, ?persist (stored with the persistence grant). Another content type is 415, JSON that is not an object 422.

The credential is Authorization: Bearer, the apikey header or x-api-key. In database scope it is the publishable key, a database token, or an obu_ session as the bearer with the publishable key as apikey. From realtime-js, channel.httpSend(event, payload) uses them for you:

const room = supabase.channel('room:42', { config: { private: true } })
const answer = await room.httpSend('note', { text: 'hi' })
console.log(answer.success)

Settings and limits

Each database's hub follows the realtime: block of its YAML. Every key is optional; the defaults are Supabase's Free plan, the maxima its Team plan:

SettingDefaultRangeWhat a client sees past it
enabledtruefalse: the upgrade answers 403 Realtime was disabled for this tenant; a join RealtimeDisabledForTenant: Realtime disabled for this tenant; REST 403 Tenant is suspended
public_channelstruefalse: a public join is refused PrivateOnly: This project only allows private channels
max_clients2001 to 10,000the upgrade answers 429 Too many connected users. Above 2,000 the database is spread over up to five hubs of 2,000 sockets each (one more per 2,000 asked for); clients notice nothing
max_events_per_second1001 to 2,500every channel of the database that receives the next broadcast gets it and is then shut down with a system error Too many messages per second, whoever sent it; a commit's row changes are dropped whole, with no signal; REST 429 You have exceeded your rate limit
max_joins_per_second1001 to 2,500the join is refused ClientJoinRateLimitReached: Too many joins per second and the socket is closed; past it at the upgrade, 429 Too many joins per second
max_presence_events_per_second201 to 1,000the channel is shut down: Too many presence messages per second. A database spread over several hubs gives each hub an equal share, so presence bunched in one hub reaches its share first
max_channels_per_client1001 to 100the join is refused ChannelRateLimitReached: Too many channels
max_payload_kb2561 to 3,000the message is sent to no one and the ack answers payload_size_exceeded; REST 422 {errors: {payload: ["Payload size exceeds tenant limit"]}}

Also, in every database:

  • 5 presence calls per 30 seconds per channel; past it the channel is shut down: Client presence rate limit exceeded.
  • A frame is at most 5,000,000 bytes (else the socket is closed 1009). Each socket sends at most max(60, max_events_per_second) frames and max(64 KB × 60, 2 × max_payload_kb × 1,000) bytes a second (else 1008).
  • A message whose bytes times its recipients pass 64 MiB is refused before it is sent to anyone (REST 422).
  • REST requests are held to max_events_per_second requests a second, over a rolling minute: every REST answer carries x-rate-limit, x-rate-limit-remaining and x-rate-rolling, and a refusal is 429 Too many requests. Each message a REST call sends counts one event.
  • 60 seconds of silence closes a socket (realtime-js heartbeats every 25 seconds); a socket with no joined channel for 10 minutes is closed 1001 No channels joined.
  • A change to the realtime: block or to channels: closes the database's sockets with code 1012; the clients reconnect and rejoin.

Over max_events_per_second realtime-js reports the channel CLOSED and does not rejoin it: subscribe again. While the rate is still over, the next broadcast closes it again.

A join refusal is Code: message, Supabase's codes and texts; an HTTP refusal is {"error": …, "message": …}.

Usage and metering

The hub counts, per database and UTC day, the messages it handled (each broadcast sent and each delivery, each presence diff and sync, each row change delivered) and the most sockets connected at once. Ocean Base stores each day's figures at 02:00 UTC the next morning; GET /v1/databases/<id>/usage shows messages and peak_connections per day and today's live count (realtime_today). Messages carry the proposed rate of Ocean Base's other meters; peak connections are shown and never billed. Ocean Base's meters have no rate on the platform's rate card today, so nothing is charged.

The console and the inspector

The console (https://base.plungeai.com, signed in with your PlungeAI account) has a Realtime tab for each database (/d/<database>/realtime): clients and channels now, the busiest topics, the last hour minute by minute, today's messages and peak, the hub's recent events, the settings in force and the policies, the access check, and a live feed that joins any topic of the database as the service role, shows every frame and sends a broadcast.

On the command line, ocean-code/realtime/tools/inspect.mjs joins one topic and prints every frame in and out as one JSON line. Run node ocean-code/realtime/tools/inspect.mjs --help. The credential is never an argument: a file of mode 600 or the OCEAN_KEY environment variable.

node ocean-code/realtime/tools/inspect.mjs --key-file ~/.ocean/ozk.key --topic orders \
  --changes 'shop.orders:status=eq.open' --presence --for 60

That joins orders in the org's hub with an ozk_ key. --db <id or name> joins a database's hub instead: with --publishable-file alone it is anonymous, with --session-file too that end user, with OCEAN_KEY or --key-file (a database token, or an ozk_ key) the service role. --private joins a private channel, --send <event> <json> broadcasts once after the join and prints the ack, --for <seconds> stops after that long.

GET https://realtime.plungeai.com/health answers the hub's version; GET /health/deep makes a round trip through a hub and answers {"ok": true, "version": …, "hub_ms": …}. A socket opened with log_level=info, warn or error gets its joins, refusals and closes logged in the hub's Worker logs; nothing of a payload, key or token.

The org scope

The platform's own apps connect to their org's hub instead of a database's: with an org's ozk_ key (a server), a PlungeAI access token from https://signin.plungeai.com (scope api), or the auth-session cookie from a *.plungeai.com page. org=<org id> picks another org you belong to. There a topic user:<id>:… is that person's, team:<id>:… that team's members', anything else open to the org; private: true is recorded and both kinds share one room. A row change names its database by name in schema (or * for every database of the org), and the collection's access: decides as in a database's hub. A database's public broadcast is heard there on <database name>:<topic>.

curl -s -X POST https://realtime.plungeai.com/realtime/v1/api/broadcast/lobby/events/news \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H "Content-Type: application/json" -d '{"text": "deploy done"}'
Limit (org scope)Value
Sockets per org2,000 (the upgrade answers 503 past it)
Channels per socket100
Frame size64 KB (a larger one closes the socket, code 1009)
Frames per second per socket60 (more closes it, code 1008)
Presence state2 KB per meta
REST broadcast100 messages and 1 MB per call

A change too large for a 64 KB frame arrives cut to its primary key. Cookie sockets close after 60 minutes with code 4001 and realtime-js reconnects.

What is different from Supabase

The full list, each with Supabase's behaviour, ours and why, is PARITY.md here. In short:

  • Credentials are Ocean Base's: a publishable key, an opaque obu_ session (not a JWT), a database token or an org key as the service role.
  • A public topic must be listed in channels: ("*" lists every topic).
  • Policy conditions are Ocean Base's SQL, not Postgres; Postgres-only syntax is refused at apply. Rows follow their collection's access:, not policies.
  • A presence meta is at most 2 KB. Frames, byte rates and fan-out have Ocean's own bounds.
  • A join value of the wrong type refuses the join instead of falling back to the default.
  • Broadcast from the database uses broadcast: rules and a batch op instead of triggers and realtime.send().
  • Messages are kept in the hub, 72 hours. Every hub runs in San Jose.
  • One hub takes at most 2,000 sockets; a database takes up to 10,000, over up to five hubs (measured on production: 10,000 sockets, a delivery across hubs in p95 163 ms). A hub deploy cuts the sockets of busy hubs 300 s later; realtime-js reconnects and rejoins on its own (measured: all 10,000 joined again within 10 s). The rates in Settings and limits are shared evenly by a database's hubs.
  • Cloudflare's edge sometimes cuts held WebSockets when it restarts a server (code 1006, nothing reaches the hub); the hub then holds the socket for its 60 s silence, so a database at max_clients answers that client's reconnect 429 for up to a minute. Supabase holds a vanished socket 60 s too.
  • The tested clients are JavaScript, Python and Rust.

Planned: TI-34

The docs assistant is not available yet. You can hand these docs to your own assistant instead.