macOS Sandboxes

macOS sandboxes are macOS virtual machines (VMs) on dedicated Apple silicon hardware. Each sandbox runs on a Mac Mini that your organization reserves. You can run commands in a macOS sandbox, connect with SSH, see and control its desktop, and keep disk between sessions.

A Mac is reserved for a 24-hour period. You choose the cores, memory and disk of each sandbox when you create it: one sandbox can use the whole Mac, or two sandboxes share it. macOS sandboxes run only on reservations. When your organization holds no reservation, Daytona can buy one for you when you create a sandbox.

Use cases

macOS sandboxes are used when the software, the build, or the task requires macOS or Apple tooling.

• Build and test Apple apps. An agent or a CI job builds and tests iOS and macOS apps with Xcode and the iPhone simulator on a clean Mac. The base image ships with Xcode, its iPhone simulator, Homebrew, and Python. The image runs macOS 26.6.2, and its Homebrew includes CocoaPods, fastlane, and Node.js 24.

• Computer-use agents on macOS. An agent operates macOS applications through screenshots and mouse and keyboard input. Computer use also reads the accessibility tree, acts on controls, and records the screen. The desktop is 1280 by 800, and your own VNC client can connect to it over a WebSocket.

• Long-lived build machines. A persistent sandbox keeps its disk across stop and start, so installed tools and build caches stay between sessions. To keep the disk after the reservation ends, take a filesystem snapshot. Automatic renewal stops when every sandbox on the Mac is stopped or paused, and the reservation then ends with its period.

• Remote access over SSH. A developer or a script connects to the Mac over SSH to run commands and inspect builds. The CLI opens the connection itself, and other SSH clients sign in with a short-lived sandbox token in the user name. The token is limited to one sandbox and to SSH, so no project API key goes into the SSH command.

• Fleets of Macs. One request reserves up to 100 Macs for parallel builds and tests. Each Mac is a separate reservation with its own ID, period, charge, and renewal. A minimum count accepts fewer Macs when not enough are available.

Requirements

Your organization must have macOS sandboxes turned on. Without it, reserving a Mac or creating a macOS sandbox fails with a feature error. Sign in to the dashboard at app.daytona.com ↗ and create a project API key. The examples read the key from an environment variable.

Endpoints

macOS sandboxes have their own API address. Send all macOS requests to the macOS API.

The SDKs and the CLI read the API address and your key from environment variables. Give the region of the Macs, listed in the table above, on each reservation and each macOS create.

export DAYTONA_API_KEY=dtn_...
export DAYTONA_API_URL=https://api.us-macos.daytona.com
export DAYTONA_REGION=macos-1    # the CLI's default region

Install

Pin these exact versions. Pre-release and latest installs pull other versions that do not have the macOS features.

pip install daytona==2.0.0a11

Connect

The SDK clients read your key and the macOS API address from the environment.

from daytona import Daytona

daytona = Daytona()  # reads DAYTONA_API_KEY and DAYTONA_API_URL
# AsyncDaytona has the same methods with await

Create a macOS sandbox

Create a macOS sandbox from a macOS image. Each sandbox runs on one of your Mac reservations. When your organization holds no reservation in the region and auto-reserve is on, which it is by default, the create buys one for you, so you do not need to reserve a Mac first. With auto-reserve off, reserve a Mac before you create a sandbox. The base image has macOS, Xcode and common build tools. The following table lists its contents.

You choose the size of each sandbox when you create it. Two sandboxes share one Mac when their sizes fit in the Mac together.

from daytona import Daytona

daytona = Daytona()
sandbox = daytona.v2.create_macos("base-macos", region="macos-1")

from daytona.v2 import MacosResources

r = daytona.v2.reservations.create(region="macos-1", model="m4pro-12c-24g",
                             idempotency_key="shared-mac-1")
a = daytona.v2.create_macos("base-macos", region="macos-1", reservation=r.id,
                             resources=MacosResources(cpu=4, memory=8, disk=100))
b = daytona.v2.create_macos("base-macos", region="macos-1", reservation=r.id,
                             resources=MacosResources(cpu=8, memory=16, disk=120))

from daytona.v2 import MacosResources

r = daytona.v2.reservations.create(region="macos-1", model="m4pro-12c-24g",
                             idempotency_key="ios-builder-mac-1")
sandbox = daytona.v2.create_macos(
    "base-macos",
    region="macos-1",
    reservation=r.id,
    resources=MacosResources(cpu=12, memory=24, disk=220),
    persistent=True,
    name="ios-builder",
    wait_seconds=120,
)
print(sandbox.id, sandbox.reservation_id, sandbox.cpu, sandbox.memory, sandbox.disk)

