Configure a desktop

Set desktop, runtime, network, storage, browser, action, and budget policy.

Use ComputerConfig when the SDK creates a Modal Sandbox. Use daemon environment variables only when you launch the daemon directly.

All configuration models reject unknown fields. A misspelled field fails validation.

Build one configuration object

from modal_computer_use import (
    ActionConfig,
    BrowserConfig,
    BudgetConfig,
    ComputerConfig,
    DesktopConfig,
    NetworkConfig,
    ResourceConfig,
    RuntimeConfig,
)

config = ComputerConfig(
    desktop=DesktopConfig(resolution=(1280, 800)),
    runtime=RuntimeConfig(timeout_seconds=3600),
    resources=ResourceConfig(profile="browser", cpu=2, memory_mib=4096),
    network=NetworkConfig(outbound_domain_allowlist=["example.com"]),
    browser=BrowserConfig(kind="chromium", prewarm=True),
    actions=ActionConfig(max_batch_actions=25),
    budgets=BudgetConfig(max_actions=200, max_screenshots=100),
)

Choose each configuration family

Family	Controls
desktop	Resolution, DPI, color depth, and window manager.
runtime	Sandbox lifetime, idle timeout, readiness timeout, Modal environment, and requested region.
resources	Image profile, CPU, memory, and GPU request.
image	Inline or named image selection and revision.
network	Network blocking, allowlists, and daemon HTTP version.
storage	Artifact paths, recording paths, traces, and Volume-backed persistence.
browser	Browser kind, prewarm, profile, launch arguments, startup URL, and GPU mode.
actions	Batch limits, timeouts, rate limit, input backend, and subprocess backend.
budgets	Action, screenshot, artifact, recording, and daemon idle limits.

Use configuration model reference for every field and accepted value.

Set lifecycle bounds

runtime.timeout_seconds limits the total Sandbox lifetime. runtime.idle_timeout_seconds is a Modal idle policy.

budgets.max_idle_seconds is different. The daemon enforces it from budget-counted activity.

Warm-pool configurations cannot set runtime.idle_timeout_seconds. They also cannot set an explicit VNC password.

Set ingress and network policy

ComputerConfig.ingress defaults to attested-tunnel. Use connect when network.block_all=True.

network.block_all cannot be combined with a network allowlist. It also requires VNC to be off.

Pin runtime.modal_region only after you measure from the real caller. The requested region is part of the configuration hash.

Configure noVNC explicitly

Use one string value:

Value	Effect
"off"	Does not start VNC.
"view_only"	Lets an operator watch without sending input.
"control"	Lets an operator watch and send input.

config = ComputerConfig(expose_vnc="view_only")

Boolean expose_vnc=True is a compatibility input for "control". It is not view-only. Use the string value so the permission is clear.

Understand precedence

Values passed to ComputerConfig replace Pydantic defaults. The explicit expose_vnc= argument to create() replaces config.expose_vnc. The explicit image= argument replaces SDK image selection.

A directly launched daemon reads its process environment when settings are created. It does not read a daemon configuration file.

Treat tokens, passwords, startup URLs, daemon URLs, and noVNC URLs as sensitive.