Capture screenshots and recordings

Capture semantic screenshots, choose a source, and record the desktop.

Capture the initial frame

screenshot = await computer.screenshots.full(
    format="png",
    show_cursor=False,
)

data = screenshot.as_bytes()
print(screenshot.width, screenshot.height, screenshot.sha256)

Inline screenshots.full() uses the raw binary HTTP route through the borrowed pooled client. It still returns a semantic Screenshot. The SDK validates the body, format, dimensions, size, digest, timestamp, coordinate space, cursor state, timing, and capture backend.

Use full_bytes() when a low-level caller only needs encoded bytes. JSON and base64 routes remain available for REST and compatibility clients.

Choose screenshot storage

Set storage when you call screenshots.full().

Storage	Result
inline	Returns the image bytes in the Screenshot. This is the default.
artifact	Saves the encoded image and returns its artifact_uri with screenshot metadata.
auto	Uses an artifact above 1,000,000 encoded image bytes. At or below 1,000,000 bytes, the image stays inline.

Artifact and automatic storage use the structured JSON response. Read saved images through the artifact namespace.

Use the step frame after actions

step = await computer.step(actions)
screenshot = step.screenshot

The frame follows native input synchronization. Your application owns readiness. The experimental first-visual-change interface has a separate polling and XDamage contract.

Select a screenshot source

MSS is the production default.

from modal_computer_use import ComputerConfig

config = ComputerConfig(actions={"screenshot_capture_source": "x11-shm"})

Source	Behavior
mss	Uses the persistent MSS session. This is the default.
auto	Probes X11-SHM after readiness and may use MSS after an ordinary native failure.
x11-shm	Requires X11-SHM readiness and fails closed when the source is unavailable.

X11-SHM requires a managed Image containing the native extension and worker. It applies to eligible cursor-hidden, full-resolution PNG requests at scale 1. Other formats and cursor-visible requests use the compatibility path.

An X-server reply timeout fails closed. Every screenshot source depends on that display, so a fallback cannot prove safe capture while the display is unresponsive. A display restart clears generation-bound clients before the daemon proves readiness again.

The fixed promotion campaign rejected X11-SHM as the default. Keep it as an explicit opt-in until a new campaign passes every latency and reliability gate.

Record the desktop

recording = await computer.recordings.start(name="demo", fps=12)
try:
    await computer.actions.run([{"type": "move", "x": 50, "y": 50}])
finally:
    stopped = await computer.recordings.stop(recording.id)

Stop a recording before the owner terminates the Sandbox. Keep screenshot bytes, recordings, and artifact references out of logs.