Sizes

A macOS sandbox takes its cores, memory and disk from the Mac of its reservation. The disk is the whole guest disk, macOS included. On the M4 Pro model, the sandboxes of one Mac share 12 cores, 24 GiB memory and 220 GiB disk. Up to two sandboxes run on one Mac at the same time, and their sizes must fit in the Mac together. For example, one sandbox of 12 cores, 24 GiB memory and 220 GiB disk uses the whole Mac, and a sandbox of 4 cores, 8 GiB and 100 GiB fits beside a sandbox of 8 cores, 16 GiB and 120 GiB. A Mac fixes the size when it accepts the sandbox, and the sandbox reports that size from then on.

Which reservation

A create places the sandbox on a reservation. The reservation option decides which one, and whether the create buys a new one.

The create can wait for room on a reservation. Two options set how long: in seconds in the SDKs, and as a Go duration in the CLI. If the time runs out, a reservation that the create bought stays bought.

Get a sandbox

Get a macOS sandbox by its ID, or list the sandboxes in the macOS region.

sandbox = daytona.v2.get("SANDBOX_ID")

Mac reservations

A reservation gives your organization one dedicated Mac for a 24-hour period. Nobody else uses that Mac while you hold it. You pay for each period when it starts. The first period starts when a Mac accepts the reservation, not when you send the request, and time spent waiting for a Mac is not charged.

You cannot end a reservation early. It ends at the end of its period unless it renews. macOS sandboxes run only on your reservations: a create picks a reservation with room left, or you name one. Up to two sandboxes run on the Mac at the same time, and you choose the size of each sandbox when you create it.

Models and prices

The production Macs are Apple M4 Pro, 12 cores, 24 GB memory. Always give this model when you reserve. Its model ID is in the table below. The price of one reservation of this model is $2.5032 per Mac-hour, $60.08 per 24-hour period.

The sizes of the sandboxes on one Mac must fit in its cores, memory and sandbox disk together. See sizes.

Read the current price and the number of available Macs from the Mac catalog. An available Mac is one that nobody has reserved. The number is a guide only: another purchase can reserve an available Mac before yours.

catalog = daytona.v2.mac_models.catalog(region="macos-1")
for region in catalog.regions:
    for entry in region.models:
        price = entry.price
        print(
            entry.model.id,
            "available:", entry.available,
            "per period: $%.2f" % (price.period_cents / 100) if price else "no price",
        )

# Model specs only; the catalog adds prices and available Macs per region
for model in daytona.v2.mac_models.list():
    print(model.id, model.cores, model.memory_mib, model.max_sandboxes)

Reserve a Mac

Reserve one Mac of a model in a region. Each purchase has an idempotency key. If you retry with the same key, you get the same reservation and you do not pay again. If you do not give a key, the SDK and the CLI make a new key for each call, so a retry buys a second Mac. Give your own key when your code can retry.

reservation = daytona.v2.reservations.create(
    region="macos-1",
    model="m4pro-12c-24g",
    idempotency_key="build-mac-2026-10-24",
)
print(reservation.id, reservation.status)

Reserve many Macs

Reserve 1 to 100 Macs of one model in one request. Each Mac is a separate reservation with its own ID, period, charge and renewal.

By default, the request is all or nothing: if fewer Macs are available than you ask for, it reserves none and fails because no Mac is available. Set a minimum count to accept fewer: the request then reserves as many as are available, if that is at least the minimum.

batch = daytona.v2.reservations.create_bulk(
    region="macos-1",
    model="m4pro-12c-24g",
    count=20,
    min_count=10,
    idempotency_key="ci-fleet-2026-10-24",
)
print(f"reserved {batch.reserved} of {batch.requested} Macs")
ids = [r.id for r in batch.reservations]

List reservations

List the reservations of your organization, one page at a time. The list returns the open reservations and the reservations that ended in the last 30 days.

cursor = None
while True:
    page = daytona.v2.reservations.list(limit=100, cursor=cursor)
    for r in page.items:
        print(r.id, r.status, r.model, r.period_end, r.auto_renew)
    cursor = page.next_cursor  # None on the last page
    if cursor is None:
        break

Iterate over all reservations

Iterate over every reservation of your organization without handling page cursors. The iterator fetches the next page when the current one is exhausted and stops when the server returns no cursor.

for r in daytona.v2.reservations.iter():
    print(r.id, r.status, r.model, r.period_end, r.auto_renew)

Get a reservation

Get one reservation of your organization by its ID. The response has the same fields as an item of the list, including its current status and the end of its period.

