Docs Node, Bun & Deno

Running in Node, Bun & Deno

Trystero runs in server and CLI JavaScript runtimes using the same room API as the browser. Common uses include keeping a passive: true backup peer online to retain signed room state when no browsers are open, running an automated game host or bot, and bridging local hardware or MIDI devices into a room.

Setup

Node 22+, Bun, and Deno provide global WebSocket and Web Crypto APIs, so you only need to pass an RTCPeerConnection implementation such as werift via rtcPolyfill.

npm i trystero werift
import {joinRoom} from 'trystero'
import {RTCPeerConnection} from 'werift'

const room = joinRoom(
  {appId: 'oedipa/hardware-synth', rtcPolyfill: RTCPeerConnection},
  'patch-bay-1'
)

const note = room.makeAction('midi-note')
note.onMessage((data, {userId}) => {
  console.log(`Note ${data.pitch} from ${userId}`)
  midiOut.send([0x90, data.pitch, data.velocity])
})

State backup with passive: true

In browser-only rooms, makeState values persist as long as at least one participant tab stays connected. To preserve shared state across periods when all browser tabs close, run a passive peer declaring the same namespaces:

import {joinRoom} from 'trystero'
import {RTCPeerConnection} from 'werift'

const room = joinRoom(
  {
    appId: 'poetry.example.com',
    rtcPolyfill: RTCPeerConnection,
    passive: true
  },
  'kitchen'
)

// Register the namespaces this backup peer should verify, cache, and sync
room.makeState('magnets', {words: []})
  • Quiet on relays. Passive peers listen for active peers without broadcasting presence announcements, so multiple passive instances never connect to one another.
  • Unprivileged caching. Because state records carry their authors' ECDSA signatures (and role certificates when roles() is active), a passive peer can verify, store, and serve state to late joiners without holding admin rights itself.
  • Presence-scoped user state. Browser users' makeUserState slots are still evicted normally when those users disconnect.

Persisting a server userId

Outside browsers, identity defaults to 'none', generating a new ephemeral userId on each process start. If your server peer acts as a room admin or needs a stable identity across restarts, generate an identity once, store its exported trystero_uk_… string in an environment variable or secret file, and import it on boot:

// 1. Run once to generate a secret key for your environment or secret store
import {createUserIdentity, exportUserIdentity} from 'trystero'

const id = await createUserIdentity()
console.log('BOT_USER_ID=', id.userId)
console.log('BOT_SECRET_KEY=', exportUserIdentity(id))
// 2. Import that identity when the server peer starts
import {joinRoom, importUserIdentity, roles} from 'trystero'
import {RTCPeerConnection} from 'werift'

const botIdentity = await importUserIdentity(process.env.BOT_SECRET_KEY)

const room = joinRoom(
  {
    appId: 'oedipa/trivia-night',
    identity: botIdentity,
    rtcPolyfill: RTCPeerConnection,
    use: [roles({selfAsAdmin: true})]
  },
  'nightly-quiz'
)

const {roomId} = await room.getSelf()
console.log(`Players join room: ${roomId}`)

Treat BOT_SECRET_KEY as a private signing key. The derived 22-character userId is public and safe to embed in client code via roles({admins: [BOT_USER_ID]}).

Runtime behavior

  • Passive signaling. On pub/sub strategies (Nostr, MQTT, ws-relay, Supabase, Firebase), passive rooms subscribe to the room topic and their own inbox without publishing announcements, replying only when active peers announce. On BitTorrent, passive rooms register as seeders without generating outbound offers.
  • Clean process exit. await room.leave() sends leave notices, closes peer connections, and tears down shared relay sockets once the last active room exits so scripts terminate without calling process.exit().