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. Warm action latency uses a separate path, and the optimized-path contract leaves warm capacity off by default.

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

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.

Define a compatible pool

Use one stable pool name and one ComputerConfig:

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.

The CPU, memory, browser, and capacity values above are example application choices. Select and record values for your workload.

Fill the pool

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

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 when startup latency justifies reserved capacity. Filled slots can remain billable while idle. Each claim is one-shot.