Discover how Edgegap works

Discover how Edgegap works

/

Unity Relays

/

Unity Relays

Deploy to Edgegap

Published

Published

Published

Last reviewed for accuracy

Last reviewed for accuracy

Last reviewed for accuracy

Unity Relays: How to add relays to your peer-to-peer Unity multiplayer game with Edgegap

Unity Relays: How to add relays to your peer-to-peer Unity multiplayer game with Edgegap

This guide shows you how to add Edgegap's Distributed Relays to a peer-to-peer Unity game built with Mirror: one player hosts, the others join through a relay near them, with no port forwarding and no NAT issues.

A relay is not a game server. It forwards traffic between players while the host player's game runs the match. Edgegap assigns each session to the best available relay for its players from a simple API call, billed while the session is open. If you'd rather run the match on an authoritative server that no player controls, see Mirror Networking instead.

This guide covers:

  1. Getting your relay token

  2. Connecting your coding agent to Edgegap (optional)

  3. Adding Edgegap's relay transport to Mirror

  4. Creating a relay session from your backend

  5. Connecting the host and players

  6. Grouping players and adding late joiners

  7. Testing with two players

You can do it two ways, and mix them:

  • With a coding agent. Any AI coding assistant can write the backend call and the connection code from the prompts below. Connected to the Edgegap MCP server, it can also create, read and delete relay sessions for your tests.

  • By hand. Every step below also works without an agent.

Here, we use Edgegap's Mirror relay sample. The relay also works with Netcode for GameObjects and Fish-Networking, through their own transports.

No credit card required. Free tier includes the resources to deploy a real game server.

No credit card required. Free tier includes the resources to deploy a real game server.

Step-by-Step Guide

Detailed Integration Steps

1. Before you start

  • A free Edgegap account. Verify your email. No credit card is needed to test.

  • A Unity project using Mirror, where one player hosts (host and client in the same game). A Unity LTS version is recommended.

  • A relay profile token. In the dashboard, open Relays, create a relay profile and copy its token. It isn't your Edgegap API token: standard API tokens don't work with the relay API.

  • A place to keep that token off players' machines: your lobby, your matchmaker or a small backend service. Anyone holding it can create sessions on your account.

  • For the agent path: an Edgegap API token, from Dashboard → User Settings → Tokens. It is organization-wide, so treat it like a password: never put it in your project, your game client or a chat.

Git: cloning the sample needs a Git client. macOS usually has one already (Xcode Command Line Tools); on Windows, install Git.

2. Connect your coding agent to Edgegap

Skip this step if you're doing everything by hand.

The Edgegap MCP server lets your agent work on your account. For relays, it can create a test session for a list of player IPs, read it, authorize a late joiner and delete it. It may also point out when an authoritative server would suit your game better: that's expected, relays are for games built host-client.

