ExamplesSandboxes
macOS Sandboxes
Run macOS VMs — cloud or local via Lume, with managed or registry images
macOS sandboxes are always VMs — either on Cua Cloud or locally via Lume (Apple Virtualization framework). Cloud macOS works on any host OS — no Mac required.
Supported versions: "26" / "tahoe" (default), "15" / "sequoia"
Cloud macOS VM
Requires
CUA_API_KEY. Works on any host OS — Linux, Windows, or macOS.# source: examples/sandboxes/test_macos_cloud_vm.py
import asyncio
from cua import Image, Sandbox
async def main():
async with Sandbox.ephemeral(
Image.macos("26"),
name="example-macos-cloud-vm",
) as sb:
result = await sb.shell.run("sw_vers")
print(result.stdout.strip())
screenshot = await sb.screenshot()
with open("screenshot.png", "wb") as f:
f.write(screenshot)
asyncio.run(main())Local macOS VM
Requires macOS host with Lume installed. No API key needed.
# source: examples/sandboxes/test_macos_local_vm.py
import asyncio
from cua import Image, Sandbox
async def main():
async with Sandbox.ephemeral(
Image.macos("26"),
local=True,
name="example-macos-local-vm",
) as sb:
result = await sb.shell.run("sw_vers")
print(result.stdout.strip())
screenshot = await sb.screenshot()
with open("screenshot.png", "wb") as f:
f.write(screenshot)
asyncio.run(main())Local macOS VM from OCI Registry
Pull a macOS image directly from the ghcr.io/trycua registry. The SDK reads the OCI manifest to resolve the image kind and auto-selects Lume.
Requires macOS host with Lume installed.
# source: examples/sandboxes/test_macos_local_registry_vm.py
import asyncio
from cua import Image, Sandbox
async def main():
async with Sandbox.ephemeral(
Image.from_registry("ghcr.io/trycua/macos-tahoe-cua:latest"),
local=True,
name="example-macos-local-registry-vm",
) as sb:
result = await sb.shell.run("sw_vers")
print(result.stdout.strip())
screenshot = await sb.screenshot()
with open("screenshot.png", "wb") as f:
f.write(screenshot)
asyncio.run(main())Choosing a version
Image.macos() # macOS Tahoe (26) — latest, default
Image.macos("26") # macOS Tahoe
Image.macos("15") # macOS Sequoia
Image.macos("sequoia") # also SequoiaWas this page helpful?