Discover how Edgegap works

Discover how Edgegap works

Matchmaking

Matchmaking

and

and

Game Server Hosting

Game Server Hosting

Integration

/

Supabase

/

Supabase

Deploy to Edgegap

Supabase: How to use it as your multiplayer game backend, with dedicated game servers and Matchmaking

Supabase integration guide: use Supabase as your browser game's backend with Edgegap dedicated game servers and matchmaking

This guide shows you how to use Supabase as the backend of your multiplayer game, for sign-in, player profiles, match history and a live leaderboard, while Edgegap's dedicated game servers run the matches: one authoritative server per match, started near its players by Edgegap's matchmaker.

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. In this guide, Edgegap's Matchmaking starts the servers, so only signed-in players can find a match.

Each side does what it is built for. Supabase keeps everything that outlives a match and decides who may queue. Edgegap groups the players, starts a server near them and stops billing when the match ends. The server decides the result, so nothing a player changes in the browser reaches the leaderboard.

Built your game with Lovable? Lovable projects already run on Supabase: sign-in, a Postgres database, Edge Functions and Realtime. What they don’t have is a server that runs the match. This guide adds it: one authoritative game server per match on Edgegap, next to the Supabase backend your game already uses.

This guide covers:

  • Preparing your game, a Supabase project and your Edgegap account

  • Connecting your coding agent to Edgegap (optional)

  • Setting up Supabase: schema, Row Level Security and anonymous sign-in

  • Letting the game server check players, then containerizing it

  • Playing a match locally with Supabase

  • Adding matchmaking through a Supabase Edge Function

  • Recording results and showing a live leaderboard

  • Testing the full loop 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 edgegap-supabase skill writes the schema, the Edge Functions and the game server changes, and runs the Supabase CLI with your consent. You handle the sign-ins, the Edgegap dashboard and playtest.

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

The guide uses Supabase Sumo Push: a Three.js party brawler from Edgegap's mini-games, with Supabase sign-in, profiles and a live leaderboard. It was tested end to end on 3 November 2026 with a hosted Supabase project on the free plan and Edgegap's free tier.

Talk to an Engineer

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.

Who does what

Supabase does

Edgegap does

Signs players in (anonymous sign-in, upgradable to email or OAuth later)

Groups players with the matchmaker

Stores profiles, wins and match history (Postgres with Row Level Security)

Starts a dedicated server near them for each match

Keeps the matchmaker token in an Edge Function and ties every ticket to a player

Gives the page a wss:// address with a valid certificate (TLS Upgrade)

Records the results the game server reports, after checking each player's ticket

Bills the server only while the match runs: the server stops itself

Pushes leaderboard changes to every open page (Realtime)


The browser holds no secret, and the game server holds no Supabase key.

Sumo Push, the Supabase sample browser game: the lobby with Find match and a Supabase leaderboard, and a round in play on an Edgegap game server with bots on a shrinking ring

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 Supabase account. The free plan is enough. The Supabase CLI runs through npx, so there's nothing to install.

  • Node.js 22 or newer, and a containerization tool, running. We recommend Docker Desktop.

  • A browser game with its own Node.js WebSocket game server. No server yet? Start with the Browser Games guide: it builds the server this guide extends.

  • 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 a client, your server image or a chat. This setup never needs it outside your agent.

  • Built with Lovable? Turn on its GitHub sync so the game server can live in the same repository. Then check where its backend lives. If you connected your own Supabase project, steps 3 and 6 work as written. If the app runs on Lovable Cloud, Lovable owns that Supabase project and the Supabase CLI can’t reach it: set secrets and deploy functions through Lovable instead (see step 6).

Shortcut: run the sample first. Clone Supabase Sumo Push, run npm install and npm run dev, then npm run web in a second terminal. Open http://localhost:8080, select Local server and open a second tab to play against yourself. Without Supabase configured, the server lets anyone in and records nothing.

2. Connect your coding agent to Edgegap

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