r = daytona.v2.reservations.get("RESERVATION_ID")
print(r.id, r.status, r.period_end, r.auto_renew)

Renew a reservation

Renew a reservation to pay for the next 24-hour period on the same Mac. You keep the Mac, its sandboxes and their disks. Use a new key for each period you want to buy, and the same key when you retry.

daytona.v2.reservations.renew(reservation.id, idempotency_key=f"renew-{reservation.id}-2")

Automatic renewal

When automatic renewal is on, we renew the reservation in the last hour of its period, but only while a sandbox on that Mac is active (being created, starting or running). If all its sandboxes are stopped or paused, or it has none, the reservation does not renew and ends at the end of its period. If a renewal fails, the reservation records the reason and ends at the end of its period.

Turn automatic renewal on or off for one reservation.

daytona.v2.reservations.update(reservation.id, auto_renew=False)

Auto-reserve

Auto-reserve buys a Mac for you when you create a macOS sandbox and your organization holds no live reservation in the region. It buys the cheapest model that fits the sandbox, with automatic renewal on. If you want to control every purchase, turn auto-reserve off and reserve Macs yourself.

• It is on by default. It holds at most 2 reservations at a time. Above that, a create fails because the auto-reserve limit is reached.
• It does not buy a Mac when you have a reservation that is only full: no free slot, or too little disk left.
• An organization admin can turn it off, or change the limit, in the dashboard: Settings, Auto-reserve Macs, or through the macOS settings.

macOS settings

The macOS settings control auto-reserve for macOS sandboxes. With auto-reserve on, a macOS create in a region where the organization holds no live Mac reservation buys a 24-hour reservation that renews while a sandbox runs on it. Auto-reserve is on by default, and the organization caps how many auto-reserved reservations it holds at once.

Get the settings

Get the organization's macOS settings.

curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/macos-settings' \
  --header 'Authorization: Bearer YOUR_OIDC_TOKEN'

{
  "macos_auto_reserve": true,
  "macos_auto_reserve_max_reservations": 2,
  "macos_auto_reserve_disabled_at": null,
  "macos_auto_reserve_disabled_by": null
}

Set the settings

Turn auto-reserve on or off, or change the cap on auto-reserved reservations. Fields left out of the request keep their stored values.

curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/macos-settings' \
  --request PATCH \
  --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "macos_auto_reserve": true, "macos_auto_reserve_max_reservations": 4 }'

When a reservation ends

A reservation ends at the end of its period when it does not renew. There is no grace period, and we do not send a notice. Watch the end of the period, the automatic renewal setting and any renewal error on your reservations, or renew by hand.

At the end, in this order:

1. The reservation enters the ending status. You cannot start, resume or create sandboxes on it.
2. Persistent sandboxes are shut down (paused ones are resumed first, then shut down). Each one that ran is exported as an image: an image without a name that records the sandbox's ID.
3. Sandboxes that are not persistent are deleted. Their data is lost.
4. When every export is saved or has failed, the Mac is erased: the sandbox disks, the console logs, the macOS user and its files. A failed export holds the erase for up to 24 hours. The disk of that sandbox is lost.
5. The Mac is checked and goes back to the pool for the next customer.
6. The reservation enters the released status. Every sandbox on it is deleted.

What you keep

Continue after the end

Find the exported image, then create a sandbox from it on a reservation. You can also give the image a name to keep it. The new sandbox needs a reservation with room for the disk: an existing one, a new one you buy, or one that auto-reserve buys. It gets a new machine identity.

exports = daytona.v2.images.list(anonymous=True, sandbox_id="OLD_SANDBOX_ID")
image = exports.items[0]
daytona.v2.images.promote(image.id, "ios-builder-day-2")   # optional: keep it
sandbox = daytona.v2.create_macos(image.id, region="macos-1", persistent=True, wait_seconds=120)

Filesystem snapshot

A filesystem snapshot saves the disk of a stopped persistent macOS sandbox as an image. You can create new sandboxes from it on any Mac of the region. Snapshots save the disk only, not the memory.

A new sandbox from an image gets a new machine identity. Apps that are bound to one machine (for example an iCloud sign-in or some licences) need you to sign in again.

sandbox.stop()
image = sandbox.capture_image(name="ios-builder-ready")
image = daytona.v2.images.get(image.id, wait="ready", timeout=3600)
print(image.id, image.status)

copy = daytona.v2.create_macos("ios-builder-ready", region="macos-1", persistent=True)

Filesystem persistence

A persistent macOS sandbox keeps its disk on its Mac across stop and start for as long as the reservation lives. To keep the disk after the reservation, make a filesystem snapshot, or let the end of the reservation save it (see when a reservation ends).

