# Run a collaboration server

> Start the local Hocuspocus server used by the SuperDoc collaboration example.



Run a local Hocuspocus server when you need to test a complete collaboration room before connecting production authentication and persistence.

## 1. Use the example server [#1-use-the-example-server]

Download or clone the [collaboration example](https://go.superdoc.dev/examples/collaboration) and follow its [installation steps](/editor/collaboration/connect-two-editors#1-start-the-example). It pins Hocuspocus 2.15.3 and includes the server and optional storage hooks.

## 2. Start it [#2-start-it]

```bash
pnpm exec tsx server.ts
```

The example listens on port `1234` and keeps rooms in memory. Restarting the process clears them. With no storage integration, unloading a room after its last editor disconnects also loses its state.

## 3. Connect two editors [#3-connect-two-editors]

Configure the first browser with a Hocuspocus target and `roomMode: 'create'`. After the room exists, open a second browser with the same `documentId` and `roomMode: 'join'`. [Connect two editors](/editor/collaboration/connect-two-editors) walks through the browser setup.

The complete two-browser project is available at [go.superdoc.dev/examples/collaboration](https://go.superdoc.dev/examples/collaboration).

> **Verification target (success)**
>
> Edit the first browser. The second browser should show the change and export a DOCX containing the synchronized text.


## Prepare for production [#prepare-for-production]

### Choose a provider [#choose-a-provider]

Hocuspocus is the local example's default, not a requirement. The document's `collaboration` field accepts these targets through `DocumentCollaborationConfig` in the [preview API](/editor/collaboration/connect-two-editors#configure-your-application):

| `providerType`  | Room and connection                     | Authentication                                  |
| --------------- | --------------------------------------- | ----------------------------------------------- |
| `'hocuspocus'`  | `documentId` and `serverUrl` (or `url`) | `token` or string `params`                      |
| `'y-websocket'` | `documentId` and `serverUrl` (or `url`) | String `params` forwarded to your server        |
| `'liveblocks'`  | `documentId` or `roomId`                | Exactly one of `authEndpoint` or `publicApiKey` |

For Liveblocks, use an authenticated endpoint when access must be checked per room; a public key does not provide that check. Configure the chosen provider's server or service before pointing the editor at it. SuperDoc owns the browser connection and local shared state; pass connection settings, not an external `{ ydoc, provider }` pair.

### Authorize access [#authorize-access]

The minimal server deliberately has no authentication or durable storage. Before deployment, authenticate the WebSocket connection, authorize each room, persist room updates, set connection and document limits, and define backup and recovery behavior in the server layer.

[Control access to a room](/editor/collaboration/control-room-access) demonstrates credential validation and per-room permission checks. Your server owns authorization; browser controls and display identity do not enforce it.

### Initialize the document [#initialize-the-document]

[Initialize a shared document](/editor/collaboration/initialize-a-document) explains who imports the DOCX, when to create or join, and how browser and backend initialization differ. The Hocuspocus server transports and stores shared state; it does not import the DOCX itself.

### Persist the room separately from DOCX files [#persist-the-room-separately-from-docx-files]

[Save and restore a room](/editor/collaboration/save-and-restore-a-room) shows how to store binary Yjs state, restart the server, and reopen with edits intact. It also explains why DOCX exports and presence are separate from room storage.

If your application starts with a local document, [upgrade it to collaboration](/editor/collaboration/upgrade-a-document) when someone invites another person to edit.