Claude Code: install the Edgegap plugin. It adds both the MCP server and the skills, and asks for your API token during install (stored in your system's credential store):

/plugin marketplace add edgegap/llm-agent-skills, then /plugin install edgegap@edgegap. Restart the session.

Only want the MCP server, without the plugin? Run this in your own terminal instead: claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user. Don't do both, or you'll have two edgegap servers.

Cursor, VS Code and other clients that send headers: add https://mcp.edgegap.dev/mcp with the header Authorization: token YOUR_EDGEGAP_API_TOKEN, and install the skills with npx skills add edgegap/llm-agent-skills --skill "*".

Claude Desktop: custom connectors can't send the header, so use the local server instead (Node 18+): { "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }. It asks for the token on first use.

Check it works:

Which Edgegap tools do you have for relay sessions?

It should list tools to create, read, authorize on and delete relay sessions.

3. Add Edgegap's relay transport to Mirror

  1. Download Edgegap's transports from distributed-relay-examples and copy the Edgegap folder into Assets/Mirror/Transports.

  2. Select your NetworkManager game object and add the EdgegapKcpTransport component.

  3. Drag that component into the NetworkManager's Transport field.

  4. If the component shows Relay GUI, disable it: it interferes with relay connections.

Using the sample? It's already set up: clone https://github.com/edgegap/unity-mirror-relay-sample and open the folder in Unity Hub.

4. Create a relay session from your backend

Your backend creates one session per match, for every player's public IP, host first, from a simple API call:

POST https://api.edgegap.com/v1/relays/sessions with the header Authorization: Token YOUR_RELAY_PROFILE_TOKEN and the body { "users": [ { "ip": "1.1.1.1" }, { "ip": "2.2.2.2" } ] }.

The relay takes a moment to assign. Poll GET https://api.edgegap.com/v1/relays/sessions/{session_id} every 2 seconds until ready is true, or pass a webhook_url when you create the session and Edgegap calls it once the relay is assigned, or if assignment fails.

Once ready, the response holds everything players need:

  • relay.ip and relay.ports: the relay address, with a server port for the host and a client port for everyone else.

  • authorization_token: the session token, the same for every player.

  • session_users[].authorization_token: one token per player.

Send each player only their own values: the relay address, their port, the session token and their own token. The relay profile token never leaves your backend.

With your agent:

Write an endpoint in my backend that creates an Edgegap relay session: POST https://api.edgegap.com/v1/relays/sessions with the header Authorization: Token, read from the RELAY_PROFILE_TOKEN environment variable, and one user per player IP, host first. Poll GET /v1/relays/sessions/{session_id} every 2 seconds, up to 5 times, until ready is true. Return to each player the relay IP, the server port for the host or the client port for the others, the session authorization_token, and that player's own authorization_token from session_users, matched by IP. Never return the relay profile token.

No backend yet? Ask your agent to create a test session for your players' public IPs: it returns the same values. Delete it when you're done, since sessions bill while they're open.

Here's our video tutorial of Edgegap's relays with Mirror in Unity:

5. Connect the host and players

In your game, set the values from step 4 on the EdgegapKcpTransport, then start Mirror:

  • Relay address: the relay ip.

  • Session ID: the session authorization_token.

  • User ID: this player's own authorization_token.

  • Relay port: the server port for the host, the client port for everyone else.

The sample sets them in one call, ChangeValue, then the host calls StartHost() and the others call StartClient().

In my Mirror project, after my backend returns the relay values, set them on the EdgegapKcpTransport (relay address, session ID from the session authorization_token, user ID from this player's authorization_token, relay port from the server port if I host or the client port otherwise), then call StartHost() or StartClient(). Show me where the transport fields are set and return the complete file.

The host and the clients all connect out to the relay, so nobody opens a port and no player sees another player's IP address.

6. Group players and add late joiners

A relay session is created for players you've already grouped, so the grouping happens before step 4: in your own lobby, Steam lobbies, Epic Online Services lobbies or Unity's Lobby service. Whatever groups them calls your backend with their public IPs.

A player joining after the session started? Authorize their IP on the existing session from your backend, then send them the same values. For a test, ask your agent:

Authorize this public IP on my Edgegap relay session {session_id}.

When the match ends, delete the session from your backend: DELETE https://api.edgegap.com/v1/relays/sessions/{session_id}. Players lose the relay connection and billing for that session stops.

7. Test with two players

  1. Clone the Mirror relay sample and open the folder in Unity Hub.

  2. For this local test only, paste your relay profile token in RelayProfileToken on the HelloWorldManager component of the NetworkManager game object. Remove it before you ship: in a build, players could read it.

  3. Run two instances, with Unity's Multiplayer Play Mode or the Editor plus a build. Start a host in the first, then join from the second.

  4. Both players play the same match through the relay. Delete the test session when you're done.

Next Steps

Next Steps

Frequently Asked Questions

Common questions about adding Edgegap's relays to a peer-to-peer Unity multiplayer game.

What is a relay in multiplayer games?

A relay forwards traffic between players when they can't connect directly, for example behind strict NAT or a firewall. One player's game hosts the match and the relay only passes messages, so nobody opens ports and players never see each other's IP address.

Should I use a relay or a dedicated server?

A relay keeps your peer-to-peer netcode as it is, but the host owns the game state: the host can cheat, plays with no latency, and the match ends when the host leaves unless your game migrates the host. An authoritative game server on Edgegap removes those limits. Use a relay when your game is already built host-client and moving to a server isn't an option.

Do Edgegap's relays work with Netcode for GameObjects and Fish-Networking?

Yes. Edgegap provides relay transports for Mirror, Netcode for GameObjects and Fish-Networking. Other netcodes can follow the relay implementation manual: the relay carries unreliable UDP, and your netcode handles reliability.

Can I put the relay token in my game client?

No. Anyone holding it can create sessions on your account. Keep it in your lobby, matchmaker or backend, and send each player only the relay address, their port, the session token and their own token.

How are relay sessions billed?

A session bills while it's open, and billing stops when you delete it. Delete each session when its match ends, and delete test sessions when you're done.

Clients

Learn more from clients who integrated Edgegap

31 case studies are available from studios that moved to Edgegap from another platform.

Key reasons why they chose Edgegap

Discover the impact of Edgegap's automated game server orchestration for a flawless multiplayer experience.

Cost

Pricing

Pricing

Optimize costs and performance with hybrid orchestration

Optimize costs and performance with hybrid orchestration

Optimize costs and performance with hybrid orchestration

Edge Cloud

On-Demand

$0.00115

/ vCPU

/ MINUTE

Billed by the Minute, Only on Usage

Pay only when players play. 0 active servers = $0

Deploy game servers worldwide, per instance, to all 615+ edge cloud locations. Zero commitment.

Simply add a credit card.

Edge Cloud

On-Demand

$0.00115

/ vCPU

/ MINUTE

Billed by the Minute, Only on Usage

Pay only when players play. 0 active servers = $0

Deploy game servers worldwide, per instance, to all 615+ edge cloud locations. Zero commitment.

Simply add a credit card.

Private Fleet (Bare Metal)

Reserved Capacity

$0.0261

/ vCPU

/ HOUR

Billed Monthly, Always On

$280 per host/month (12 mo rate), or $350 monthly

Optimize the cost effectiveness of your game server with egress-free hosting of Private Fleets.

Persistent, available 24/7, exclusive to your studio.

Private Fleet (Bare Metal)

Reserved Capacity

$0.0261

/ vCPU

/ HOUR

Billed Monthly, Always On

$280 per host/month (12 mo rate), or $350 monthly

Optimize the cost effectiveness of your game server with egress-free hosting of Private Fleets.

Persistent, available 24/7, exclusive to your studio.

Your bill varies per rate and usage; which can vary per game type, player count, & more.

Your bill varies per rate and usage; which can vary per game type, player count, & more.

Model your usage with our estimate calculator ->

Model your usage with our estimate calculator ->

Edgegap's features & price: detailed comparison between Edge Cloud & Private Fleets

Edgegap's features & price: detailed comparison between Edge Cloud & Private Fleets

COMPARE

Free Trial

Edge Cloud

Private Fleets

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

Capabilities are unlocked when a credit card is added to the account.

COMPARE

Free Trial

Edge Cloud

Private Fleets

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

Capabilities are unlocked when a credit card is added to the account.

COMPARE

Free Trial

Edge Cloud

Private Fleets

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

Capabilities are unlocked when a credit card is added to the account.