Lifecycle

Every macOS sandbox moves through a lifecycle. Stop, start, pause and resume need a persistent sandbox. A sandbox that is not persistent can only run or be deleted.

If a Mac restarts, a running persistent sandbox comes back stopped with its disk. A running sandbox that is not persistent is lost.

Stop / start

Stop a persistent macOS sandbox to shut down macOS and keep its disk on the same Mac. Start boots macOS from the same disk on the same Mac.

sandbox.stop()
sandbox.wait(until="stopped")
sandbox.start(timeout=120)

# Stop a sandbox by ID, without fetching it first
daytona.v2.stop("SANDBOX_ID")

# Start a stopped sandbox by ID
daytona.v2.start("SANDBOX_ID", timeout=120)

Pause / resume

Pause a persistent macOS sandbox to save its memory on the Mac. Resume continues the sandbox from the saved memory.

sandbox.pause()
sandbox.resume()

# Pause a sandbox by ID, without fetching it first
daytona.v2.pause("SANDBOX_ID")

# Resume a paused sandbox by ID
daytona.v2.resume("SANDBOX_ID")

Fork

Fork a persistent macOS sandbox to copy its disk into a new sandbox. A fork does not copy memory, and a fork that asks for memory fails.

twin = sandbox.fork(name="ios-builder-2")

Delete

Delete a macOS sandbox to erase the sandbox and its disk. You cannot undo this.

sandbox.delete()

Run commands

Run commands in a macOS sandbox, in the foreground or in the background. Files, git and PTYs work as on Linux sandboxes.

result = sandbox.exec("sw_vers -productVersion && xcodebuild -version")
print(result.exit_code, result.output)

handle = sandbox.process.start("xcodebuild -scheme App build")  # runs in the background
print(handle.wait().exit_code)

SSH

Connect to a macOS sandbox over SSH. The CLI opens SSH for you. With your own SSH client, make a short-lived sandbox token that allows SSH, and put the sandbox ID and the token in the user name, joined by a hash sign (#).

The gateway checks the token, not a password or an SSH key. A token works until it expires. Make a new one when you need it.

token = sandbox.create_access_token(operations=["ssh"], ttl_seconds=3600)
print(f'ssh -p 2222 "{sandbox.id}#{token.access_token}@ssh.us-macos.daytona.com"')

Desktop

macOS sandboxes have a desktop of 1280 × 800. Open the sandbox in the dashboard and choose the desktop view. The desktop takes mouse and keyboard input as soon as it connects.

User and password

A macOS sandbox signs in to its macOS user when it starts, so the desktop opens without a login screen. macOS asks for the password of this user when you change a protected setting, for example when you allow an app under Privacy & Security, and when you unlock the screen. SSH and the desktop view do not use this password. Daytona checks your sandbox token instead.

The following table lists the user settings of the base image. A sandbox from a filesystem snapshot keeps the user settings of the sandbox that the snapshot was taken from, including a changed password.

Computer use

Take screenshots and send mouse and keyboard input inside the sandbox. Computer use can also read the accessibility tree, act on controls, and record the screen.

import base64

cu = sandbox.computer_use
cu.start()
print(cu.status())

shot = cu.screen.screenshot()
with open("screen.png", "wb") as f:
    f.write(base64.b64decode(shot.screenshot))

cu.mouse.click(x=640, y=400)
cu.keyboard.type(text="hello from Daytona")
cu.keyboard.hotkey(keys="cmd+space")       # modifiers: cmd, ctrl, alt (option), shift
print(cu.display.windows())

VNC client

Connect your own VNC client to the desktop. The desktop is also a VNC connection over a WebSocket. Make a token with the desktop operation and connect a noVNC client to the address below. The proxy does the VNC password step for you. Your client must support the DesktopSize encoding (noVNC does).

wss://proxy.us-macos.daytona.app/vnc/SANDBOX_ID?daytona_token=TOKEN

token = sandbox.create_access_token(operations=["desktop"], ttl_seconds=3600)

Logs

A macOS sandbox has a console log, and your own processes can keep their own logs. The console log is erased with the Mac when the reservation ends. Copy what you need before then.

daytona sandbox logs SANDBOX_ID
daytona sandbox logs SANDBOX_ID --follow

Errors

The SDKs raise these errors with the codes in the following table. If something does not work as this page says, send us the sandbox ID or the reservation ID and the time. We read the server logs from those.

Permissions

macOS sandboxes and Mac reservations use the sandbox permissions of their project, which you can grant to an organization role or an API key. The macOS settings of the organization use organization permissions.

The audit logs record sandbox creates and deletes, and Mac reservations and renewals.