> ## Documentation Index
> Fetch the complete documentation index at: https://modal-computer-use.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Keep warm desktop capacity

> Fill and claim a bounded pool of ready Modal desktop Sandboxes.

A warm pool reduces the wait for a ready desktop. It does not reduce warm action latency.

Function warm capacity and desktop warm capacity are separate. A warm Function reduces Function startup. A desktop pool reduces Sandbox startup.

<Warning>
  Warm capacity can incur charges while no task is running. Measure pool hit rate, cold fallback rate, remaining lifetime, and cost before you add capacity.
</Warning>

## Define a compatible pool

Use one stable pool name and one `ComputerConfig`:

```python theme={"system"}
import os

from modal_computer_use import (
    BrowserConfig,
    ComputerConfig,
    ComputerSandboxManager,
    ResourceConfig,
    RuntimeConfig,
    WarmPoolPolicy,
)

region = os.environ["MODAL_COMPUTER_USE_REGION"]

config = ComputerConfig(
    resources=ResourceConfig(profile="browser", cpu=4, memory_mib=8192),
    browser=BrowserConfig(kind="firefox", prewarm=True),
    runtime=RuntimeConfig(timeout_seconds=3600, modal_region=region),
)

policy = WarmPoolPolicy(
    pool_name="interactive-firefox",
    capacity=2,
    min_remaining_seconds=300,
)
```

Use a region selector from a current measurement. The pool checks configuration identity before it counts or claims a slot.

## Fill the pool

```python theme={"system"}
manager = ComputerSandboxManager()
fill = manager.fill_warm_pool(config=config, policy=policy)

print(
    {
        "configured_capacity": fill.configured_capacity,
        "existing_count": fill.existing_count,
        "created_count": fill.created_count,
    }
)
```

The manager counts a slot only after TCP readiness, daemon readiness, browser prewarm, and a decoded first frame.

Modal requires a Sandbox name to be unique within an App. The manager uses fixed named slots to coordinate concurrent fillers.

## Claim one desktop

```python theme={"system"}
claim = manager.claim_warm_pool(config=config, policy=policy)
try:
    computer = claim.computer
    computer.browser.open_url("https://example.com")
finally:
    claim.close()
```

A claim is one-shot. Close it after use. Do not place the Sandbox back in the pool.

The claim path rejects stale, incompatible, unready, finished, busy, and near-expiry candidates. An expected rejection can use the normal cold fallback.

Inspect `claim.metrics` for the pool result, claim time, complete request-to-first-frame time, remaining lifetime, and cost state.

## Reconcile capacity

Run `reconcile_warm_pool()` from your operator process. It removes invalid, incompatible, abandoned, and near-expiry reserved slots after live ownership checks.

Queue entries can outlive a terminated slot. Claim validation rejects stale entries.

Use the [warm-pool example](https://github.com/ashtonchew/modal-computer-use/blob/main/examples/04_warm_pool.py) when startup latency justifies reserved capacity. Filled slots can remain billable while idle. Each claim is one-shot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.