> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playflowcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Lifecycle

> Understand how your dedicated server works on PlayFlow, from configuration to automatic shutdown.

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`:**

```json theme={null}
{
  "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"
  }
}
```

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

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.

<Tabs>
  <Tab title="Unity">
    The SDK provides a helper class to make this easy. Simply call `PlayFlowServerConfig.LoadConfig()` to get the data.

    ```csharp theme={null}
    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...
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Other Engines">
    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.
  </Tab>
</Tabs>

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

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

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

<Warning>
  On the **Free** plan, TTL is force-capped at `3600` seconds (1 hour) regardless of the value you request. See [Plan Instance Types](/fundamentals/plan-instance-types) for per-plan limits.
</Warning>

## Next Steps

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

<Card title="Programmatic Access" icon="code" href="/unity/programmatic-access" arrow="true" cta="Learn More">
  Start, stop, and list servers using the PlayFlow API and Unity SDK.
</Card>