Concepts
Organizations, realms and handles
The objects you work with: the organization that pays, the realms that isolate apps, and the handles people and agents carry.
Organization#
The organization is the billing unit: one plan, one invoice, one team. Everything you use is counted per organization across all of its realms. Members manage it in the Console; there are no seat prices.
Realm#
A realm isolates one app or environment: its own keys, its own handles and its own rooms. Realms are free to create, so give production, staging and each separate product its own. A realm id is permanent once created; its display name and branding can change.
Every stream in a realm lives under realm/<realm-id>/…. The SDK adds that prefix for you, and the relay refuses a key from one realm in another.
Identity, DID and handle#
Every person and agent is an identity: a did:key that never changes, and a handle people can read and change. The global handle is @alice; inside your realm the same person can be @alice.acme. Renaming a handle keeps the DID, so nothing you stored breaks.
| Form | Where | Meaning |
|---|---|---|
@alice | OpenPulse | A person’s own handle, claimed at openpulse.org |
@alice.acme | Your realm | The same kind of identity, scoped to the realm acme |
did:key:z6Mk… | Everywhere | The stable id you store; handles point to it |
Tenant#
If one realm serves many customers (workspaces, teams, accounts), each is a tenant. A person’s seat lists the tenants they may reach, and the same room name in another tenant is another room. See tenants and seats.
Streams and presets#
Everything live is a stream: an ordered log of events with a sequence number, kept for a while so readers can resume. A preset tells the relay how to treat it. You rarely name one; the SDK picks it:
| Preset | Used by | Behaviour |
|---|---|---|
chat | pulse.chat() | Durable conversation messages |
llm_agent_run | pulse.run() | One AI answer: start, chunks, end |
ephemeral_ui_stream | pulse.presence() | Cursors, typing, who is here; latest state wins |
api_event_stream | pulse.events(), pulse.stream() | Fan-out events and wakes |
collab_crdt_stream | @openpulse/sdk/bind | Shared documents (Yjs) |
Keys#
A realm key (opw1.…) is minted in the Console with the capabilities it needs (for example send and observe) and belongs on servers. Browsers and agents get short-lived tokens from it: seats for people, device assertions for agents.