Build the MST5 connection demo locally, prove the socket works, and only then make it reachable by remote clients
Master Server Toolkit 5 provides modular backend infrastructure for Unity multiplayer projects, but a reliable remote test begins with a verified local build. In this guide, we install the official source repository, build its Basic Connection demo with the documented Unity version, inspect the generated configuration, and start the matching master-server and client executables. We then configure a Localtonet TCP tunnel that forwards the master-server socket without requiring inbound router port forwarding, firewall changes, a VPN, or a public IP address. The final sections cover remote-client configuration, security boundaries, routine operation, and troubleshooting.
📋 What's in this guide
What Master Server Toolkit does in a multiplayer architecture
Master Server Toolkit 5, commonly shortened to MST5, is a modular Unity framework for building and operating multiplayer backend services. Its master-server layer can own shared concerns such as accounts, sessions, profiles, service discovery, rooms, lobbies, matchmaking, permissions, and other backend modules. The project also includes infrastructure for room processes, process spawners, persistent profiles, chat, analytics, leaderboards, platform-service bridges, and administration tools.
MST is infrastructure rather than a complete game server. It does not implement the unique rules, movement, combat, economy, or moment-to-moment networking of a game. Those responsibilities remain in the integrating Unity project and its chosen game-networking framework. MST lists Mirror and FishNet integrations, while its networking API can also be used independently for backend messages.
The distinction matters when planning remote access. A client can use the MST WebSocket API to communicate with the master server for backend operations, while a separate game-networking connection may communicate with a room server for live gameplay. Exposing the master-server endpoint does not automatically expose room servers, spawners, databases, dashboards, or every port needed by a complete production game.
This tutorial deliberately starts with the Basic Connection demo. It is the smallest documented example for proving that a matching master and client can establish the underlying connection. Authentication, profiles, chat, rooms, worlds, process allocation, and production persistence introduce additional components. A successful Basic Connection test is therefore a foundation, not proof that a complete multiplayer deployment is production-ready.
The MST architecture identifies its client-facing API as WebSocket-based, and the documented configuration example identifies a master address and port. A Localtonet TCP tunnel is the conservative choice because it forwards the configured socket as a raw TCP stream without requiring us to assume details about MST's HTTP routing. MST also includes an HTTP server and dashboard controllers, but the available project evidence does not establish that server's listening port. This guide therefore does not invent or configure a separate dashboard tunnel.
Prerequisites and version boundaries
MST5 is under active development, so version consistency is important. The documented repository currently targets Unity 2022.3.62f3. Client, master, room, and spawner builds should use the same MST revision because network and persistence contracts can differ from MST4 and can also change as MST5 develops.
For the source-based Basic Connection workflow, prepare the following:
- Git installed and available from your terminal.
- Git LFS installed before cloning the repository.
- Unity Editor
2022.3.62f3. - A supported desktop build target for master, room, and spawner processes.
- Enough local storage for the Unity project, imported assets, and generated builds.
- A Localtonet client installation on the machine that will run, or can reach, the MST master-server process.
- A Localtonet device/auth token selected through our platform. Treat the token as a device-specific secret and never place it in source control, screenshots, logs, or shared configuration examples.
WebGL is supported for MST clients, but server-only database assemblies are excluded from WebGL. That distinction does not change the first local test: the master server must run on a supported desktop target, and the client must point to the socket exposed by that master.
| Requirement | Documented value or role | Why it matters |
|---|---|---|
| Unity Editor | 2022.3.62f3 |
Using the repository's targeted version reduces avoidable import, serialization, and build differences. |
| Git LFS | Install and initialize it before cloning | The repository expects LFS-managed content to be retrieved correctly. |
| MST source | Clone the standalone repository | MST5 is not currently distributed as a Unity Package Manager package. |
| Build target | Supported desktop target for server processes | The master server needs a runnable desktop build. |
| Matching revision | Use the same MST revision for related builds | Network and persistence contracts may differ across revisions. |
| Localtonet client | Run it where the local MST endpoint is reachable | The client establishes the outbound connection to our relay server. |
This workflow is evidenced for Unity 2022.3.62f3. A newer or older editor might upgrade project files, reimport assets differently, or introduce incompatibilities. If your project must migrate to another Unity version, perform that migration in a separate branch and validate it independently rather than silently changing the version during this baseline test.
Install MST5 and build the Basic Connection demo
The official MST5 installation path is source-based. The standalone repository already contains the framework, demos, bridge code, and Unity project settings used for development. It is not currently installed through Unity Package Manager.
Install and initialize Git LFS
Install Git LFS for your operating system, then initialize it for your user account before cloning MST5. The documented initialization command is:
git lfs installConfirm that this completes successfully. Cloning before Git LFS is installed can leave expected assets as pointer files rather than usable project content.
Clone the official MST5 repository
Clone the repository into a working directory with the documented command:
git clone https://github.com/aevien/master-server-toolkit.gitKeep the repository revision consistent while producing the master and client builds. If the source changes between builds, rebuild both sides from the same checked-out revision.
Open the cloned folder in Unity 2022.3.62f3
Add or open the cloned project folder with Unity Editor 2022.3.62f3. Allow the initial import to finish before using the project menus or attempting a build. During this first import, Unity creates local project artifacts and processes the repository's assets and packages.
Build the Basic Connection demo
In Unity, select Tools > Master Server Toolkit > Build > Demos > Basic Connection > All. This is the documented builder for the smallest connection example. Let the build finish and review the Unity Console for errors instead of assuming that the presence of a build directory means every target succeeded.
Locate the generated master and client builds
The documented Windows outputs are Builds/BasicConnection/MasterServer/MasterServer.exe and Builds/BasicConnection/Client/Client.exe. The builder also writes matching application.cfg files for the master and client. The available evidence does not provide exact executable names for every desktop platform, so use the corresponding artifacts produced by your selected supported target rather than guessing a filename.
At this point, preserve the complete generated build directories. Unity standalone builds commonly depend on files and directories adjacent to the launcher, so moving only the executable is not a safe deployment method. The MST evidence specifically establishes that application.cfg is read from the project or build root by default, which is another reason to keep the generated layout intact.
If you plan to customize the demo, first archive or commit a clean baseline of your own work. MST5 is active development software, and reproducing a known-good source revision is much easier when dependency updates, configuration changes, and game-specific modifications are isolated.
Understand the generated MST configuration
MST reads application.cfg from the project or build root by default. A different main configuration file can be selected with the -mstConfigFile argument. The Basic Connection builder writes matching configuration files, so the first test should normally use those generated files without speculative edits.
The project documents this representative configuration syntax:
@import "Configs/common.cfg"
@import "Configs/security.cfg"
-mstStartMaster=true
-mstMasterIp=127.0.0.1
-mstMasterPort=25200
In this example, -mstStartMaster=true identifies a build that should start the master role. The address 127.0.0.1 is the IPv4 loopback address, which limits that endpoint to the same host. The example port is 25200. Treat these as documented example values and inspect the generated application.cfg in your actual build before configuring Localtonet. Your tunnel target must match the address and port the running master really uses.
Configuration resolution order
MST resolves values in the following priority order, from highest to lowest:
- Environment variable
- Command-line argument
- Main configuration file
- Imported configuration defaults
This order is essential during troubleshooting. A correct-looking application.cfg does not prove that its value is active if an environment variable or command-line argument overrides it. Within configuration files, the main file wins over imported values. Repeated imports are ignored to prevent cycles, missing imports produce a warning, and the first imported duplicate wins.
| Configuration source | Priority | Diagnostic question |
|---|---|---|
| Environment variable | Highest | Does the process environment override the address, port, role, or security setting? |
| Command-line argument | Second | Was the executable launched by a shortcut, service, or script that supplies different values? |
Main application.cfg |
Third | Are you editing the file in the build root that the running process actually reads? |
| Imported defaults | Lowest | Is an imported file present, and is its value being superseded by the main file? |
Canonical argument names are defined by the MST source in MstArgNames.cs. Do not invent similarly named flags. When creating automation around MST, use the names supported by the exact repository revision from which you built the executables.
MST warns against committing a generated production key ring and deploying the same private keys to unrelated projects. For each production environment, configure a stable -mstSecurityKeyRingFile path and protect the resulting files with appropriate host permissions and backup controls. Do not place private keys or Localtonet device tokens in a public repository.
Start and verify the demo locally
Local verification isolates MST build and configuration problems from remote connectivity problems. If the generated client cannot connect on the same machine, adding a public tunnel will not repair the master process, configuration, or application-level protocol.
Start the master-server build
On Windows, launch Builds/BasicConnection/MasterServer/MasterServer.exe. On another supported desktop target, launch the corresponding server artifact generated by Unity. Keep the process running and retain its visible logs or terminal output for diagnosis.
Confirm that startup completes without a fatal error
Review the process output for configuration warnings, missing imports, startup failures, or address-binding errors. Verify that the build is using the intended configuration file and that no other process already occupies the configured master port.
Start the matching local client
On Windows, launch Builds/BasicConnection/Client/Client.exe. The documented builder writes a matching client configuration, so use the client from the same build operation rather than an older executable from another MST revision.
Observe the connection result on both sides
Check the client and master logs for a successful socket connection and for immediate disconnects or protocol errors. A stable local connection establishes that the generated pair can communicate before a relay path is introduced.
A port-listening check can be useful, but the exact command varies by operating system and is not required by the MST build instructions. Whichever native tool you use, confirm that the process is listening on the address and port shown by the effective configuration. Remember that a listening socket proves only that a process accepted the bind. The matching demo client remains the more meaningful application-level verification.
If the local client fails, compare the master and client configurations, check the resolution priority, and ensure both executables came from the same source revision. Do not proceed to remote testing until this baseline works consistently.
Expose the MST master socket with a Localtonet TCP tunnel
Once the Basic Connection demo works locally, Localtonet can provide a public host and port for the master-server socket. Our client application establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
The Localtonet client should run on the machine hosting MST or on another device that can reach the configured MST address and port. If MST listens only on 127.0.0.1, the Localtonet client must run on that same host because loopback is not reachable from another machine.
Install and run the Localtonet client
Install our client application for the operating system on the device that can reach the MST master server, then run it. Current installation details can vary by operating system and client version, so use the current Localtonet installation flow rather than an unverified command copied into automation.
Authenticate or select the client device
Use the device-specific auth token associated with the client that will carry the tunnel. Never guess, publish, or embed this token in the Unity project. Confirm that the selected device appears connected before continuing.
Select an available relay server
Choose an available relay server or region from the current Localtonet dashboard. Available server codes and regions can vary, so obtain the value from the product instead of hardcoding an example from an article.
Create a TCP tunnel to the local MST endpoint
Select the TCP tunnel type and set its local target to the IP address and port used by the running master server. For an unchanged build matching the documented example, that may be 127.0.0.1 and 25200, but inspect your effective MST configuration first. Do not copy those example values if your build uses different settings.
Start the tunnel
Creating a Localtonet tunnel does not mean it is running. Use the Start button and confirm that the selected client device remains connected. The tunnel is available only while that client is connected and the tunnel is running.
Record the assigned public host and port
After the TCP tunnel starts, use the public host and port assigned by our platform. Remote MST clients must use that exact pair. Do not substitute the relay server label, dashboard address, local loopback address, or an HTTP URL.
The public endpoint depends on three running components: the MST master-server process, the Localtonet client, and the TCP tunnel. Stopping any one of them interrupts remote access. A tunnel can later be stopped or deleted from the dashboard when testing is complete.
Configure and test a remote MST client
Keep one unmodified local client build as a control. Create a separate copy for remote testing, then change only the master endpoint required by that copy. The remote client must use the Localtonet public host and public port, while the server continues listening on its local target.
Do not configure a remote player with 127.0.0.1. Loopback always refers to the device on which the client is running. On a player's computer, it points back to that player's computer, not to your development machine.
Copy the matching client build
Use a client generated by the same Basic Connection build operation as the running master. Preserve its full build directory and configuration files.
Set the public master host and port
Update the remote client's effective MST master address and port to the Localtonet values. Respect MST's configuration priority: a command-line argument or environment variable can override a value edited in application.cfg. The exact public endpoint is unique to the running tunnel and must not be guessed.
Move the client to a genuinely remote network
Run the test client on another device or network so the test exercises the public endpoint rather than a local route. Keep the master logs and Localtonet dashboard available on the host side.
Launch the client and correlate the logs
Start the remote client and compare its timestamped behavior with the master output. Determine whether the connection reaches the master, remains established, and completes the Basic Connection flow.
Retest the local control client
If the remote client fails, retest the untouched local client. If local communication now fails too, investigate MST first. If local communication succeeds while remote communication fails, focus on the tunnel state, public endpoint, remote configuration, and transport security compatibility.
This test exposes only the Basic Connection master socket. A larger game may require room servers and other client-facing services. Those services need their own documented addresses, ports, protocol choices, authentication, and exposure decisions. Never assume that forwarding the master port automatically makes spawned rooms reachable.
Security boundaries for a public multiplayer endpoint
A TCP tunnel provides reachability. It does not replace authentication, authorization, application-layer encryption, abuse controls, process isolation, secure key handling, or game-specific validation. Once the public endpoint is distributed, untrusted internet clients can attempt to connect to it.
MST documents WSS support, a permission challenge and proof flow, authenticated request envelopes, persistent key rings, password hashing, and replay protection. Which controls are active depends on the MST scene and configuration you deploy. A Basic Connection demo should be treated as a connectivity exercise, not as a hardened public service.
WebSocket describes application communication over a TCP connection, while WSS adds TLS protection to that WebSocket traffic. A Localtonet TCP tunnel forwards the stream to MST, but you must still configure a compatible security design for the application protocol. Follow MST's recommendation to use WSS or external TLS termination for public connections. Do not label an unverified plaintext configuration as secure merely because it is reachable through a tunnel.
Use least privilege on the host running the master server and Localtonet client. Run only the modules required by the test, keep development terminals and dashboards private unless they have a separately reviewed exposure plan, and restrict access to configuration and key files. If you later add account registration, password reset, email confirmation, platform bindings, profile persistence, or database bridges, perform a new threat review for those workflows.
Routine operation and deployment planning
A repeatable startup order makes failures easier to interpret. Start the MST master process first and confirm that it is listening. Start the Localtonet client second and verify that its device is connected. Start the configured TCP tunnel third. Only then start remote clients.
For shutdown, stop accepting new tests, close remote clients, stop the tunnel, and then stop the master process. Deleting a tunnel is appropriate when the endpoint is no longer needed. Stopping preserves the configuration for later use, while deletion removes it.
| Operational state | Local client result | Remote client result |
|---|---|---|
| MST master stopped | Cannot complete the MST connection | The tunnel has no working local service to forward to |
| Localtonet client disconnected | Can still work locally if MST is running | Public tunnel is unavailable |
| TCP tunnel stopped | Can still work locally | Assigned public endpoint is not active |
| Wrong public host or port | Unaffected | Connects to the wrong destination or fails |
| Client and master revisions differ | May fail or behave incompatibly | May fail even when the TCP path is reachable |
Full MST deployment can include a server build containing the master server and spawner, room builds containing game scenes, and a client build containing the client scene and required room scenes. The spawner must know the correct room executable location on the deployed server. Every scene that connects to the master must use consistent master connection information.
These deployment concerns go beyond the Basic Connection demo. Room servers may need independent public reachability for gameplay, depending on the selected networking framework and architecture. Determine those ports from your actual room and networking configuration. The evidence supplied for this tutorial does not establish universal room ports, dashboard ports, or production process paths, so we do not invent them.
Troubleshooting the build, local connection, and tunnel
Git LFS assets were not downloaded correctly
Ensure Git LFS is installed and that git lfs install completed before the repository was cloned. If files contain LFS pointer text instead of expected content, repair the checkout using Git LFS tooling appropriate to your installation or perform a clean clone after initialization. Do not diagnose Unity import errors until the source checkout is complete.
Unity reports import or compilation errors
Confirm that the project is open in Unity 2022.3.62f3 and that the initial import has finished. Check that you cloned the repository root, not a partial folder. Review the first meaningful error in the Unity Console because later errors can be consequences of an earlier failure. If you opened the project in another Unity release, return to a clean checkout rather than assuming all upgraded files can be reversed safely.
The Basic Connection build is missing
Verify that you used Tools > Master Server Toolkit > Build > Demos > Basic Connection > All. Review the Console for build errors and confirm that your selected desktop target is supported. The documented Windows paths end in MasterServer.exe and Client.exe, but exact artifact names for every desktop target are not established by the supplied evidence.
The master process starts and exits immediately
Run it in a way that preserves its output, then inspect the earliest warning or fatal message. Check for a missing configuration import, an invalid path, a port collision, or a role setting overridden by a higher-priority source. Confirm that application.cfg remains in the build root unless you intentionally selected another file with -mstConfigFile.
The local client cannot connect
Confirm that the master is running before the client. Compare the effective address and port on both sides. If the documented example is in use, the endpoint is 127.0.0.1:25200, but generated or edited files may differ. Check environment variables and launch arguments before trusting the visible file. Finally, verify that master and client came from the same MST revision.
The Localtonet tunnel starts but no remote client connects
First retest the local client. Then verify that the Localtonet target matches the master server's actual IP address and port. Confirm that the selected Localtonet device is connected and can reach that address. If MST listens on 127.0.0.1, our client must run on the same host. Check that the tunnel itself was started, not merely created, and copy the assigned public host and port exactly.
The remote client still uses loopback
Replace the remote client's master address and port with the Localtonet public endpoint. If editing application.cfg appears ineffective, inspect command-line and environment overrides. MST gives those sources higher priority than the main file.
A TCP connection opens and then closes
Basic transport reachability does not guarantee protocol compatibility. Compare client and server revisions, inspect both application logs, and check whether the security mode expected by the client matches the master. An immediate application disconnect can result from incompatible configuration even when the Localtonet TCP path is working.
The dashboard is not reachable through the master tunnel
The TCP tunnel in this guide targets the documented MST master socket used by the Basic Connection example. MST includes a built-in HTTP server and dashboard controllers, but the available evidence does not establish the HTTP server's listening port or a universal dashboard deployment configuration. Do not assume it shares the master socket. Identify and secure the dashboard's actual configuration before considering a separate tunnel.
Basic Connection works, but rooms do not
The master connection and live room networking are different paths. A complete deployment can include master, spawner, room, and client builds, with room executable paths configured for the deployment host. Room networking may require separate endpoints. Derive those requirements from the room build and the selected networking integration rather than reusing the master port automatically.
Keep one known-good local client and one remote client. When a failure occurs, test both against the same running master. If both fail, investigate MST startup, revision, and configuration. If only the remote client fails, investigate the Localtonet client state, tunnel lifecycle, target address, assigned endpoint, and remote-client overrides.
Frequently asked questions
Is Master Server Toolkit a complete multiplayer game server?
No. MST provides modular multiplayer backend infrastructure, including master-server functions, authentication-related modules, profiles, rooms, lobbies, matchmaking, chat, spawners, administration tools, and integrations. Your project remains responsible for game rules, movement, combat, economy policy, and its live gameplay networking design.
Can I install MST5 with Unity Package Manager?
Not through the currently documented path. MST5 is provided as a standalone repository containing the framework, demos, bridge code, and Unity project settings. Install Git LFS, clone the repository, and open the cloned folder in Unity 2022.3.62f3.
Why does this guide use a Localtonet TCP tunnel?
The MST architecture identifies its client-facing API as WebSocket-based, and the documented configuration provides a master IP address and port. TCP forwarding carries that socket stream without requiring assumptions about HTTP host routing or the separate built-in HTTP server. The tunnel target must match the effective MST address and port.
Does a Localtonet TCP tunnel automatically encrypt MST traffic?
Do not assume that raw TCP forwarding makes the application payload encrypted. MST recommends WSS or external TLS termination for public connections. Configure and verify a compatible application security design, and keep authentication and authorization enabled for sensitive operations.
Must the Localtonet client run on the MST server?
It must run on a device that can reach the MST local target. If MST listens on 127.0.0.1, that means the same host. If MST is deliberately bound to an address reachable over a trusted local network, another device may be able to carry the tunnel, but that binding and the surrounding access controls must be reviewed separately.
Does creating a Localtonet tunnel make it active immediately?
No. Creating and running are separate lifecycle states. Start the tunnel with the Start button and keep the selected Localtonet client connected. The public endpoint is available only while the tunnel is running and its client device remains connected.
Can the same tunnel expose MST room servers and the dashboard?
Not by assumption. The tutorial tunnel forwards one configured master-server TCP endpoint. Room servers can use separate game-networking endpoints, and the available evidence does not establish the built-in HTTP server's listening port. Inventory each service and configure only the separately documented endpoints that remote clients genuinely require.
Why must the client and server use the same MST revision?
MST5 is under active development, and its network and persistence contracts can differ from MST4 or other revisions. Building related components from the same checked-out revision removes a major source of protocol and data incompatibility.
Connect your verified MST5 demo with Localtonet
Build and validate the Basic Connection demo first, then create a Localtonet TCP tunnel to its confirmed local master-server address and port. Keep the endpoint active only while the master process, our client, and the tunnel are running.
Get Started Free →
