# Server setup

Installing the Paper plugin or server mod, local testing and public WSS deployment

Source: https://socketsvc.vercel.app/zh-TW/server
Voice chat needs SocketSVC installed on both the client and the server. The server side comes in two forms with identical features, and any client loader works with the Paper plugin or any server mod:

- **Paper plugin**: one JAR supports Paper/Purpur/Folia.
- **Server mod**: dedicated servers on Fabric/Quilt, NeoForge and Forge.

The server side opens its own WebSocket listener (port `24455` by default) and handles authentication, player positions, distance routing and the speaker API. On a Velocity/BungeeCord network you can additionally install the optional relay plugin so the whole network exposes a single public voice port; see [Proxy relay](/proxy).

## Support matrix

The state below is as of 2026-09-17; versions and dependencies may change, and [gradle/socketsvc.properties](https://github.com/HippoDev03/SocketSVC/blob/main/gradle/socketsvc.properties) is authoritative.

| Component | Current setting |
| --- | --- |
| Paper server | Compiled against Paper API `1.21.11-R0.1-SNAPSHOT`, Java 21 bytecode; one JAR supports Paper/Purpur/Folia |
| Server mod | Minecraft 1.21.11, 26.1, 26.1.1, 26.1.2, 26.2, 26.3; dedicated servers on Fabric/Quilt, NeoForge and Forge, feature-identical to the Paper plugin |
| Loader | Fabric (the same JAR declares Quilt support) on all versions; NeoForge on all versions (26.1 and 26.1.1 use beta loaders and are released as beta); Forge on all versions |
| Java | Java 21 for 1.21.11; Java 25 for 26.x |
| Voice transport | WebSocket; TLS for WSS is handled by an external reverse proxy |
| Bedrock (Geyser/Floodgate) | **Not supported and not planned.** Bedrock players cannot install the client mod, so they have no voice; they are otherwise unaffected |

<Callout type="error" title="Bedrock clients are not supported, and will not be">
  SocketSVC voice needs the client mod. Bedrock players joining through **Geyser/Floodgate** cannot install it, so they have no voice at all: they hear nobody and nobody hears them. They play normally in every other respect — nothing is broken, and they do not need to be blocked — but they are silent, and nothing on the server side can change that.

  This is not a gap waiting to be filled. Voice would have to be carried over Bedrock's own protocol to a client SocketSVC does not write and cannot extend; that is a different product, not a feature of this one. Treat a Bedrock player the way you would treat a player who has not installed the mod, because that is exactly what they are.
</Callout>

<Callout type="warn" title="Client and server compatibility are verified separately">
  Client support for 26.x does **not** mean the server has been verified on the same Paper version; server compatibility has to be tested separately. The server must also meet the Java requirement of the Paper version it runs.
</Callout>

## Installing the server side

[The download page](/download?side=server) has the current jar for every loader, the Paper plugin included.

<Tabs items={['Paper', 'Fabric/Quilt/NeoForge/Forge']}>
  <Tab value="Paper">
    Put `socketsvc-server-paper-<version>.jar` into `plugins/` and restart; this generates `plugins/SocketSVC/config.yml`. The same JAR supports Paper/Purpur/Folia.
  </Tab>
  <Tab value="Fabric/Quilt/NeoForge/Forge">
    Put the `socketsvc-server-<loader>-<version>+mc<MC>.jar` matching your Minecraft version and loader into `mods/` (Fabric also needs Fabric API). Starting the server generates `config/socketsvc-server.yml`, with the same fields as Paper.
  </Tab>
</Tabs>

By default the listener uses port `24455` and binds `0.0.0.0` (LAN-visible). See [Configuration](/server/configuration) for all fields.

| Artifact | File to install | Modrinth version number |
| --- | --- | --- |
| Server mod (per version × loader) | `server/<loader>/build/<MC>/libs/socketsvc-server-<loader>-<server>+mc<MC>.jar` | `<server>+mc<MC>-<loader>@server` |
| Paper plugin | `server/paper/build/libs/socketsvc-server-paper-<server>.jar` | `<server>-paper@server` |

Every file's version number on Modrinth ends in `@client`, `@server` or `@proxy`, so it is clear which side it belongs to.

<Callout type="warn" title="Do not install incomplete JARs">
  Do not install `-plain.jar` or `-slim.jar`; they are not complete artifacts. Do not use leftovers from the old `client/build/`, `server/build/` or `proxy-plugin/build/` directories.
</Callout>

## Local testing

Use a separate test Minecraft instance and server directory so game data and real deployment settings never end up in the repository.

<Steps>
<Step>

### Install the client

On the test client, install the loader for the target Minecraft version (Fabric/Quilt also needs Fabric API; Mod Menu is an optional integration) and the SocketSVC client JAR for the same Minecraft version and loader. Install only one SocketSVC client JAR.

</Step>
<Step>

### Install the server side

Paper: put `socketsvc-server-paper-<version>.jar` into `plugins/`, start the server, then edit `plugins/SocketSVC/config.yml`. Fabric/Quilt/NeoForge/Forge dedicated server: put the matching `socketsvc-server-<loader>-<version>+mc<MC>.jar` into `mods/` (Fabric needs Fabric API), start the server, then edit `config/socketsvc-server.yml` (same fields as Paper).

</Step>
<Step>

### Check the voice address

Local testing can use the default `ws://localhost:24455`. If players are on other machines, `public-host` must be a host they can reach — do not keep `localhost`, which would point at the player's own computer.

</Step>
<Step>

### Join and test

Make sure the client can reach both the game and the voice service. After joining, the client automatically requests a one-time token and connects to voice. Complete the first-run setup (push-to-talk or automatic detection, input/output devices), then test capture and a two-player call.

</Step>
</Steps>

## Public deployment and WSS

For a public WSS deployment, a proxy terminates TLS; the plugin listener itself is plain WebSocket and never touches TLS or certificates.

- Set `public-url` to a `wss://` base URL players can reach (for example `wss://mydomain.com`) instead of exposing the raw port.
- The proxy must support the WebSocket upgrade and preserve the negotiation headers (`X-SocketSVC-*`, see [Voice protocol](/server/voice-protocol)) and the `/voice` query.
- If the proxy runs on the same machine as the plugin, you can bind the listener to `127.0.0.1`.
- After changing the external URL, `/ssvc-server reload` closes existing voice connections so clients automatically fetch a new token and connect to the new URL. Adjust the proxy and firewall yourself; the plugin does not change external network settings.

<Accordions>
<Accordion title="Example: Cloudflare Tunnel (cloudflared)">

cloudflared terminates TLS at Cloudflare's edge and forwards plain WebSocket traffic to the listener's local `port`. Point the tunnel's local service at `ws://localhost:<port>` (or `127.0.0.1`) and set the tunnel's `wss://` hostname in the config:

```yaml title="config.yml"
bind-address: "127.0.0.1"
port: 24455
public-url: "wss://mydomain.com"
```

</Accordion>
</Accordions>

## Managing the server

<Cards>
  <Card title="Configuration" href="/server/configuration">
    Range, fade, spectators, visible players, the soundboard switch and hot reload
  </Card>
  <Card title="Permissions" href="/server/permissions">
    `/ssvc-server status`/`reload` and the speak/listen/soundboard permission nodes
  </Card>
  <Card title="Spatial audio API" href="/server/spatial-audio-api">
    Let other plugins or mods create speakers, relay microphones and play audio
  </Card>
  <Card title="Proxy relay" href="/proxy">
    A single public voice port for a Velocity/BungeeCord network
  </Card>
</Cards>