The Edgegap MCP server lets your agent create apps and versions, deploy servers, read logs and generate matchmaker configurations on your account. The edgegap-supabase skill gives it the files tested with Sumo Push: the database schema, the two Edge Functions, the game server's player check and the browser code. It builds on edgegap-threejs, which holds the game server itself. Creating a Supabase project, pushing the schema, setting secrets and deploying functions change your Supabase account, so the agent asks before it does them.

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 22): { "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }. It asks for the token on first use.

Check it works:

"List my Edgegap apps."

3. Set up your Supabase project

Supabase signs players in and keeps everything that outlives a match. The sample's schema is ready to use: adapt what a profile holds and what a match counts, and keep the ticket checks.

  • Create and link a project: npx supabase login, then npx supabase projects create <name> --org-id <your-org-id> --region <region> and npx supabase link --project-ref <project-ref>. npx supabase orgs list shows your org ID.

  • Push the schema: npx supabase db push --remote applies the sample's migrations: profiles, tickets, matches, Row Level Security and the record_match() function. A trigger creates a profile with a random name for every new player.

  • Turn on anonymous sign-ins: on a project made for this game, npx supabase config push. It sends every Auth setting in config.toml, so on an existing project use the dashboard instead: Authentication → Sign In / Providers → Allow anonymous sign-ins.

  • Point the page at it: copy client/config.js to client/config.local.js and fill in the Project URL and Publishable key from Project Settings → API Keys. The publishable key is made to ship in pages: Row Level Security limits what it can do.

Players get an account without filling in a form. To keep their progress across devices, link an email or OAuth sign-in to the anonymous player later: the player, and their profile, stay the same.

Check before going further: a player can rename themselves, but can't change their wins, create tickets or call record_match().

With your agent:

"Load the edgegap-supabase skill. Create a Supabase project for my game, push the schema with profiles, tickets, matches and Row Level Security, turn on anonymous sign-ins, and check that a player can't change their own wins. Ask me before each change to my Supabase account."

4. Let the game server check players, then containerize it

The game server holds no Supabase key. When a player connects, it checks the player's Supabase access token against your project's public signing keys, and at the end of the match it reports the result through an Edge Function, with a shared secret.

  • Check players: the sample's server/supabase.js verifies access tokens with the jose library, refuses players who aren't signed in, and keeps one connection per player. Without SUPABASE_URL set, it lets anyone in, for local development.

  • Signing keys: new Supabase projects sign tokens with asymmetric keys. If https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json lists no key, switch the project to asymmetric JWT signing keys in the dashboard first.

  • Build and push: after docker login registry.edgegap.com with the username and token from the Container Registry page, run docker build --platform linux/amd64 -t registry.edgegap.com/<project>/<image>:<tag> . and docker push. Tag every build with its time, never latest.

Then create the application and its version in the dashboard:

  • Your image and tag.

  • Port 7777, protocol WS, name gameport, with TLS Upgrade turned on.

  • 0.25 vCPU and 512 MB, and a max duration of 30 minutes as a safety net: the server stops itself.

  • Environment variables: SUPABASE_URL (https://<project-ref>.supabase.co), GAME_SERVER_SECRET (a long random string, marked Secret; you need it again in step 6) and REQUIRE_TICKET = 1, so only matched players get in.

With your agent:

"Using the edgegap-supabase skill, add the Supabase player check and result report to my game server, then containerize it for linux/amd64, push it with a new tag and create the app version: port 7777, protocol WS, TLS Upgrade on, named gameport, with SUPABASE_URL, a secret GAME_SERVER_SECRET and REQUIRE_TICKET=1."

5. Play a match locally with Supabase

Before going online, check that Supabase and your game work together on your machine:

  • Run the game server with your project: SUPABASE_URL=https://<project-ref>.supabase.co npm run dev. It now refuses players who aren't signed in.

  • Open the page (npm run web, then http://localhost:8080). The menu shows the player's generated name, their record and the leaderboard. Change the name: it's saved to the profile.

  • npm test plays a full match with two headless players and checks the phases and the result.

Results are only recorded for matchmaker matches, because they need a ticket. That's the next step.

6. Add matchmaking through an Edge Function

The browser never calls Edgegap's matchmaker. A Supabase Edge Function holds the matchmaker's token, checks the player's session and ties every ticket to a player, so only signed-in players can queue.

  • Create the matchmaker: in the sample's edgegap/matchmaker-config.json, set your application name and version. Its profile is a free-for-all of 2 to 8 players, and a lone player gets a match after 20 seconds, with bots filling the seats. In the dashboard, open Matchmaker, select Create Matchmaker, upload the file and select Create and Start. Copy its API URL and Auth Token.

  • Store them in Supabase: npx supabase secrets set EDGEGAP_MM_URL=<API URL> EDGEGAP_MM_TOKEN=<Auth Token> GAME_SERVER_SECRET=<same secret as step 4>.

  • Deploy the functions: npx supabase functions deploy matchmaking and npx supabase functions deploy report-match. Both check their callers themselves: matchmaking with the player's session, report-match with the shared secret.

Find Match then works in three calls to the matchmaking function: join (a player searching alone is a group of one; it cancels any earlier search), status (the page asks every 1.5 seconds, and gets the wss:// address once a server is assigned) and cancel. Closing the page mid-search also cancels it, so a search left behind doesn't start a server nobody joins.

With your agent:

"Using the edgegap-supabase skill, deploy the matchmaking and report-match Edge Functions with my matchmaker's API URL and Auth Token as Supabase secrets, and wire Find Match in my page to the matchmaking function, with cancel on page close."

On Lovable Cloud? The supabase secrets set and supabase functions deploy commands can’t reach a Lovable Cloud project. Add EDGEGAP_MM_URL, EDGEGAP_MM_TOKEN and GAME_SERVER_SECRET in Lovable’s Secrets panel instead, and let Lovable deploy the matchmaking and report-match functions. This path hasn’t been tested end to end yet.

7. Record results and show a live leaderboard

  • The server decides the result. Players only send inputs. The server owns positions, rounds and the winner.

  • The server reports it. At the end of the match, it posts the result to the report-match function with the shared secret. record_match() only accepts players with their own, unused ticket, so even a leaked secret can't award wins or replay a match.

  • The leaderboard updates live. Supabase Realtime pushes profile changes to every open page.

Host the page anywhere that serves static files: GitHub Pages, Netlify, Vercel or Supabase Storage. If you later add email or OAuth sign-in, add the site's address under Authentication → URL Configuration.

8. Test the full loop with two players

  • Make sure no test deployment is still running. On the free tier, a leftover one blocks the matchmaker's deployment.

  • Open the page in two browser windows with different profiles, or one private window: two windows of the same profile share one Supabase session.

  • Select Find match in both within 20 seconds. Both land on the same Edgegap server.

  • When the match ends, the leaderboard updates on both pages and the server stops its own deployment. In our test, it stopped 14 seconds after the match.

To test without a browser: SUPABASE_URL=… SUPABASE_PUBLISHABLE_KEY=… node tools/e2e.mjs 2 signs in two headless players, plays a full match on Edgegap, reads the result back from Supabase and checks that the server stopped itself.

Before launch: set inspect to false in the matchmaker configuration, lower FIRST_JOIN_TIMEOUT_S for servers whose players never arrive, let players link an email or OAuth sign-in, and clean up old tickets rows. Supabase limits anonymous sign-ins to 30 per hour per IP address by default.

On the free tier, the matchmaker stops 3 hours after each start (restart it from the dashboard) and one deployment runs at a time. Not tested yet: game servers other than Node.js (Unity, Godot, Unreal) checking Supabase tokens, and email or OAuth sign-in.

Next Steps

Next Steps

Going live? Ask your agent to run the edgegap-launch skill's checklist.

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 using Supabase as your game backend with Edgegap's dedicated game servers.

Can Supabase host my real-time game server?

Supabase runs your database, sign-in, Edge Functions and Realtime updates. A real-time match needs a process that runs the game's rules for the whole match, near its players. Edgegap runs that process, one per match, and stops it when the match ends.

Does the game server need a Supabase key?

No. It checks each player's access token against your project's public signing keys, and reports results through an Edge Function with a shared secret. Your Supabase secret key never leaves Supabase.

Can players cheat their way onto the leaderboard?

The game server decides every result, Row Level Security stops players from changing their own wins, and record_match() only accepts players with their own, unused matchmaking ticket.

Do players need to create an account?

No form to fill in: they're signed in anonymously the first time they play, and come back as the same player on the same browser. Link an email or OAuth sign-in later to keep their progress across devices.

Does this work with Unity, Godot or Unreal game servers?

The schema, the Edge Functions and the Find Match flow are the same, over HTTP. The game server needs a JWT library that verifies ES256 tokens against your project's signing keys. Only the Node.js server has been tested on Edgegap.

Can I use this with a game built in Lovable?

Yes. Lovable projects use Supabase for their backend, so the sign-in, database and Edge Function parts of this guide fit them as they are. Sync the project to GitHub, add the game server, and host it on Edgegap. With your own Supabase project connected, follow the steps as written. On Lovable Cloud, set the secrets in Lovable’s Secrets panel and let Lovable deploy the functions: the Supabase CLI can’t reach those projects, and moving one to your own Supabase account later means migrating it by hand. The steps were tested with the Sumo Push sample, not yet with a Lovable project.

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.

+58% Average Latency Reduction

+58% Average Latency Reduction

14M CCU Rapid-Scaling

14M CCU Rapid-Scaling

+615 Locations Worldwide

+615 Locations Worldwide

~2s. Median Game Server Boot Time

~2s. Median Game Server Boot Time

Multi-Version Support & Rolling Updates

Multi-Version Support & Rolling Updates

91% Fill Rate Matchmaking

91% Fill Rate Matchmaking

Cross-Platform Compatibility

Cross-Platform Compatibility

Instant DDoS Protection

Instant DDoS Protection

Multi-Cloud Across 17+ Providers for 99.99% Availability

Multi-Cloud Across 17+ Providers for 99.99% Availability

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.

615+ locations worldwide

$0.10/GB of monthly Egress

0.25 to 4 vCPU deployments

Compare features & pricing

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.

615+ locations worldwide

$0.10/GB of monthly Egress

0.25 to 4 vCPU deployments

Compare features & pricing

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.

58 locations worldwide

Egress Included

16 vCPU/host total (14.7 usable)

Compare features & pricing

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.

58 locations worldwide

Egress Included

16 vCPU/host total (14.7 usable)

Compare features & pricing

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

BILLING & PRICE

Rate per vCPU

Free

$0.00115/vCPU/minute

$0.0261/vCPU/hour

Pricing Model

Free

On-demand (usage-based)

Reserved capacity

Billing

No credit card required

Yes, via Stripe

Yes, via Stripe

Commitment

None

None

1, 6 or 12 months (incl. discount)

Egress

N/A

$0.10/GB month

Incl. 6 TB per host, per month

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

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

China deployments

DDoS protection

Fully-managed clusters

Always-on deployments

COMPARE

Free Trial

Edge Cloud

Private Fleets

BILLING & PRICE

Rate per vCPU

Free

$0.00115 / vCPU / minute

$0.0261/vCPU/hour

Pricing Model

Free

On-demand (usage-based)

Reserved capacity

Billing

No credit card required

Yes, via Stripe

Yes, via Stripe

Commitment

None

None

1, 6 or 12 months (incl. discount)

Egress

N/A

$0.10/GB month

Incl. 6 TB per host, per month

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

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

China deployments

DDoS protection

Fully-managed clusters

Always-on deployments

COMPARE

Free Trial

Edge Cloud

Private Fleets

BILLING & PRICE

Rate per vCPU

Free

$0.00115/vCPU/minute

$0.0261/vCPU/hour

Pricing Model

Free

On-demand (usage-based)

Reserved capacity

Billing

No credit card required

Yes, via Stripe

Yes, via Stripe

Commitment

None

None

1, 6 or 12 months (incl. discount)

Egress

N/A

$0.10/GB month

Incl. 6 TB per host, per month

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

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

China deployments

DDoS protection

Fully-managed clusters

Always-on deployments