## Configure Subscriptions for local development

When composing a Graph locally, you can supply the protocol using the following configuration.

```
version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      protocol: "ws"
```

If your Subgraph uses SSE, use the following configuration.

```
version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      protocol: "sse"
```

If your Subgraph uses SSE over HTTP POST, the config should look like this.

```
version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      protocol: "sse_post"
```

If your Subscriptions Endpoint differs from the default routing URL, you can use the following configuration.

```
version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      url: "http://localhost:4001/subscriptions"
      protocol: "sse_post"
```

## Configure Subscriptions using wgc

When using Cosmo Studio as a target to publish your Subgraphs, you’ll be using “wgc publish” to upload the Subgraph configuration to the Studio. In this case, you can supply the protocol using the following config.

### Setting a custom Subscriptions protocol on wgc publish

```
npx wgc subgraph publish products --subscription-protocol sse --schema ../demo/subgraphs/products/products.graphql
```

Available options are “sse”, “sse_post”, and “ws”.

### Setting a custom Subscriptions URL on wgc publish

```
npx wgc subgraph publish products --subscription-url "http://localhost:4001/subscriptions" --schema ../demo/subgraphs/products/products.graphql
```

You can also use `wgc subgraph update …` to update the Subscriptions protocol or URL for a specific Subgraph.

## Tuning the upstream subscription client

The router’s upstream WebSocket client (the one that connects to subgraphs for subscriptions) is configured under the `engine` block. The defaults suit most deployments. The options below are listed with their YAML field and the matching environment variable.

| Option | Env var | Default | Purpose |
| --- | --- | --- | --- |
| `websocket_client_write_timeout` | `ENGINE_WEBSOCKET_CLIENT_WRITE_TIMEOUT` | `10s` | The timeout for the websocket write of the WebSocket client implementation. |
| `websocket_client_ping_interval` | `ENGINE_WEBSOCKET_CLIENT_PING_INTERVAL` | `15s` | The Websocket client ping interval to the subgraph. Defines how often the router will ping the subgraph to signal that the connection is still alive. |
| `websocket_client_ping_timeout` | `ENGINE_WEBSOCKET_CLIENT_PING_TIMEOUT` | `30s` | The Websocket client ping timeout to the subgraph. Defines how long the router will wait for a ping response from the subgraph. |
| `websocket_client_ack_timeout` | `ENGINE_WEBSOCKET_CLIENT_ACK_TIMEOUT` | `30s` | How long the router waits for `connection_ack` from a subgraph after sending `connection_init`. |
| `websocket_client_read_limit` | `ENGINE_WEBSOCKET_CLIENT_READ_LIMIT` | `1MB` | Maximum size of a single incoming WebSocket message from a subgraph. |

Example:

```
version: "1"

engine:
  websocket_client_write_timeout: 10s
  websocket_client_ping_interval: 15s
  websocket_client_ping_timeout: 30s
  websocket_client_ack_timeout: 30s
  websocket_client_read_limit: 1MB
```

## Tuning the server-side WebSocket handler

These options apply to the router’s own WebSocket endpoint (the one clients connect to). They are separate from the upstream client options above.

| Option | Env var | Default | Purpose |
| --- | --- | --- | --- |
| `websocket_server_read_timeout` | `ENGINE_WEBSOCKET_SERVER_READ_TIMEOUT` | `5s` | Read timeout for the server-side WebSocket handler. |
| `websocket_server_write_timeout` | `ENGINE_WEBSOCKET_SERVER_WRITE_TIMEOUT` | `10s` | Write timeout for the server-side WebSocket handler. |
| `websocket_server_poll_timeout` | `ENGINE_WEBSOCKET_SERVER_POLL_TIMEOUT` | `1s` | Timeout for the poll loop of the server-side WebSocket handler. |
| `websocket_server_conn_buffer_size` | `ENGINE_WEBSOCKET_SERVER_CONN_BUFFER_SIZE` | `128` | Buffer size for the poll buffer of the server-side WebSocket handler. Determines how many connections can be handled in one loop. |
| `enable_net_poll` | `ENGINE_ENABLE_NET_POLL` | `true` | Enables the more efficient poll implementation for the server-side WebSocket handler. Linux and macOS only. Has no effect on upstream subgraph connections. |

**Subject to change.**`enable_net_poll`, `websocket_server_poll_timeout`, and `websocket_server_conn_buffer_size` may be removed or changed in a future release without a standard deprecation cycle. Avoid depending on them.

If you are upgrading from an older release and your configuration sets `websocket_client_poll_timeout`, `websocket_client_read_timeout`, `websocket_client_conn_buffer_size`, or `websocket_client_frame_timeout`, see the [Subscriptions Overhaul migration guide](https://cosmo-docs.wundergraph.com/router/subscriptions-migration).