# Running the engine on a server

> Serve typstream's engine protocol over WebSocket with @typstream/node, so browsers render live previews without downloading the 6 MB compiler, and connect the browser client to it.

Source: https://typstream.vercel.app/docs/guides/remote-engine

By default each browser runs Typst itself, in a worker: a 6.2 MB download (brotli) before the first preview. `@typstream/node` can run the engine on your server instead and serve the same protocol over WebSocket. The browser still heals the stream and renders the result; only compiling moves to the server.

Consider it for devices too slow or too constrained for the wasm engine, or for pages that show a document once and don't justify the download. The cost is a round trip per compile and compile time on your servers.

<Callout type="warn" title="Beta">
  The browser client, `fromWebSocket`, is beta and may change before the first stable release. Switching from server previews to the local engine once its download finishes isn't built yet.
</Callout>

## Serve the protocol

```npm
npm install @typstream/node ws
```

```ts title="server.ts"
import { WebSocketServer } from "ws";
import { createProtocolServer, handleWebSocket } from "@typstream/node";

const server = createProtocolServer({ timeouts: { streaming: 3_000, final: 10_000 }, maxDocuments: 32 });

new WebSocketServer({ port: 8080, maxPayload: 8 << 20 }).on("connection", (ws) => handleWebSocket(ws, server));
```

`createProtocolServer` runs `@typstream/engine`'s protocol server, the same code that runs in the browser worker, over an adapter that compiles on `@typstream/node`'s worker pool. `handleWebSocket` attaches one socket to it; anything with `ws`'s `on`, `send` and `close` works.

To share a port with your HTTP server and decide who may connect, handle the upgrade yourself. typstream doesn't authenticate connections:

```ts title="server.ts"
import { createServer } from "node:http";
import { WebSocketServer } from "ws";
import { createEngine, createProtocolServer, handleWebSocket } from "@typstream/node";

const engine = createEngine({ workers: 4 });
const typst = createProtocolServer({ engine });
const wss = new WebSocketServer({ noServer: true, maxPayload: 8 << 20 });

const http = createServer(app); // your app's request handler
http.on("upgrade", (req, socket, head) => {
  if (req.url !== "/typst" || !isSignedIn(req)) {
    socket.destroy();
    return;
  }
  wss.handleUpgrade(req, socket, head, (ws) => handleWebSocket(ws, typst));
});
http.listen(3000);
```

The options:

### ProtocolServerOptions

Limits and identity for createProtocolServer; every connection gets the same.

| Prop             | Type                                                   | Description                                                                                                           |
| ---------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `engine?`        | `NodeEngine \| undefined`                              | Default: defaultEngine.                                                                                               |
| `timeouts?`      | `{ streaming?: number; final?: number; } \| undefined` | Watchdog budget per compile by `mode`, in ms; exports are `final`. Default 3,000 streaming, 10,000 final (PLAN §6.3). |
| `maxDocuments?`  | `number \| undefined`                                  | Open documents per connection. Default 32.                                                                            |
| `maxTextLength?` | `number \| undefined`                                  | Longest `/main.typ` (preamble and text), in UTF-16 code units. Default 1,000,000 (PLAN §9).                           |
| `serverInfo?`    | `{ name?: string; version?: string; } \| undefined`    | Reported in `initialize`'s `serverInfo`.                                                                              |

The engine's own options (workers, fonts, the default budget) are `createEngine`'s; see [Validating and repairing on the server](/docs/guides/server-fix-loop#the-engine). One engine can serve the protocol and your `validate` and `render` calls at the same time.

## What the server offers

| | |
|---|---|
| Targets | HTML, and paged with changed-page updates (only pages whose content changed are sent). |
| Exports | PDF and HTML: `doc.exportPdf()` and `doc.exportHtml()` work over the connection. |
| Fixers and fallback | The built-in fixers and the fallback ladder run on the server, as they do in the browser worker. |
| Fonts | The server engine's: Typst's bundled fonts and the script fonts, plus any you give `createEngine`. Fonts a client sends are ignored. |
| Packages | None by default. The server ignores the package lists clients send (see below) and has no allowlist of its own, so `#import "@preview/…"` reports that the package isn't allowed. Local packages in a plugin's `files`, such as `@typstream/edu`'s, work. |
| Fixer modules | Ignored, with a warning: importing a module would run the client's code on your server. |
| `resolve/*` | Not offered. |

**Sessions.** Each connection is a session with its own documents. Closing the socket cancels its queued requests and frees its documents.

**Watchdog.** Documents live on the server's main thread and pool workers only compile, so a compile over budget costs one compile, not the session: the pool terminates that worker and the compile answers with an error diagnostic, `code: "timeout"` (or `"engine-crashed"` when it ran out of memory). The fallback then finds the block that hangs and shows it as an error box.

## The wire format

Messages are JSON text, one per WebSocket message. They are the protocol's plain data (`@typstream/core`'s `ClientMessage` and `ServerMessage`), except that bytes (files, PDF exports) are written as `{ "$bytes": "<base64>" }`. `serializeMessage` and `deserializeMessage` from `@typstream/core` read and write it, in the browser and in Node:

```ts
import { deserializeMessage, serializeMessage } from "@typstream/core";

serializeMessage({ id: 1, method: "export/pdf", params: { uri: "doc-1", rev: 3 } });
// '{"id":1,"method":"export/pdf","params":{"uri":"doc-1","rev":3}}'
deserializeMessage('{"id":1,"result":{"uri":"doc-1","rev":3,"diagnostics":[],"status":"ok","data":{"$bytes":"JVBERi0="}}}');
// result.data is a Uint8Array
```

