Deploy and Host Hocuspocus on Railway

Hocuspocus is the open-source Yjs collaboration backend from the Tiptap team. This template deploys a ready-to-use Hocuspocus 4.7 server: editors and agents connect over WebSocket, sync Yjs documents in real time, and documents persist on a volume. The access token is generated for you, so nothing needs filling in.

About Hosting Hocuspocus

The image is a small wrapper (source: github.com/bon5co/hocuspocus-railway) around the official @hocuspocus/server package, pinned by digest. It adds what a hosted server needs: token authentication on every connection, SQLite persistence of each document under /data, and a /health endpoint. It runs as a single process.

Why Deploy Hocuspocus on Railway?

No manual step: the token is generated, port and health path are wired up.
Public HTTPS and WSS endpoint out of the box.
Documents survive redeploys because the volume is already mounted.
Connections are authenticated from the first message.

Common Use Cases

Real-time collaborative text editors built on Tiptap, ProseMirror, Quill or Monaco.
Shared state between AI agents and humans in the same document.
Multiplayer whiteboards, notes and forms built on Yjs.
Self-hosted replacement for Liveblocks or Tiptap Cloud collaboration.

Dependencies for Hocuspocus Hosting

Deployment Dependencies

Image: ghcr.io/bon5co/hocuspocus-railway (Hocuspocus 4.7.1, Yjs 13.6.33)
Docs: https://tiptap.dev/docs/hocuspocus
Volume mounted at /data (SQLite database).

Machine-readable contract

service: hocuspocus
base_url: https://
health: GET /health -&gt; 200 {"status":"ok","documents":N}
websocket: wss:///   (HocuspocusProvider option token = HOCUSPOCUS_TOKEN; document name = provider name)
credential_variables:
  HOCUSPOCUS_TOKEN  (wrong token -&gt; authentication failed)
optional_variables:
  HOCUSPOCUS_DB     (SQLite path, default /data/hocuspocus/db.sqlite)
volume: /data

Check health:

curl https:///health

Connect a client:

import { HocuspocusProvider } from "@hocuspocus/provider";
import * as Y from "yjs";
const doc = new Y.Doc();
new HocuspocusProvider({ url: "wss://", name: "my-document", document: doc, token: "" });
doc.getText("t").insert(0, "hello");