yserve

Overview ¶

Command yserve is a self-hosted Yjs sync server in a single static binary: a drop-in replacement for a Hocuspocus deployment with no Node runtime, no Redis, and no CGO.

It speaks the Hocuspocus message envelope (Sync, Awareness, QueryAwareness, Auth, Stateless, BroadcastStateless, Close, SyncStatus), so existing @hocuspocus/provider and y-websocket clients connect unchanged. SQLite persistence and periodic document versioning are built in.

Usage:

yserve [-addr :8080] [-store path/to/ygo.db]
       [-version-interval 10m] [-keep-versions 10]
       [-read-limit BYTES] [-awareness-timeout 30s]
       [-max-awareness-clients 4096]

Without -store the server runs purely in-memory; documents are lost when their last connection disconnects. With -store every applied update is persisted to a pure-Go SQLite database and document history is loaded on first connect after a restart.

With -version-interval > 0 (requires -store), every document that changed since the previous interval is captured as a named version; -keep-versions bounds the history per document (0 keeps everything). Versions survive log compaction and can be listed, loaded, and restored programmatically via the persist package.

-read-limit raises the maximum WebSocket frame size the server will read (default 32 KiB); raise it for large documents whose sync frame exceeds the default, or pass -1 for unlimited. -awareness-timeout and -max-awareness-clients tune the presence layer's silent-client eviction window and per-room client cap.

Mount point: documents are addressed by the URL path. A client connecting to ws://host:8080/my-doc operates on docName "my-doc", matching y-websocket's convention.