`deserializeMessage` only parses: validate the result before trusting it, as the server does.

## Untrusted clients

Anyone who can open the socket can send the server anything, so the server treats every client as untrusted:

- **Shapes are checked** before the protocol server reads a message. A malformed request is answered `invalid-params`; anything else malformed gets a `$/log` warning back and is dropped. The only notification clients may send is `$/cancel`.
- **Limits.** More than `maxDocuments` open documents (32), or a document longer than `maxTextLength` (1,000,000 UTF-16 code units, preamble and text), answers `invalid-params`. Cap the size of a single message on the socket server: `ws`'s `maxPayload` (8 MiB above).
- **No fetching for clients.** The protocol server runs with `trustClient: false`, so it ignores the package allowlists clients send. Otherwise a client could make your server fetch any URL.
- **No code from clients.** It runs with `clientFixers: false`, so it ignores the fixer modules clients name. Otherwise a client could run code in your server (a `data:` URL is a module).
- **The sandbox.** Documents can't read the server's filesystem or the network, only the files the client sent to that document, and diagnostics name virtual paths only. See [Security](/docs/guides/security).

Authentication, rate limits and the number of connections per user are yours to enforce, in the upgrade handler or in front of the server.

## Connect the browser

The engine client (`createEngine` from `@typstream/engine`) talks to whatever its `spawn` function starts. In a browser that is usually a worker (`engineWorker()`); `fromWebSocket` from `@typstream/engine/websocket` connects it to your server instead:

```npm
npm install @typstream/engine
```

```ts title="engine.ts"
import { createEngine } from "@typstream/engine";
import { fromWebSocket } from "@typstream/engine/websocket";

export const engine = createEngine({ spawn: fromWebSocket("wss://typst.example.com/typst") });
```

Then use it like any engine: `<TypstreamProvider engine={engine}>` in React, or `mountTypstream(element, { engine, … })`. In an app rendered on the server, create the engine in the browser only, as in [Self-hosting](/docs/guides/self-hosting#a-custom-worker). `fromWebSocket` is its own entry point, so pages that compile in a worker don't download it.

To authenticate each connection with a short-lived token, pass a function: it is called for every connection, the first and each one that replaces it, and must return the URL synchronously.

```ts
// sessionToken() returns your app's current token.
const spawn = fromWebSocket(() => `wss://typst.example.com/typst?token=${encodeURIComponent(sessionToken())}`);
```

How the client behaves over this transport:

- **Healing stays in the browser.** The client heals each chunk on the main thread and sends the server one diff right before each compile, so the server sees healed source, never half a token.
- **The watchdog.** The budgets `fromWebSocket` gives the engine, 10 s streaming and 30 s final, sit above the most the server takes with its default timeouts (about 4.5 s and 15 s, its fallback included), so the server's own timeout answers first: a `timeout` diagnostic that costs one compile. Past the client's budget (a server that stopped answering), the client closes the connection and opens a new one, a new session; documents open themselves again before their next compile. If you raise the server's `timeouts`, raise the client's `watchdog` with them.
- **No spare connection.** In a worker the engine keeps a spare warm; over a socket that would be a second session per page, so `fromWebSocket` turns it off. Pass `spare: true` to `createEngine` to have it anyway.
- **Dropped connections.** When a connection closes (the server restarted, a proxy timed it out), the engine emits a `disconnect` event and opens a new one; the compile or export that was running is retried there, without counting against the document. A request that keeps dropping the connection (three times in a row, such as a message over `maxPayload`) then counts as a crash, so it stops.
- **A server that can't be reached.** Opening a connection is retried 4 times, after 0.5, 1, 2 and 4 s (`retries`, `retryDelayMs`). When every attempt fails, or a connection closes before the server answers `initialize` (it refused it), the engine fails (an engine `failed` event, every document in `error`) rather than reconnecting in a loop. Create a new engine to try again.
- **Telemetry** works as with a worker: the [events](/docs/guides/telemetry) come from the client. `serverInfo.name` in the engine's `ready` event is `@typstream/node`.

The options:

### WebSocketOptions

Options of fromWebSocket.

| Prop            | Type                                                                                | Description                                                                                         |
| --------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `protocols?`    | `string \| string[] \| undefined`                                                   | Subprotocols, for the `WebSocket` constructor.                                                      |
| `retries?`      | `number \| undefined`                                                               | Attempts to open a connection after the first fails, before the engine gives up. Default 4.         |
| `retryDelayMs?` | `number \| undefined`                                                               | Wait before the first retry, in ms, doubled for each one after it. Default 500 (0.5 + 1 + 2 + 4 s). |
| `WebSocket?`    | `(new (url: string, protocols?: string \| string[]) => WebSocketLike) \| undefined` | The WebSocket class. Default: the global `WebSocket` (browsers, Node 22+).                          |

The server's `$/log` warnings (ignored fonts or fixer modules) arrive as `log` events. Browsers can't send WebSocket pings, so a proxy that closes idle connections (nginx's `proxy_read_timeout` is 60 s by default) makes the client reconnect after each one: harmless, as nothing is lost, but raise the proxy's idle timeout if the reconnects bother you.

## Content-Security-Policy

Under a policy, allow the socket's origin in `connect-src`:

```text
connect-src 'self' wss://typst.example.com
```

If no page uses the local engine, `'wasm-unsafe-eval'` and `worker-src` aren't needed for typstream. See [Security](/docs/guides/security#content-security-policy) for the rest of the policy.
