SDK & API

SDKs (Python · TypeScript)

Both SDKs (Python on PyPI, TypeScript on npm) expose the same macOS sandbox surface — create() for macOS sandboxes, plus mouse, keyboard, screenshot, exec, files, recording, and the UI tree. Pick your language:

A Go SDK is not available yet.

These packages replace the old use-computer (PyPI) and use-computer-sdk (npm) packages, which get no new releases. Uninstall the old package first (pip uninstall use-computer or npm uninstall use-computer-sdk): the Python packages install the same use_computer module, so the import stays from use_computer import Computer. In TypeScript, change the import to @daytona/use-computer.

// TypeScript — async-native
import { Computer } from "@daytona/use-computer";
const mac = await new Computer().create();
console.log((await mac.exec("sw_vers")).stdout);
await mac.close();

The rest of this page covers the Python SDK in depth. The TypeScript SDK mirrors the sandbox surface; Python additionally ships optional computer-use agents behind extras.

Idempotency-Key

The customer API accepts Idempotency-Key on POST /v1/sandboxes and POST /v1/sandboxes/{id}/snapshots. Creating a sandbox with a snapshot field restores that snapshot and uses the same protection.

Use a unique key (up to 255 bytes) for each operation and reuse it when retrying with the same path and exact request body. Keys are scoped to your user and gateway environment across these endpoints. Completed 2xx and 4xx responses replay their original HTTP status and body for 24 hours after the first request. A 5xx response replays only until the attempt's 10-minute create or 25-minute snapshot capture/restore deadline; retrying after that deadline starts a fresh attempt. A concurrent retry returns 409 {"error":"idempotency_in_flight"}; retry with the same key after the first request finishes. An unfinished request can be retried after 10 minutes for ordinary creates or 25 minutes for snapshot capture/restore. A gateway restart also releases unfinished requests in that gateway environment. These retries may repeat work that completed remotely before the gateway could record its response.

Reusing a key with a different path, body, or reservation-key reservation returns 422 {"error":"idempotency_key_reused"}. Without the header, every request starts a new operation. After 24 hours, the same key starts a new operation too.

Snapshots

macOS sandboxes can be snapshotted after you seed them, usually by opening the live screen over VNC and setting it up by hand. macOS snapshots preserve disk state.

macOS snapshots are portable disk deltas. When you create one, the gateway pulls the snapshot artifact from the source Mac Mini; when you launch from it, the gateway pushes that artifact to whichever reserved Mini claims the new VM.

Restores use the base image recorded in the snapshot, not the Mac's current warm-pool image. An older snapshot can therefore restore after a pool upgrade while its original base remains available. Snapshots taken from that restored sandbox keep the same base dependency, including across gateway restarts.

If the reservation's Macs lack the required base or have a different base disk size, create returns 409 with error: "snapshot_base_unavailable" before claiming a VM. Contact support to recover the base, or create a new snapshot from a fresh sandbox. Transfer, apply, and startup failures return 502 with a JSON error; these are different from a missing reservation.

from use_computer import Computer

client = Computer(api_key="uc_live_...")

# Boot a sandbox and configure it by hand over VNC, then snapshot it.
with client.create() as mac:
    print("Set up the screen here:", mac.vnc_url)
    # In the VNC session, bake whatever you want into the image:
    #   - install the apps and tools your agent needs
    #   - sign into accounts (email, GitHub, a web app)
    #   - pre-open the tabs, apps, or files it should start from
    input("Press Enter once the screen is ready to snapshot...")

    # Save the configured state as a reusable snapshot version.
    snapshot = mac.snapshot("chrome-seeded-macos")

# Every future sandbox boots from that saved state, no setup needed.
with client.create(snapshot=snapshot.version) as seeded:
    print(seeded.vnc_url)  # installed apps, files, and logins restored

Use client.snapshots() to list saved snapshot versions.

Python SDK

The Python SDK is published on PyPI.

pip install daytona-use-computer

Base installs only the SDK client and httpx. Computer-use agent integrations are opt-in:

pip install "daytona-use-computer[agents]"        # computer-use agents and provider SDKs

from use_computer import Computer
client = Computer(api_key="uc_live_...")

Creating a sandbox

mac = client.create()

If one account key has more than one active Mac reservation, pass reservation_id="..." when creating macOS sandboxes.

Reserve with client.reserve(hours=24, mac_model="m5-pro") for an Apple M5 Pro Mac (15 cores, 24 GiB). M4 remains the default; M4 Pro is m4-pro. Check the live dashboard for each model's configured hourly price and availability. Reservations retain their purchased rate.

M5 Pro split defaults are 8 + 7 cores · 12 GiB each. create() and create(snapshot=...) use the available slot and return its actual cpu and memory_gib; a restore is not pinned to the source sandbox's CPU count. vm_layout="whole" at reservation time provides one 15 vCPU / 24 GiB VM. For explicit sizes, create(cpu=7, memory_gib=12) and create(cpu=8, memory_gib=12) can coexist on a split M5 Pro Mac. Use the reservation-scoped platform catalog for guest base availability.

DSL

MacOSSandbox provides complete control over the macOS VM (screenshot, display, recording, file transfer, mouse, keyboard, and shell).

Lifetime and cleanup

The server defaults new sandboxes on a reserved Mac to the reservation lifetime when the create request omits ephemeral: they live until you delete them or the reservation reaches end_at. Set ephemeral: true to opt into the two-minute idle timeout.

The shipped Python and TypeScript SDK versions still send ephemeral: true by default. With these versions, explicitly disable ephemeral mode before removing your keep-alive thread. In Python:

with client.create(ephemeral=False) as mac:  # automatically delete on exit
    ...                       # long-running agent work

If you keep the SDK's ephemeral default, keep calling mac.start_keepalive() for long-running work. The server's reservation-lifetime default takes effect only once the SDK omits the field (or you explicitly send false).

Without a context manager, call mac.delete() when finished. At reservation expiry, GET /v1/sandboxes/{id} reports state: "completing" while cleanup is in progress; you can still delete the sandbox. Once cleanup completes, it returns 404.

vnc_url from create or snapshot restore contains a sandbox-scoped viewer token, not your account key. The link expires within one hour, or earlier at the reservation's end_at (pool sandbox lifetime: 24 hours after creation). Each viewer request checks that the sandbox still exists and its reservation is active, including after reservation edits. The owner can request a fresh link with POST /v1/sandboxes/{id}/viewer-token; the response includes vnc_url, token, and expires_at. Anyone holding the link can view and control that sandbox until it expires.

HTTP API

Not on Python? Every SDK method is a thin wrapper over https://api.use.computer/v1/... — auth is Authorization: Bearer uc_live_.... The full surface is documented as an interactive Swagger viewer at api.use.computer/docs, with the raw spec at api.use.computer/openapi.yaml for Postman / Insomnia.