Discover how Edgegap works

Discover how Edgegap works

Nakama

Deploy to Edgegap

Published

Published

Published

Last reviewed for accuracy

Last reviewed for accuracy

Last reviewed for accuracy

Nakama: How to start Edgegap dedicated servers from your Nakama matchmaker

Nakama: How to start Edgegap dedicated servers from your Nakama matchmaker

This guide shows you how to keep Nakama by Heroic Labs for your accounts, social features and matchmaking, and start an Edgegap dedicated game server for each match: when Nakama's matchmaker groups players, Nakama deploys a server near them and sends every player its address.

Once your game server is containerized, Edgegap deploys it worldwide to 615+ Edge Cloud locations (on-demand) from a simple API call and billed exclusively on usage: no entire server to rent, provision or keep running between matches. For persistent servers of reserved capacity, Edgegap offers Private Fleets.

Nakama and Edgegap connect through Edgegap's Nakama Fleet Manager plugin, a verified integration co-maintained with Heroic Labs. It runs inside your Nakama server, so your Edgegap API token stays on your backend and never reaches a game client.

This guide covers:

  1. Preparing a working Edgegap app version and a Nakama server

  2. Connecting your coding agent to Edgegap (optional)

  3. Adding the Edgegap Fleet Manager to Nakama

  4. Configuring it

  5. Reporting the game server's state to Nakama

  6. Starting a server when Nakama's matchmaker finds a match

  7. Testing with two players

You can do it two ways, and mix them:

  • With a coding agent. Connect Claude Code, Cursor or another agent to the Edgegap MCP server and its agent skills. The agent writes the Nakama module and the game server calls, and checks your app version and deployments. You handle your Nakama and Edgegap dashboards, the secrets, and playtest.

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

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 working Edgegap app version of your game server: a server you deployed and joined at least once. Nakama deploys that version for every match, so it needs a functional, containerized game server to work end to end. If you don't have one yet, use our guides: Unity Engine, Unreal Engine, Godot Engine or Custom Engine. Note its application name, version name and port name (usually gameport).

  • A Nakama server you can add a Go runtime module to: self-hosted with Docker, or on Heroic Cloud.

  • An Edgegap API token, from Dashboard → User Settings → Tokens. It goes only in your Nakama server's configuration. It is organization-wide, so never put it in your game client, your game server, your project files or a chat.

2. Connect your coding agent to Edgegap

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

The Edgegap MCP server lets your agent check your apps and versions, deploy test servers and read their logs on your account. The edgegap-deployments-api agent skill gives it the tested rules for backends that start Edgegap servers, Nakama included.

Claude Code (run in your own terminal, so the token never passes through the chat):

claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user

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

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/edgegap-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:

"List my Edgegap apps and their versions, with each version's ports."

3. Add the Edgegap Fleet Manager to Nakama

The plugin implements Nakama's Fleet Manager: Nakama asks it for a server, and it deploys one on Edgegap and tracks it in Nakama's storage.

Self-hosted Nakama: add the Go package to your runtime module with go get github.com/edgegap/nakama-edgegap, then register it in your module's InitModule:

  • fleetmanager.NewEdgegapFleetManager(ctx, logger, db, nk, initializer), then initializer.RegisterFleetManager(efm).

  • initializer.RegisterAfterAuthenticateCustom(fleetmanager.OnAuthenticateUpdateCustom): stores each player's public IP when they sign in, so Edgegap can place the server near the whole group.

  • initializer.RegisterMatchmakerMatched(...): your callback for step 6.

For a local test, the repository includes a docker-compose.yml and Dockerfile: docker compose up --build -d.

Heroic Cloud: create a Builder from the nakama-edgegap repository (or your fork with your own module code).

With your agent:

"Load the edgegap-deployments-api skill. Add github.com/edgegap/nakama-edgegap to my Nakama Go module: register the Edgegap Fleet Manager, the after-authenticate hook that stores player IPs, and a matchmaker-matched callback that creates an Edgegap instance for the matched users and notifies them. Read every setting from environment variables."

4. Configure the Fleet Manager

