> ## 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. # Pool Servers > Pre-warmed game servers to reduce launch latency (upcoming feature). # 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](/fundamentals/api) 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. 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 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. 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. 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: ```bash theme={null} 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.` | object | A map of compute size names to the number of servers to keep warm. | Keep 3 small servers warm in US East: ```json theme={null} { "pool_config": { "enabled": true, "regions": { "us-east": { "small": 3 } } } } ``` Spread warm servers across multiple regions for global coverage: ```json theme={null} { "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: ```json theme={null} { "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. ```bash theme={null} 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: ```bash theme={null} 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](/fundamentals/plan-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 * **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 * **Low-traffic games** where the on-demand launch wait is acceptable * **Development and testing** where launch speed is not a priority * **Long-session games** (e.g., survival or sandbox) where the initial startup time is negligible relative to session length *** ## Next Steps Choose regions for your pool based on where your players are located. Review compute sizes and pricing to plan your pool configuration.