Pool Servers

Pool servers are not currently available. This feature is in active development. Today, every server cold-starts on demand — there are no pre-warmed standby servers, no instant claim, and no idle billing discount, regardless of any pool_config you set. This page describes how pool servers are intended to work once the feature ships. Nothing on this page functions at runtime yet.

Pool servers are a planned feature: pre-provisioned game servers that sit warm and ready to be claimed, so you can skip the on-demand launch wait when a match is found. This is intended for competitive matchmaking and any game where launch latency matters. Until pool servers ship, use the standard on-demand server start flow — every server is created fresh on each start.

How Pool Servers Will Work

The flow below describes the intended design. None of these steps run today — the pool system is disabled, so configuration is stored but no standby servers are provisioned or claimed.

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.

PlayFlow provisions servers

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

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 and you receive its connection details in the response, skipping the on-demand launch wait.

Pool replenishes automatically

After a server is claimed, PlayFlow launches a replacement to maintain your configured capacity. A reconciliation process keeps the pool at the target size.

Pool servers are designed to use the same infrastructure and runtime environment as on-demand servers. The only difference is that they are pre-launched and waiting.

Configuring Your Pool

Pool configuration is stored via the project settings endpoint. (Storing it has no runtime effect today — no standby servers are provisioned until the feature ships.)

Updating project settings requires a server key (pf_...). Client keys (pfclient_...) receive a 403. Keep server keys server-side and never ship them in a game build.

Use the project settings endpoint to configure your pool programmatically:

curl -X POST https://api.computeflow.cloud/api/v3/projects/settings \
  -H "api-key: pf_YOUR_SERVER_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:

Field	Type	Description
`enabled`	boolean	Whether pool provisioning is active for this project.
`regions`	object	A map of region IDs to compute size configurations.
`regions.<region_id>`	object	A map of compute size names to the number of servers to keep warm.

Single Region
Multi-Region
Disable Pool

Keep 3 small servers warm in US East:

{
  "pool_config": {
    "enabled": true,
    "regions": {
      "us-east": {
        "small": 3
      }
    }
  }
}

Spread warm servers across multiple regions for global coverage:

{
  "pool_config": {
    "enabled": true,
    "regions": {
      "us-east": {
        "small": 3,
        "medium": 2
      },
      "eu-west": {
        "small": 2
      },
      "ap-north": {
        "small": 1
      }
    }
  }
}

To disable the pool and stop provisioning idle servers:

{
  "pool_config": {
    "enabled": false,
    "regions": {}
  }
}

Claiming a Pool Server

Once pool servers ship, you will start a server exactly as you do today via POST /api/v3/servers/start. If a matching pool server is available in the requested region and compute size, PlayFlow will assign it rather than launching a new machine. Today this always launches a fresh on-demand server — the request below is the standard start call and works now; the pool fast-path is what will change once the feature is enabled. name and region are required. Select a build with version_tag (the build name) and optional version. There is no build_id field on server start.

curl -X POST https://api.computeflow.cloud/api/v3/servers/start \
  -H "api-key: pf_YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ranked-1",
    "region": "us-east",
    "version_tag": "default",
    "compute_size": "small"
  }'

Read the connection details from the response: use the host and external_port of each entry in network_ports[] rather than hardcoding a host or port. The proxy-allocated external_port differs from your internal port — never assume 7777 or any fixed value. When pool servers are eventually claimed, the response will additionally set pool_claimed_at and is_pool_server: true on the server record.

When pool servers are available and none matches the requested region and size, PlayFlow will fall 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

Once the feature ships, pool servers will be visible in the server list alongside on-demand servers, identifiable by the is_pool_server field:

curl https://api.computeflow.cloud/api/v3/servers \
  -H "api-key: pf_YOUR_SERVER_KEY"

While pooling is disabled, these fields stay dormant: every server is a cold-create, so is_pool_server is always false and pool_claimed_at is always null.

In the response, pool servers will include:

Field	Description
`is_pool_server`	`true` for servers provisioned by the pool system.
`pool_claimed_at`	Timestamp when the server was claimed. `null` if the server is still idle and unclaimed.

Billing

Because pool servers do not run today, there is no separate pool billing. Every server you launch is an on-demand server billed at the standard rate for its compute size. The billing model for pooled standby servers has not been finalized and will be documented here when the feature ships. See Pricing & Instance Types for the standard rates by compute size.

Limits

Maximum 10 servers per region per compute size in the pool configuration
Pool reconciliation will run automatically to provision or remove servers to match the target count (not active while the feature is disabled)
Pool servers will follow the same plan limits as on-demand servers (Free plan: max 1 active server; Pro plan: unlimited servers)

When Pool Servers Will Help

Good Fit
May Not Need

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

Pool Servers

Pool Servers

How Pool Servers Will Work

Configuring Your Pool

Configuration Reference

Claiming a Pool Server

Identifying Pool Servers

Billing

Limits

When Pool Servers Will Help

Next Steps

Server Regions

Pricing & Instance Types

​Pool Servers

​How Pool Servers Will Work

​Configuring Your Pool

​Configuration Reference

​Claiming a Pool Server

​Identifying Pool Servers

​Billing

​Limits

​When Pool Servers Will Help

​Next Steps

Server Regions

Pricing & Instance Types

Pool Servers

How Pool Servers Will Work

Configuring Your Pool

Configuration Reference

Claiming a Pool Server

Identifying Pool Servers

Billing

Limits

When Pool Servers Will Help

Next Steps