Configuration reference

Configure Modal orchestration with ComputerConfig and a direct daemon with environment variables.

The package has two configuration surfaces:

• ComputerConfig configures SDK-created Modal Sandboxes.
• Environment variables configure a directly launched daemon.

ComputerConfig rejects unknown keys. It uses Pydantic defaults unless you provide a value.

Configure the placed path

from modal_computer_use import (
    ActionConfig,
    BrowserConfig,
    ComputerConfig,
    ResourceConfig,
    RuntimeConfig,
)

config = ComputerConfig(
    runtime=RuntimeConfig(
        modal_environment="main",
        modal_region="us-west",
    ),
    resources=ResourceConfig(
        profile="browser",
        cpu=1,
        memory_mib=2048,
    ),
    browser=BrowserConfig(kind="chromium", prewarm=True),
    actions=ActionConfig(
        screenshot_capture_source="mss",
        input_backend="auto",
        subprocess_backend="isolated-asyncio",
    ),
)

Replace the environment, supported region selector, CPU, memory, browser, and timeouts with values measured for your workload. Use a public narrow selector such as us-west or a Workspace-granted granular selector such as us-west-2. Broad selectors such as us and eu cannot prove the placed handoff. Warm capacity stays off until you enable it in Modal.

Public models

Model	Owns
DesktopConfig	Resolution, DPI, window manager, and display depth
RuntimeConfig	Timeouts, Modal environment, and verifiable region selector
ResourceConfig	Resource profile, CPU, memory, and GPU requests
ImageConfig	Inline or named image selection and revision
NetworkConfig	Network policy and daemon HTTP version
StorageConfig	Artifact, recording, trace, and persistence paths
BrowserConfig	Browser kind, prewarm, profile, startup URL, arguments, and GPU mode
ActionConfig	Batches, timeouts, capture, input, subprocesses, and input-work limits
BudgetConfig	Trajectory action, screenshot, artifact, recording, and idle budgets

See the 2.0 configuration source for every field and bound.

Important defaults

Setting	Default
Resolution	1024 x 768
Runtime timeout	3600 seconds
Readiness timeout	120 seconds
Resource profile	standard
Image source	inline
Ingress	attested-tunnel
Daemon HTTP version	1.1
Maximum batch actions	50
Default action timeout	5000 ms
Input-work refill	100 weighted tokens per second
Input-work burst	400 weighted tokens
Screenshot source	mss
Input backend	auto
Subprocess backend	isolated-asyncio
VNC mode	off

CPU and memory values are requests. Modal billing can use the requested amount when it exceeds actual use.

Select a screenshot source

Value	Behavior
mss	Production default with persistent MSS and XShm capture when available
auto	Evaluates the optional native X11 shared-memory extension, then uses the bounded MSS policy
x11-shm	Requires the native extension and fails readiness when it cannot provide the source

The X11 shared-memory source is an explicit option. MSS remains the production default because the X11 shared-memory campaign failed required promotion gates.

Configure a direct daemon

A directly launched daemon reads COMPUTER_USE_* variables when it starts. Common groups include:

Group	Examples
Display and backends	DISPLAY, COMPUTER_USE_BACKEND, COMPUTER_USE_INPUT_BACKEND
Capture	COMPUTER_USE_SCREENSHOT_CAPTURE_SOURCE
Input-work policy	COMPUTER_USE_INPUT_RATE_LIMIT_PER_SEC, COMPUTER_USE_INPUT_RATE_LIMIT_BURST
Actions	COMPUTER_USE_MAX_BATCH_ACTIONS, COMPUTER_USE_MAX_BATCH_DURATION_MS
Authentication	COMPUTER_USE_LOCAL_TOKEN, COMPUTER_USE_TUNNEL_TOKEN
Storage	COMPUTER_USE_ARTIFACTS_DIR, COMPUTER_USE_RECORDINGS_DIR, COMPUTER_USE_TRACE_DIR
Budgets	COMPUTER_USE_MAX_ACTIONS, COMPUTER_USE_MAX_SCREENSHOTS, COMPUTER_USE_MAX_IDLE_SECONDS

The application configuration guide lists every environment variable and bound.

Protect secrets

Treat tokens, VNC passwords, daemon URLs, browser startup URLs, typed text, clipboard text, screenshots, and artifact bytes as secrets. Keep them out of configuration output and logs.