Skip to main content

​
Pool Servers

Pool servers are pre-provisioned game servers that sit warm and ready to be claimed instantly. Instead of waiting 15-30 seconds for a server to launch on demand, you can claim a pool server and get connection details in milliseconds. This makes pool servers the ideal choice for competitive matchmaking and any game where launch latency matters.

​
How Pool Servers Work

1

Configure your pool

In your project settings, you define which regions and compute sizes you want pre-provisioned, and how many servers to keep warm in each.
2

PlayFlow provisions servers

PlayFlow automatically launches and maintains the configured number of idle servers. These servers are running and ready to accept players, but are not yet assigned to any game session.
3

Claim a server

When your game needs a server (for example, when matchmaking finds a match), you claim a pool server via the API. The claimed server becomes yours instantly — you receive its connection details in the response.
4

Pool replenishes automatically

After a server is claimed, PlayFlow launches a replacement to maintain your configured capacity. A reconciliation process runs approximately every 5 minutes to keep the pool at the target size.
Pool servers use the same infrastructure and runtime environment as on-demand servers. The only difference is that they are pre-launched and waiting, so there is no cold-start delay when you need one.

​
Configuring Your Pool

You can configure pool servers through the project dashboard or the API.

​
Dashboard Configuration

Navigate to your project’s Settings page in the PlayFlow dashboard. Under the pool configuration section, enable the pool and specify the number of servers to keep warm per region and compute size.

​
API Configuration

Use the project settings endpoint to configure your pool programmatically: 
curl -X POST https://app.playflowcloud.com/api/v3/projects/settings \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pool_config": {
      "enabled": true,
      "regions": {
        "us-east": {
          "small": 3,
          "medium": 2
        },
        "eu-west": {
          "small": 2
        }
      }
    }
  }'

​
Configuration Reference

The pool_config object has the following structure:
FieldTypeDescription
enabledbooleanWhether pool provisioning is active for this project.
regionsobjectA map of region IDs to compute size configurations.
regions.<region_id>objectA map of compute size names to the number of servers to keep warm.
Keep 3 small servers warm in US East:
{
  "pool_config": {
    "enabled": true,
    "regions": {
      "us-east": {
        "small": 3
      }
    }
  }
}

​
Claiming a Pool Server

When your game needs a server, start one as you normally would via POST /api/v3/servers/start. If a matching pool server is available in the requested region and compute size, PlayFlow assigns it instantly rather than launching a new machine. 
curl -X POST https://app.playflowcloud.com/api/v3/servers/start \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "build_id": "BUILD_ID",
    "region": "us-east",
    "compute_size": "small"
  }'
When a pool server is claimed:
  • The pool_claimed_at timestamp is set on the server record
  • The server appears in your server list with is_pool_server: true
  • You receive the server’s connection details (IP, ports) immediately in the response
If no pool server is available in the requested region and size, PlayFlow falls back to launching a new server on demand. Your game logic does not need to handle this distinction — the API response format is the same either way.

​
Identifying Pool Servers

Pool servers are visible in the server list alongside on-demand servers. You can identify them by the is_pool_server field: 
curl https://app.playflowcloud.com/api/v3/servers \
  -H "api-key: YOUR_API_KEY"
In the response, pool servers include:
FieldDescription
is_pool_servertrue for servers provisioned by the pool system.
pool_claimed_atTimestamp when the server was claimed. null if the server is still idle and unclaimed.

​
Billing

Pool servers use a split billing model that reduces costs while servers are idle.
Pool servers are billed from the moment they are provisioned, not from when they are claimed. Make sure you configure only as many pool servers as you need to avoid unnecessary costs.
StateRateDescription
Unclaimed (idle)30% discountPool servers waiting to be claimed are billed at 70% of the standard rate.
Claimed (active)Standard rateOnce claimed, servers switch to the normal per-second billing rate for their compute size.
If a server is claimed partway through a billing window, the pool discount applies to the time before the claim and the standard rate applies after. See Pricing & Instance Types for the standard rates by compute size.

​
Limits

Pool server limits are enforced per project. If you attempt to configure more servers than the maximum, the API returns an error.
  • Maximum 10 servers per region per compute size in the pool configuration
  • Pool reconciliation runs automatically approximately every 5 minutes to provision or remove servers to match the target count
  • Pool servers follow the same plan limits as on-demand servers (Free plan: max 1 active server; Pro plan: unlimited servers)

​
When to Use Pool Servers

  • Competitive matchmaking where sub-second server availability is critical
  • High-traffic games with frequent match starts and predictable demand
  • Tournament or event systems where matches need to start immediately
  • Games with short session times where launch latency is a significant fraction of playtime

​
Next Steps

Server Regions

Choose regions for your pool based on where your players are located.

Pricing & Instance Types

Review compute sizes and pricing to plan your pool configuration.