Set these environment variables on your Nakama server (on Heroic Cloud, in your instance's configuration):

  • EDGEGAP_API_URL: https://api.edgegap.com

  • EDGEGAP_API_TOKEN: your API token, including its token prefix. Keep it in your secret store.

  • EDGEGAP_APPLICATION: your Edgegap application name.

  • INITIAL_EDGEGAP_VERSION: the app version to deploy, used until you set another one.

  • EDGEGAP_PORT_NAME: the port players connect to, usually gameport.

  • NAKAMA_ACCESS_URL: the public https:// address of your Nakama server, which game servers call back.

Optional: EDGEGAP_POLLING_INTERVAL (default 15 minutes), NAKAMA_CLEANUP_INTERVAL (1 minute) and NAKAMA_RESERVATION_MAX_DURATION (30 seconds). Keep both background workers on in production.

Ship a new server build without restarting Nakama: call the server-to-server RPC update_edgegap_version with {"version": "..."}, using your Nakama HTTP key. It checks the version exists on Edgegap first. Game clients can't call it.

5. Report the game server's state to Nakama

Nakama tracks every server it starts: whether it's ready, who is connected, and how many seats are free. Your game server tells it, using three environment variables the plugin injects into each deployment:

  • NAKAMA_INSTANCE_EVENT_URL: send READY once the server accepts players, ERROR if it can't start the match, and STOP when the match ends. On STOP, Nakama stops the Edgegap deployment.

  • NAKAMA_CONNECTION_EVENT_URL: send the full list of connected user IDs, batched about every 5 seconds.

  • NAKAMA_INSTANCE_METADATA: the match details Nakama created the server with, as JSON.

Unity: the Edgegap Server Nakama Plugin for Unity makes these calls for you. Other engines: three small HTTP calls from your server code.

With your agent:

"In my game server, read NAKAMA_INSTANCE_EVENT_URL, NAKAMA_CONNECTION_EVENT_URL and NAKAMA_INSTANCE_METADATA. Send READY with the instance ID once the server listens, send the connected user IDs every 5 seconds, and send STOP when the match ends."

6. Start a server when Nakama finds a match

  1. Players join Nakama's matchmaker from your game client, as they do today (AddMatchmaker in Nakama's client SDKs).

  2. When Nakama groups them, your matchmaker-matched callback collects the matched user IDs and calls the Fleet Manager's Create with the match size and those users.

  3. The Fleet Manager deploys your app version near the players and waits for the server's READY.

  4. Each player receives a Nakama notification with subject connection-info: IpAddress, DnsName, Port and InstanceId. The client connects to that address and port. If the server can't start, players get create-timeout or create-failed instead: send them back to the queue.

Want players to join servers already running? The plugin also has sample RPCs: instance_list (for example, servers with at least one free seat) and instance_join. Use Nakama's matchmaker for production, and these for testing or a server browser.

7. Test with two players

  1. Make sure no test deployment is still running: the free tier runs one deployment at a time.

  2. Sign two clients in to Nakama and join the matchmaker with both.

  3. In the Edgegap dashboard, a deployment of your version appears in a location near you.

  4. Both clients receive connection-info and connect to the same server.

  5. End the match: the server sends STOP, Nakama stops the deployment, and it disappears from the dashboard.

If players get an address but can't connect, it's the server, not Nakama: deploy your version by hand from the dashboard and join it directly.

Next Steps

Next Steps

Going live? Ask your agent to run the edgegap-launch skill's checklist: version rollouts, restart policy, maximum duration, cost control. No backend yet? Edgegap's hosted matchmaker needs no code to run.

Stuck? Ask your agent to load edgegap-troubleshoot, or ask our team and other studios on the Edgegap Discord.

Frequently Asked Questions

Common questions about hosting Nakama matches on Edgegap's dedicated servers.

Can Nakama start dedicated game servers?

Yes. Nakama's Fleet Manager lets it request a server for each match. Edgegap's Nakama plugin implements it: when Nakama's matchmaker groups players, it deploys an Edgegap server near them and sends every player the address.

Does the Edgegap Nakama plugin work on Heroic Cloud?

Yes. Create a Builder from the nakama-edgegap repository, or from your fork with your own module code, and set the plugin's environment variables on your instance. It also runs on self-hosted Nakama with Docker.

Where does my Edgegap API token go with Nakama?

Only in your Nakama server's configuration, as EDGEGAP_API_TOKEN. Game clients and game servers never hold it: game servers report their state to Nakama through the callback URLs the plugin injects.

How do players get the server address from Nakama?

When the server is ready, Nakama sends each matched player a connection-info notification with the server's IP address, host name, port and instance ID. The client connects to it directly.

Which game engines work with Nakama and Edgegap?

Any engine whose server runs in a Linux container: Unity, Unreal Engine, Godot or your own. Edgegap's Unity plugin makes the server-side Nakama calls for you; other engines make three small HTTP calls.

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

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.0282

/ 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.0282

/ 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.