PlayFlow Cloud Documentation

This guide covers what happens inside your game server build when it runs on the PlayFlow platform.

Reading Session Config

Every time PlayFlow starts your server, it makes the current session’s details available so your server can configure itself dynamically. There are two ways to read them.

Option 1: `playflow.json` (file)

PlayFlow writes a playflow.json file in the root directory, right next to your server executable. This file is written for backwards compatibility with existing SDKs, and it remains fully supported. Example playflow.json:

{
  "instance_id": "i-12345abcdef",
  "region": "us-east",
  "match_id": "match-abc123",
  "version_tag": "my-build",
  "startup_args": "-mode competitive",
  "custom_data": {
    "map_name": "dust2",
    "game_mode": "competitive"
  }
}

playflow.json also contains the server’s api-key (a pf_ key with full access). Never ship this file in a client-facing or WebGL build — treat it as server-side only.

Your server should read this file on startup. For example, you can use the custom_data to tell the server which map to load or what game mode to run.

Option 2: `GET :9090/v1/config` (HTTP)

The PlayFlow agent also serves a live config endpoint at http://localhost:9090/v1/config from inside the machine. Newer integrations can query it instead of reading the file. It returns the same session fields plus the current ttl and the allocated ports array, so it is the best source for reading your server’s port mappings at runtime.

Unity
Other Engines

The SDK provides a helper class to make this easy. Simply call PlayFlowServerConfig.LoadConfig() to get the data.

using PlayFlow;
using UnityEngine;

public class MyGameServer : MonoBehaviour
{
    void Start()
    {
        var config = PlayFlowServerConfig.LoadConfig();
        if (config != null)
        {
            Debug.Log($"Server instance ID is: {config.instance_id}");

            if (config.custom_data.TryGetValue("map_name", out object map))
            {
                Debug.Log($"Loading map: {map}");
                // Your code to load the map...
            }
        }
    }
}

For other engines, you’ll need to read and parse the playflow.json file from the server’s root directory using standard file I/O operations.

Automatic Server Shutdown

Servers stop automatically in two ways: when your process exits, and when a time-to-live (TTL) expires. Both are always enforced.

Shutdown on process exit

For match-based games, you want the server to shut down after the match is over to save costs. When your server process exits, PlayFlow detects it and automatically stops the instance. In Unity, this means all you need to do is call Application.Quit() at the end of a match. PlayFlow will handle the rest, ensuring you only pay for the time your server was actually running.

In the default multi-container model the agent detects exit by watching your game ports go down, which takes up to about 45 seconds after the process exits. A brief lingering running state after Application.Quit() is expected.

Shutdown on TTL

Every server can also carry a TTL — a maximum lifetime after which PlayFlow stops it automatically, even if the process is still running. You set ttl (in seconds) when you start a server; the accepted range is 60–86400 (24 hours). Leaving it unset means no TTL-based auto-shutdown.

On the Free plan, TTL is force-capped at 3600 seconds (1 hour) regardless of the value you request. See Plan Instance Types for per-plan limits.

Next Steps

Now that you understand how the server behaves, learn how to control it from your game client or backend.

Programmatic Access

Start, stop, and list servers using the PlayFlow API and Unity SDK.

​Reading Session Config

​Option 1: playflow.json (file)

​Option 2: GET :9090/v1/config (HTTP)

​Automatic Server Shutdown

​Shutdown on process exit

​Shutdown on TTL

​Next Steps

Programmatic Access

Reading Session Config

Option 1: `playflow.json` (file)

Option 2: `GET :9090/v1/config` (HTTP)

Automatic Server Shutdown

Shutdown on process exit

Shutdown on TTL

Next Steps