# Server Browser

**Welcome to Edgegap Server Browser OPEN BETA.** We hope you enjoy the opportunity to preview our new service, and help shape it's future through roundtable discussions in our Discord.

Server Browser is a managed service for [#match-bound](https://docs.edgegap.com/orchestration/deployments#match-bound "mention") and [Persistent](https://docs.edgegap.com/learn/orchestration/persistence) servers:

* **help players search and join suitable servers** based on capacity, latency, or game parameters;
* **pre-warm new servers** to serve global audiences at scale and prevent frustrating queues;
* **streamline server operations** including updates, restarts, persistence, meshing, and more.

{% hint style="success" %}
Looking to match players based on strict rules, without allowing server choice? Consider [matchmaking](https://docs.edgegap.com/learn/matchmaking "mention").
{% endhint %}

<figure><img src="proxy.php?url=https://3027732442-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FwKrq9tLaamRoM6vSLXZu%2Fimage.png?alt=media&#x26;token=83756c6f-d413-4ac1-988e-b90e7fa7a0a6" alt=""><figcaption></figcaption></figure>

## ✔️ Preparation

**Testing this service is entirely free, no credit card required.**

Free Tier allows up to 3 hours of runtime on our shared test cluster, after each restart.

This tutorial assumes you have already:

* [understood Edgegap’s deployment model](https://docs.edgegap.com/orchestration/deployments#id-1.-just-in-time-deployment-dedicated-servers),
* published your server application on Edgegap ([unreal-engine](https://docs.edgegap.com/unreal-engine "mention"), [unity](https://docs.edgegap.com/unity "mention")),
* successfully connected from a game client to your server on Edgegap.

### Flow and Hierarchy

<figure><img src="proxy.php?url=https://3027732442-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fnwlt2Ot2ahlyLvI7kdGx%2Fimage.png?alt=media&#x26;token=14b5a6c8-48c8-4f23-a50a-0783acab14e3" alt=""><figcaption><p>Server Browser: Flow and Hierarchy</p></figcaption></figure>

Server Browser offers two main features:

[#start-browsing](#start-browsing "mention") with Game Clients to:

* Discover and find suitable server instances, view slots, and reserve available capacity.
* Reserve seats in an instance slot, retrieve connection details, and connect to servers.
* Authenticate player connections from Deployments using [Federated Identity](#user-content-fn-1)[^1].
* Update instance slots' available capacity and/or metadata to modify discovery criteria.

[#automated-scaling](#automated-scaling "mention") (optional) with Scaling Policies to:

* Monitor available server instances, slots, capacity - per region and/or other criteria.
* Deploy Servers to increase capacity with prewarming or just-in-time scaling.
* Automate ops with special policies for demos, updates, testing, QA, tournaments, and more.

{% hint style="info" %}
After release, **your server browser will need to run 24/7** to ensure players across the world can join servers.
{% endhint %}

## ▶️ Start Browsing

Learn about server/player lifecycle and their responsibilities to ensure efficient server use.

### Authenticate

All requests must send an `Authorization`  HTTP header with your secret **Auth Token:**

<pre><code>Authorization: <a data-footnote-ref href="proxy.php?url=#user-content-fn-2">xxxxxxxx-e458-4592-b607-c2c28afd8b62</a>
</code></pre>

{% hint style="warning" %}
**Keep your tokens secret and safe! Edgegap staff will never ask you for your tokens.**
{% endhint %}

Server Browser automatically generates two types of tokens:

* **Server Token** - required for [Server API](#server-lifecycle) methods, can be [injected as app version variable](https://docs.edgegap.com/orchestration/application-and-versions#injected-variables).
  * Grants access to all API methods, and is handy for testing, devops, or custom orchestration.
* **Client Token** - required for [Monitor API and Seat Reservation API](#player-lifecycle) used by Game Clients.
  * We recommend storing this token in a third party secret store to make token rotation easier.

### Discover Instance

**New** [deployments](https://docs.edgegap.com/learn/orchestration/deployments "mention") **must create a new Instance with at least one Slot when initialized.**

{% hint style="info" %}
See [#automated-scaling](#automated-scaling "mention") to learn about Scaling Policies and start deployments automatically.
{% endhint %}

**Optional custom metadata parameters** for player filtering, sorting, and browsing.

Examples:

* slot information - team capacity and team-specific metadata (e.g. team name),
* name and tags - customizable, unique, human-readable and searchable labels;
* connection details - URL, IP, external ports, or other parameters;
* compatibility data - server version or supported client versions;
* latency qualifiers - city and region identifiers, and assigned [ping-beacons](https://docs.edgegap.com/learn/orchestration/ping-beacons "mention") details;
* game parameters - level/scene/map, game mode, difficulty, mods used;
* any other custom parameters to help players filter and find a suitable server.

{% hint style="info" %}
Metadata parameters above are just examples, you can define any parameters including the above. All  metadata parameters are optional, and some instances may not need to define all parameters.
{% endhint %}

Metadata supports string keys and values containing string, number, boolean, or array of strings.

{% hint style="success" %}
To serialize nested objects try encoding their accessor path in the key as `"object.child.property"`.
{% endhint %}

Servers may **update instance or slot metadata anytime** to modify their discoverability criteria.

**Server Instances must periodically send a keep-alive heartbeat** to verify their ongoing availability and prevent players from joining crashed or offline servers. Missing heartbeat for the configured expiration period will automatically delete instance and any pending seat reservations.

{% hint style="info" %}
See [persistence](https://docs.edgegap.com/learn/orchestration/persistence "mention") for managing persistent world state and [#active-caching](https://docs.edgegap.com/orchestration/application-and-versions#active-caching "mention") for faster deployments.
{% endhint %}

### Search and Browse

Players may list server instances and [paginate through results](#pagination) to find a server they'd like to join. To display ping (latency) data, read each instance's [ping-beacons](https://docs.edgegap.com/learn/orchestration/ping-beacons "mention") details and [measure latency](https://docs.edgegap.com/orchestration/ping-beacons#measuring-round-trip-time).

Instances and slots may be filtered by joinable seats or [indexed metadata parameters](#configuration).

<table><thead><tr><th width="170">Parameter</th><th width="135">Operators</th><th>Example Filter (based on Simple Example)</th></tr></thead><tbody><tr><td><code>"joinable_seats"</code></td><td><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-3"><code>eq</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-5"><code>ne</code></a> or </p><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-7"><code>lt</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-8"><code>le</code></a> or </p><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-9"><code>gt</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-10"><code>ge</code></a></p></td><td><pre><code>?filter=<a data-footnote-ref href="proxy.php?url=#user-content-fn-4">joinable_seats gt 0</a>
&#x26;orderby=<a data-footnote-ref href="proxy.php?url=#user-content-fn-6">joinable_seats desc</a>
</code></pre></td></tr><tr><td><code>"string"</code><br>(metadata)</td><td><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-3"><code>eq</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-5"><code>ne</code></a> or </p><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-7"><code>lt</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-8"><code>le</code></a> or </p><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-9"><code>gt</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-10"><code>ge</code></a>  or<br><code>contains</code></p></td><td><pre><code>?filter=metadata.custom_name contains 'my game'
and metadata.server_version le '1.1.0'
and metadata.server_version ge '1.0.0'
&#x26;orderby=metadata.custom_name asc
</code></pre></td></tr><tr><td><p><code>"int"</code> , or <code>"float"</code></p><p>(metadata)</p></td><td><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-3"><code>eq</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-5"><code>ne</code></a> or </p><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-7"><code>lt</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-8"><code>le</code></a> or </p><p><a data-footnote-ref href="proxy.php?url=#user-content-fn-9"><code>gt</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-10"><code>ge</code></a>  </p></td><td><pre><code>?filter=metadata.xp_multiplier gt 1.0
&#x26;orderby=metadata.xp_multiplier desc
</code></pre></td></tr><tr><td><code>"bool"</code><br>(metadata)</td><td><a data-footnote-ref href="proxy.php?url=#user-content-fn-3"><code>eq</code></a>  or <a data-footnote-ref href="proxy.php?url=#user-content-fn-5"><code>ne</code></a></td><td><pre><code>?filter=metadata.allows_new_connections eq true
</code></pre></td></tr></tbody></table>

{% hint style="success" %}
Filter by regions and/or cities to narrow down selection before measuring latency to servers.
{% endhint %}

{% hint style="info" %}
Learn about cursor-based [#pagination](#pagination "mention") to let users fetch more results.
{% endhint %}

### Reserve Seats

Before joining a server, a seat reservation is required to ensure that the instance offers sufficient available capacity. Reservations can include a group of players or a solo individual.

**Reservations exceeding slot's joinable seat capacity will be automatically rejected** ([409 Conflict](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/409)). Joinable seats are any available seats which have not been reserved by other players yet.

Federated Identity: Players must provide a unique third party player ID in their reservation. Sending the same ID once they [#connect-to-server](#connect-to-server "mention") will allow the server to verify their identity.

Once a reservation is made successfully ([200 OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200)) players should attempt connecting immediately. Pending **reservations will expire after 30 seconds unless they are confirmed** by your server.

{% hint style="info" %}
Server may forcefully change any slot's capacity, add, delete, or update any slots. **All reservations for a given slot will be removed if any pending reservations exceed new available slot capacity.**
{% endhint %}

### Connect to Server

Once a player found a suitable instance, they can **retrieve required connection details from metadata** (URL, IP, [External Port](https://docs.edgegap.com/orchestration/application-and-versions#port-mapping)). As soon as the seat reservation is made, **players may proceed to connect to your deployment's game server and pass their player ID**.

{% tabs %}
{% tab title="Unreal Engine" %}
To **connect from PIE (Editor)** during development and testing, press the tilde key `~`  and type `open {URL}:{port}` and wait for your editor to load the map.

{% hint style="success" %}
In case of failed connections or dark screen consult our [troubleshooting guide](https://docs.edgegap.com/unreal-engine#troubleshooting-and-faq-1).
{% endhint %}
{% endtab %}

{% tab title="Unity" %}
To **connect your Unity Editor** or **game client** to your cloud deployment, input:

* **Deployment** **URL** pointing to the server's IP, usually in `NetworkManager`  component.
* **External port** mapping to the [server's internal listen port](https://docs.edgegap.com/learn/advanced-features/application-and-versions#port-mapping), usually in a Transport component.

{% hint style="success" %}
In case of connection timeout or other issues consult our [troubleshooting guide](https://docs.edgegap.com/unity#troubleshooting-and-faq-4).
{% endhint %}
{% endtab %}
{% endtabs %}

To authenticate new connections, **your server must send a bulk reservation confirmation** request with all new players' IDs, receiving information in confirmation response:

* assignment of accepted player reservations to their preferred slot,
* assignment of expired player reservations to their preferred slot,
* a list of unknown player IDs.

Your **server may decide how to handle each group of players** and whether to allow or kick/ban expired or rejected users. Each of the **instance's slots must be updated immediately with the new available seat count** to ensure new reservations won't exceed capacity.

### Abandon Server

When players leave, the server must update their assigned slot to reflect new available seat capacity.

{% hint style="success" %}
If your game design allows a reconnection period, your server may wait before releasing seats.
{% endhint %}

We recommend stopping servers with no players to optimize your hosting cost. Waiting a few minutes before doing so can reduce the amount of restarts during short periods of idling.

Read about [#recovery-objectives](https://docs.edgegap.com/orchestration/persistence#recovery-objectives "mention") to prevent frustrating persistent server rollbacks.

## 🚀 Automated Scaling

Server Browser is compatible with several different methods of autoscaling:

* **pre-warming method** - starting servers strictly with Server Browser scaling policies,
* **just-in-time method** - start through [matchmaking](https://docs.edgegap.com/learn/matchmaking "mention") and [fill with Server Browser](#start-browsing),
* **custom autoscaler** - start through custom game backend and [fill with Server Browser](#start-browsing).

The following guide will focus on **pre-warming with Scaling Policies** as the primary method.

{% hint style="success" %}
Learn how to stop deployments in [Unreal Engine](https://docs.edgegap.com/unreal-engine#stop-deployments), [Unity](https://docs.edgegap.com/unity#stop-deployments), or [with API](https://docs.edgegap.com/docs/api/dedicated-servers#delete-v1-self-stop-request_id-access_point_id) to manage lifecycle reliably.
{% endhint %}

### Monitor Capacity

Scaling policies continuously refresh the list of your server instances (discovered Deployments), repeating every [`monitoring_interval`](#user-content-fn-11)[^11] . Each policy can include a filter using the same [filtering syntax](#search-and-browse) as players do when searching for instances - per region, capacity, or other criteria.

Your configured [`minimum_active_instances`](#user-content-fn-12)[^12]  amount can be treated either as a:

* **fixed capacity** of deployments that you wish to keep running at all times,
* **pre-warm standby** deployment buffer to hide initialization delays.

#### Fixed Capacity

Keeping a fixed amount of servers can be useful particularly for games with [persistence](https://docs.edgegap.com/learn/orchestration/persistence "mention"), particularly when such games offer players to rent [#community-servers](https://docs.edgegap.com/orchestration/persistence#community-servers "mention").

This type of policy configuration is also sometimes used for Quality Assurance, Tournaments, Closed Alphas, Publisher Demos, or other kinds of limited capacity events and operations.

{% hint style="info" %}
Scaling policy helps you automatically restart and recycle crashed or stopped servers on the fly.
{% endhint %}

#### Pre-Warm Standby

Starting servers ahead of player demand can be advantageous when:

* launch major releases or updates and expect rapid inflow of players in a short timespan,
* or server initialization requires more than 30 seconds (not including deployment time),
* or game implements meshing strategies requiring complex or circular network dependencies.

{% hint style="info" %}
With matchmaking, you'll need to [#backfill-match](https://docs.edgegap.com/matchmaking/matchmaker-in-depth#backfill-match "mention") to utilize this capacity before starting new deployments.
{% endhint %}

### Deploy Servers

New deployments will be started automatically when the amount of monitored server instances falls below the configured minimum of active instances. All deployments are requested immediately and retried infinitely after [`deployment_registration_period`](#user-content-fn-11)[^11]  elapsed.

{% hint style="warning" %}
Verify that new deployments [perform auto-discovery and create instances](#discover-instance) matching your policy filter correctly, or **your policy may loop infinitely and create large amounts of unused deployments**!&#x20;
{% endhint %}

When defining a deployment request for your policy, we use the standard deployment parameters allowing deployment in Private Fleets (with Overflow to Cloud) or directly to Cloud:

* [**application and version**](https://docs.edgegap.com/learn/orchestration/application-and-versions) - build version, resources, and other orchestration parameters,
* **users** - a single set of coordinates for preferred [server placement](https://docs.edgegap.com/orchestration/deployments#regional-standby),
* [**private host IDs**](https://docs.edgegap.com/learn/orchestration/private-fleets) - leave empty for cloud, or specify hosts within the desired region,
* [**tags**](https://docs.edgegap.com/orchestration/deployments#dashboard-monitoring) - tag with policy name to find deployments started with this policy later on,
* [**environment variables**](https://docs.edgegap.com/orchestration/deployments#custom-variables) - pass custom parameters and secrets to servers,
* [**webhooks**](https://docs.edgegap.com/orchestration/deployments#webhooks-and-postbacks) - notify your game backend (or matchmaker) of deployment lifecycle events,
* [**require cached locations**](https://docs.edgegap.com/orchestration/application-and-versions#active-caching) - if you prefer faster deployments only in cached locations.

### Example Policies

Test and modify any of these policies as you need. Most games will use multiple policies.

<details>

<summary>🍀 Quality Assurance Pool (Minimal Example)</summary>

A simple policy to keep one server deployed for testing at all times.

<pre class="language-json" data-title=""><code class="lang-json">{
  "name": "sb-qa-pool",
  <a data-footnote-ref href="proxy.php?url=#user-content-fn-13">"filter"</a>: "metadata.POLICY_NAME eq 'sb-qa-pool'",
  "deployment_request": {
    "private_host_ids": [],
    "application": <a data-footnote-ref href="proxy.php?url=#user-content-fn-14">"my-game-server"</a>,
    "version": <a data-footnote-ref href="proxy.php?url=#user-content-fn-15">"2024.01.30-16.23.00-UTC"</a>,
    "users": [
      {
        "user_type": "geo_coordinates",
        "<a data-footnote-ref href="proxy.php?url=#user-content-fn-16">user_data</a>": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-qa-pool"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-qa-pool",
        "is_hidden": false
      }
    ]
  },
  "minimum_active_instances": 1
}
</code></pre>

</details>

<details>

<summary>🌡️ Pre-Warm Release Per Region</summary>

Each region starts a deployments prior to the release in anticipation of demand.

<pre class="language-json" data-title=""><code class="lang-json">{
  "name": "sb-v1.0.0-chicago",
  <a data-footnote-ref href="proxy.php?url=#user-content-fn-17">"filter"</a>: "joinable_seats gt 0 and metadata.POLICY_NAME eq 'sb-v1.0.0-chicago'",
  "deployment_request": {
    "private_host_ids": [],
    "application": <a data-footnote-ref href="proxy.php?url=#user-content-fn-14">"my-game-server"</a>,
    "version": <a data-footnote-ref href="proxy.php?url=#user-content-fn-15">"2024.01.30-16.23.00-UTC"</a>,
    "users": [
      {
        "user_type": "geo_coordinates",
        "<a data-footnote-ref href="proxy.php?url=#user-content-fn-16">user_data</a>": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-v1.0.0-chicago"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-v1.0.0-chicago",
        "is_hidden": false
      }
    ]
  },
  <a data-footnote-ref href="proxy.php?url=#user-content-fn-18">"minimum_active_instances"</a>: 10
}
</code></pre>

</details>

<details>

<summary>❄️ Server Meshing Group</summary>

One policy per group of servers, where game backend adds new policy for each group.

<pre class="language-json" data-title=""><code class="lang-json">{
  "name": "sb-meshgroup-pqyt8sxcb",
  <a data-footnote-ref href="proxy.php?url=#user-content-fn-13">"filter"</a>: "metadata.POLICY_NAME eq 'sb-meshgroup-pqyt8sxcb'",
  "deployment_request": {
    "private_host_ids": [],
    "application": <a data-footnote-ref href="proxy.php?url=#user-content-fn-14">"my-game-server"</a>,
    "version": <a data-footnote-ref href="proxy.php?url=#user-content-fn-15">"2024.01.30-16.23.00-UTC"</a>,
    "users": [
      {
        "user_type": "geo_coordinates",
        "<a data-footnote-ref href="proxy.php?url=#user-content-fn-16">user_data</a>": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-meshgroup-pqyt8sxcb"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-meshgroup-pqyt8sxcb",
        "is_hidden": false
      }
    ],
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-19">"webhook_on_ready"</a>: {
      "url": "https://my-webhook.com"
    },
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-20">"webhook_on_terminated"</a>: {
      "url": "https://my-webhook.com"
    }
  },
  <a data-footnote-ref href="proxy.php?url=#user-content-fn-21">"minimum_active_instances"</a>: 9
}
</code></pre>

</details>

<details>

<summary>🔑 Community Server</summary>

One policy per server owner, passing a custom password used for server authentication.

<pre class="language-json" data-title=""><code class="lang-json">{
  "name": "sb-owner-jnjnc8mid",
  <a data-footnote-ref href="proxy.php?url=#user-content-fn-22">"filter"</a>: "metadata.POLICY_NAME eq 'sb-owner-jnjnc8mid'",
  "deployment_request": {
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-23">"private_host_ids"</a>: ["alpha-north-america-95fab093"],
    "application": <a data-footnote-ref href="proxy.php?url=#user-content-fn-14">"my-game-server"</a>,
    "version": <a data-footnote-ref href="proxy.php?url=#user-content-fn-15">"2024.01.30-16.23.00-UTC"</a>,
    "users": [
      {
        "user_type": "geo_coordinates",
        "<a data-footnote-ref href="proxy.php?url=#user-content-fn-16">user_data</a>": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["community", "sb-owner-jnjnc8mid"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-owner-jnjnc8mid",
        "is_hidden": false
      },
      {
        "key": "SB_SERVER_PASSWORD",
        "value": "password1234",
        "is_hidden": false
      }
    ],
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-19">"webhook_on_ready"</a>: {
      "url": "https://my-webhook.com"
    },
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-24">"webhook_on_error"</a>: {
      "url": "https://my-webhook.com"
    },
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-25">"webhook_on_terminated"</a>: {
      "url": "https://my-webhook.com"
    }
  },
  "minimum_active_instances": 1
}
</code></pre>

</details>

<details>

<summary>🔒 Region-Locked MMO</summary>

Each region adds deployments as available capacity drops below a threshold.

<pre class="language-json" data-title=""><code class="lang-json">{
  "name": "sb-mmo-chicago",
  <a data-footnote-ref href="proxy.php?url=#user-content-fn-26">"filter"</a>: "joinable_seats gt 5 and metadata.POLICY_NAME eq 'sb-mmo-chicago'",
  "deployment_request": {
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-23">"private_host_ids"</a>: ["alpha-north-america-95fab093"],
    "application": <a data-footnote-ref href="proxy.php?url=#user-content-fn-14">"my-game-server"</a>,
    "version": <a data-footnote-ref href="proxy.php?url=#user-content-fn-15">"2024.01.30-16.23.00-UTC"</a>,
    "users": [
      {
        "user_type": "geo_coordinates",
        "<a data-footnote-ref href="proxy.php?url=#user-content-fn-16">user_data</a>": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-mmo-chicago"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-mmo-chicago",
        "is_hidden": false
      }
    ],
    <a data-footnote-ref href="proxy.php?url=#user-content-fn-25">"webhook_on_terminated"</a>: {
      "url": "https://my-webhook.com"
    }
  },
  "minimum_active_instances": 3
}
</code></pre>

</details>

## ⚙️ Configuration

Server Browser API is generated from a JSON configuration specified when you create a new (or quick-restart) Server Browser. You may specify server and slot expiration, and custom metadata:

{% tabs %}
{% tab title="🍀 Simple Example" %}

<pre class="language-json" data-title="sb-simple-example-v0-0-5.json"><code class="lang-json">{
	"version": "0.0.5",
	"server_instances": {
		"expiration_period": "1m",
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string"
		}
	},
	"server_instance_slots": {
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string"
		}
	},
	"seat_reservations": {
		"expiration_period": "1m"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "1m"
	}
}
</code></pre>

{% endtab %}

{% tab title="🎈 Social Games" %}

<pre class="language-json" data-title="sb-social-example-v0-0-5.json"><code class="lang-json">{
	"version": "0.0.5",
	"server_instances": {
		"expiration_period": "15s",
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string",
			"third_party_id": "string",
			"level": "string",
			"mode": "string",
			"difficulty": "string",
			"seed": "string",
			"max_player_count": "int",
			"app_version": "string",
			"BEACON_PUBLIC_IP": "string",
			"BEACON_PORT_UDP_EXTERNAL": "string",
			"BEACON_PORT_TCP_EXTERNAL": "string"
		}
	},
	"server_instance_slots": {
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string",
			"third_party_id": "string",
			"max_player_count": "int",
			"avg_player_latency": "int",
			"player_ids": "string"
		}
	},
	"seat_reservations": {
		"expiration_period": "30s"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "30s"
	}
}
</code></pre>

{% endtab %}

{% tab title="🤝 Cooperative Games" %}

<pre class="language-json" data-title="sb-cooperative-example-v0-0-5.json"><code class="lang-json">{
	"version": "0.0.5",
	"server_instances": {
		"expiration_period": "15s",
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string",
			"third_party_id": "string",
			"level": "string",
			"mode": "string",
			"difficulty": "string",
			"avg_player_rank": "int",
			"max_player_count": "int",
			"app_version": "string",
			"DEPLOYMENT_TAGS": "string",
			"MM_MATCH_ID": "string",
			"MM_INTERSECTION": "string",
			"MM_EQUALITY": "string"
		}
	},
	"server_instance_slots": {
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string",
			"third_party_id": "string",
			"max_player_count": "int",
			"player_ids": "string"
		}
	},
	"seat_reservations": {
		"expiration_period": "30s"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "30s"
	}
}
</code></pre>

{% endtab %}

{% tab title="⚔️ Competitive Games" %}

<pre class="language-json" data-title="sb-competitive-example-v0-0-5.json"><code class="lang-json">{
	"version": "0.0.5",
	"server_instances": {
		"expiration_period": "15s",
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string",
			"third_party_id": "string",
			"avg_player_rank": "int",
			"max_player_count": "int",
			"is_ranked": "bool",
			"app_version": "string",
			"HOST_BASE_CLOCK_FREQUENCY": "int",
			"MM_MATCH_ID": "string",
			"MM_INTERSECTION": "string",
			"MM_EQUALITY": "string"
		}
	},
	"server_instance_slots": {
		"<a data-footnote-ref href="proxy.php?url=#user-content-fn-27">indices</a>": {
			"name": "string",
			"third_party_id": "string",
			"max_player_count": "int",
			"avg_player_rank": "int",
			"avg_player_latency": "int"
		}
	},
	"seat_reservations": {
		"expiration_period": "30s"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "15s"
	}
}
</code></pre>

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For best performance, avoid specifying indices for metadata not used for filtering or sorting. Non-indexed params can be still set and read with server instance or slot details API methods, see [#api](#api "mention").
{% endhint %}

## ☁️ Hosting Cluster

Server Browser is conveniently hosted and managed 24/7 around the clock by Edgegap.

Choose a hosting option best suited for your goal:

* **Free Cluster (shared)** to test all features and explore synergies with your design,
  * shuts down after 3 hours automatically, requiring restart to continue testing.
* **Private Cluster** **(dedicated)** to ensure a stable environment for your production needs,
  * pick your region and get 24/7 support for live games to release with confidence.

### Private Cluster Tiers

We currently offer [3 private cluster tiers](https://edgegap.com/resources/pricing#managed-infrastructure) to cater to everybody’s needs:

<table><thead><tr><th width="160">Tier</th><th align="right">Hobbyist Tier</th><th align="right">Studio Tier</th><th align="right">Enterprise Tier</th></tr></thead><tbody><tr><td>Best Suited For</td><td align="right">enthusiasts,<br>solo developers</td><td align="right">commercial releases</td><td align="right">high-traffic launches</td></tr><tr><td>Resources</td><td align="right">1 vCPU + 2GB RAM</td><td align="right">6 vCPU + 12GB RAM</td><td align="right">18 vCPU + 48GB RAM</td></tr><tr><td>Redundancy</td><td align="right">1x virtual node</td><td align="right">3x virtual nodes</td><td align="right">3x virtual nodes</td></tr><tr><td>Rate Limit (req/s)</td><td align="right">200</td><td align="right">750</td><td align="right">2,000</td></tr><tr><td>Price, hourly</td><td align="right">$0.0312</td><td align="right"> $0.146</td><td align="right">$0.548</td></tr><tr><td><strong>Price, 30 days</strong><br>(nonstop usage)</td><td align="right"><strong>$22.464</strong></td><td align="right"><strong>$105.12</strong></td><td align="right"><strong>$394.56</strong></td></tr></tbody></table>

Upgrade to a private cluster with one click to benefit from highly available hosting maintained by Edgegap team with 24/7 live support for publicly released games.

Resource requirements for your instance will depend on factors:

* **number of players** - more players result in more API requests,
* **number of requests per player** - faster retries increase service load and consume resources,
* **number of servers** - more servers result in more data stored and more API requests,
* **client retry fallback logic** - retrying with jittered backoff helps spread traffic burst peaks,
* **average match duration** - shorter sessions require more frequent server browser interaction.

{% hint style="info" %}
Our clusters use cloud machines featuring AMD/Intel CPUs with clock speed 2.4 - 3.2 GHz.
{% endhint %}

## 📗 API

Game Clients and Dedicated Servers send API requests throughout their lifecycle to Server Browser.

{% hint style="info" %}
Unity/Android - consider [using raw string interpolation](https://www.c-sharpcorner.com/article/convert-string-to-json-in-c-sharp/) to prevent code stripping of hardcoded JSONs.
{% endhint %}

{% hint style="success" %}
**Swagger Web UI**: deploying your service will generate an openAPI specification and a convenient web UI. Open the URL in your browser to view and test all API endpoints, and to review payload examples.
{% endhint %}

{% file src="proxy.php?url=<https://3027732442-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2F0auyzkkQfLfNRgzKbWMn%2Fedgegap-server-browser-005.yaml?alt=media&token=84669896-e7b9-4415-8d66-131badb3fff5>" %}

Import API specification to [Scalar API Web Client](https://client.scalar.com/workspace/default/request/default) or [Swagger Editor](https://editor.swagger.io/) to inspect details.

### Pagination

**Server Browser provides cursor pagination to fetch filtered data incrementally in a specific order.** This approach requires sending a cursor (starting point) and a page size (number of response items) whenever fetching more results, as opposed to the traditional limit-offset pagination.

{% hint style="info" %}
Combined with our proprietary database indexing system developed for game server metadata, cursor pagination provides a fast, consistent, and flexible user experience for filtering highly dynamic data.
{% endhint %}

Our goal is for users to find a suitable server on the first page. For best experience, we recommend showing cached results for previous pages, and only refreshing results when the user clicks Search.

## 🔖 Changelog

#### Semantic Versioning

Our matchmaker uses official [Semantic Versioning](https://semver.org/) guidelines. Each configuration JSON is tied to a specific version of the service. Service version dictates which rules and settings are available in your configuration and API. **Once a version is released, it will never change**.

{% hint style="info" %}
**The latest version of server browser is `0.0.5`** . Keep an eye out for updates and announcements.
{% endhint %}

#### 0.0.5 (Mar 18, 2026)

* Introducing [#automated-scaling](#automated-scaling "mention") and [#example-policies](#example-policies "mention").
* Adding more [#configuration](#configuration "mention") Examples for your inspiration.
* Improved [#flow-and-hierarchy](#flow-and-hierarchy "mention") diagram to get started faster.

#### 0.0.4 (Jan 05, 2026)

* Entering OPEN BETA, introducing [filtering and sorting for server instances and slots](#search-and-browse)!

#### 0.0.3 (Nov 28, 2025)

* Initial release of Server Browser service launched in CLOSED BETA.
* List Servers, Manage Capacity, and Get Connection Details.
* Support for match sessions with Cloud Deployments and always online with Private Fleets.

[^1]: third party player identifiers

[^2]: example value

[^3]: equals

[^4]: finds instances with available seats

[^5]: not equals

[^6]: show more filled instances first

[^7]: lower than

[^8]: lower than or equal

[^9]: greater than

[^10]: greater than or equal

[^11]: see Configuration

[^12]: see Example Policies

[^13]: * fixed capacity
    * assumes instances supply policy name in metadata from injected variable

[^14]: replace with your own application name

[^15]: replace with your own application version

[^16]: Chicago coordinates

[^17]: * deploys when less than 10 joinable instances found
    * assumes instances supply policy name in metadata from injected variable

[^18]: we expect at least 10 deployments in the Chicago region

[^19]: notify game backend when ready

[^20]: notify game backend when stopped

[^21]: 3x3 grid = 9 servers per world

[^22]: * does not monitor capacity
    * assumes instances supply policy name in metadata from injected variable

[^23]: prefer private fleet if capacity available

[^24]: notify game backend when deployment fails

[^25]: notify game backend when server restarts

[^26]: * deploys when less than 3 instances with 5 or less joinable seats are found
    * assumes instances supply policy name in metadata from injected variable

[^27]: indices contain your custom metadata parameters used for filtering or sorting