macOS Sandboxes

Daytona v2

Documentation for Daytona v2, currently in alpha. For the latest release, see Daytona v0.

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

A Mac is reserved for a 24-hour period, and the reservation decides how the Mac is divided: one sandbox uses 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.

Term	Description
Reservation	One dedicated Mac for your organization for a 24-hour period. Nobody else uses that Mac while you hold it.
Layout	How a reservation divides its Mac: split runs up to two sandboxes at a time, whole runs one.
Model	The type of Mac, for example m4pro-12c-24g.
Auto-reserve	An organization setting that buys a Mac for you when you create a macOS sandbox and hold no reservation.
Image	A macOS disk that a sandbox starts from, for example base-macos or a snapshot of your sandbox.
Persistent	A sandbox that keeps its disk across stop and start. Stop, start, pause, resume and snapshots need it.

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.
• Computer-use agents on macOS: an agent operates macOS applications through screenshots and mouse and keyboard input.
• Long-lived build machines: a persistent sandbox keeps its disk across stop and start, so installed tools and build caches stay between sessions.
• Fleets of Macs: one request reserves up to 100 Macs for parallel builds and tests.

Requirements

Your organization must have macOS sandboxes turned on. Without it, the API answers 403 FEATURE_NOT_ENABLED when you reserve a Mac or create a macOS sandbox. Sign in to the dashboard at app.daytona.com ↗ and create a project API key. The examples read it from DAYTONA_API_KEY.

Endpoints

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

What	Address
Dashboard	https://app.daytona.com
Daytona API (organizations, API keys)	https://api.daytona.com
macOS API (reservations, macOS sandboxes)	https://api.us-macos.daytona.com
Sandbox SSH	ssh.us-macos.daytona.com, port 2222
Region of the Macs	macos-1

The SDKs and the CLI read the API address and your key from environment variables. Give the region macos-1 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. Do not use pip install --pre daytona or npm install @daytona/sdk@latest: they install other versions that do not have the macOS features.

Python

Python 3.10 or later:

pip install daytona==2.0.0a2

TypeScript

Node.js 22.4 or later:

npm install @daytona/sdk@2.0.0-alpha.2

CLI

On macOS or Linux:

curl -fsSL https://github.com/daytona/clients/releases/download/v2.0.0-alpha.2/install.sh | sh -s -- --version 2.0.0-alpha.2

With DAYTONA_API_KEY set, the CLI needs no daytona login.

Connect

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

Python

from daytona import Daytona

daytona = Daytona()  # reads DAYTONA_API_KEY and DAYTONA_API_URL

AsyncDaytona has the same methods with await.

TypeScript

import { Daytona } from '@daytona/sdk'

const daytona = new Daytona() // reads DAYTONA_API_KEY and DAYTONA_API_URL

Units

• In the SDKs, memory and disk are in GiB. In the CLI, --memory and --disk are in MiB.
• Python timeouts are in seconds.
• TypeScript timeouts of exec, start, pause, resume and process handles are in milliseconds. waitSeconds, createTimeoutSeconds and the timeout of sandbox.wait are in seconds.

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. A reservation has one layout, which you choose when you reserve, and you cannot change it. Both layouts cost the same. macOS sandboxes run only on your reservations: a create picks a reservation with free room, or you name one.

Layout	Description
split	Up to two sandboxes run on the Mac at the same time.
whole	One sandbox runs on the Mac.

Reservation statuses

Status	Description
pending_charge	We are charging the period.
pending_mac	The period is paid. The reservation waits for a free Mac. If no Mac accepts it within 5 minutes, it becomes failed and we refund the charge.
active	A Mac holds the reservation. period_end tells you when the period ends.
ending	The period ended. We stop the sandboxes, save persistent disks and erase the Mac. See when a reservation ends.
released	The reservation ended. end_reason tells you why, for example expired.
failed	The charge failed, or no Mac accepted the reservation (refunded).

Show more

• Useful reservation fields: id, status, model, layout, period_end, auto_renew, renewal_error, capacity (the Mac’s CPU, memory and sandbox disk), resources_used, slots_used and sandboxes_per_mac.

Models and prices

The production Macs are Apple M4 Pro, 12 cores, 24 GB memory. Their model ID is m4pro-12c-24g. Always give this model when you reserve. The price of one m4pro-12c-24g reservation is $2.5032 per Mac-hour, $60.08 per 24-hour period.

Layout	Sandboxes at a time	Default size of each sandbox
split (default)	2	6 vCPU, 12 GiB memory, 110 GiB disk
whole	1	12 vCPU, 24 GiB memory, 220 GiB disk

Read the current price and the number of free Macs from the Mac catalog (GET /mac-catalog). The number of free Macs is a guide only: another purchase can take a free Mac before yours.

Python

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,
            "free:", entry.available,
            "per period: $%.2f" % (price.period_cents / 100) if price else "no price",
        )
        for layout in entry.model.layouts:
            print("  ", layout.layout, layout.max_sandboxes, "sandboxes,",
                  layout.default_vcpus, "vCPU,", layout.default_memory_mib, "MiB,",
                  layout.default_disk_mib, "MiB disk")

• available is the number of free Macs.
• daytona.v2.mac_models.list() lists the models without prices.

TypeScript

const catalog = await daytona.v2.macModels.catalog({ region: 'macos-1' })
for (const region of catalog.regions) {
  for (const entry of region.models) {
    const perPeriod = entry.price ? `$${(entry.price.period_cents / 100).toFixed(2)}` : 'no price'
    console.log(entry.model.id, 'free:', entry.available, 'per period:', perPeriod)
  }
}

• available is the number of free Macs.
• daytona.v2.macModels.list() lists the models without prices.

CLI

daytona mac-model list --region macos-1

Reserve a Mac

Reserve one Mac of a model in a region, with the layout you choose. 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.

Python

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

TypeScript

const reservation = await daytona.v2.reservations.create({
  region: 'macos-1',
  model: 'm4pro-12c-24g',
  layout: 'split', // or 'whole'
  idempotencyKey: 'build-mac-2026-10-24',
})
console.log(reservation.id, reservation.status)

CLI

daytona reservation create --region macos-1 --model m4pro-12c-24g --layout split \
  --idempotency-key build-mac-2026-10-24

• auto_renew (autoRenew, --auto-renew) sets automatic renewal. If you do not set it, it follows your organization’s auto-reserve setting, which is on by default.
• If no Mac of the model is free, the request fails with 409 NO_MAC_AVAILABLE (ConflictError in the SDKs) and you pay nothing.

List and get reservations

List the reservations of your organization, or get one by its ID. The list returns the open reservations and the reservations that ended in the last 30 days.

Python

for r in daytona.v2.reservations.iter():  # every page
    print(r.id, r.status, r.layout, r.period_end, r.auto_renew)
r = daytona.v2.reservations.get(reservation.id)

TypeScript

const page = await daytona.v2.reservations.list() // one page; reservations.iter() reads them all
const one = await daytona.v2.reservations.get(reservation.id)

CLI

daytona reservation list
daytona reservation get RESERVATION_ID

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 free than you ask for, it reserves none and fails with 409 NO_MAC_AVAILABLE. Set a minimum count to accept fewer: the request then reserves as many as are free, if that is at least the minimum.

Python

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

TypeScript

const batch = await daytona.v2.reservations.createBulk({
  region: 'macos-1',
  model: 'm4pro-12c-24g',
  count: 20,
  minCount: 10,
  layout: 'whole',
  idempotencyKey: 'ci-fleet-2026-10-24',
})
console.log(`reserved ${batch.reserved} of ${batch.requested} Macs`)

CLI

--dry-run shows the price and the free Macs and reserves nothing.

daytona reservation create --region macos-1 --model m4pro-12c-24g --count 20 --dry-run
daytona reservation create --region macos-1 --model m4pro-12c-24g --count 20 --min-count 10 \
  --layout whole --idempotency-key ci-fleet-2026-10-24

• min_count (minCount, --min-count) sets the minimum count.
• A retry with the same key and the same body returns the same reservations. The same key with a different body fails with 409 IDEMPOTENCY_KEY_REUSED.
• If the charge of one Mac fails, that reservation shows failed and the others stay. The request fails with 402 only when every charge fails.

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.

Python

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

TypeScript

await daytona.v2.reservations.renew(reservation.id, { idempotencyKey: `renew-${reservation.id}-2` })

CLI

daytona reservation renew RESERVATION_ID --idempotency-key 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 period_end. If a renewal fails, the reservation shows the reason in renewal_error and ends at period_end.

Turn automatic renewal on or off for one reservation.

Python

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

TypeScript

await daytona.v2.reservations.update(reservation.id, { autoRenew: false })

CLI

daytona reservation 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, in that model’s default layout, 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 with 409 AUTO_RESERVE_LIMIT_REACHED.
• It does not buy a Mac when you have a reservation that is only full (NO_FREE_SLOT or MAC_DISK_FULL).
• An organization admin can turn it off, or change the limit, in the dashboard: Settings, Auto-reserve Macs.

Create a macOS sandbox

Create a macOS sandbox on one of your reservations. The base image is base-macos: macOS 26.6.2 with Xcode 26.6 and its iPhone simulator, Homebrew (with git, Node.js 24, Ruby, CocoaPods, fastlane, gh and jq) and Python 3.14. The user in the sandbox is lume, with home /Users/lume.

Without a size, each sandbox gets the default half of a split Mac or all of a whole Mac. The following examples create two sandboxes on one split reservation, each with the default half.

Python

r = daytona.v2.reservations.create(region="macos-1", model="m4pro-12c-24g", layout="split",
                             idempotency_key="split-mac-1")
a = daytona.v2.create_macos("base-macos", region="macos-1", reservation=r.id)
b = daytona.v2.create_macos("base-macos", region="macos-1", reservation=r.id)

The following example creates a persistent sandbox that uses a whole Mac:

r = daytona.v2.reservations.create(region="macos-1", model="m4pro-12c-24g", layout="whole",
                             idempotency_key="whole-mac-1")
sandbox = daytona.v2.create_macos(
    "base-macos",
    region="macos-1",
    reservation=r.id,
    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)

Parameter	Type	Description
image	str	Sets the macOS image that the sandbox starts from, for example base-macos or a snapshot. This is the first positional argument.
region	str	Sets the region, macos-1.
reservation	str	Sets the reservation that the sandbox runs on: a reservation ID, or "new". See which reservation.
auto_renew	bool	Sets automatic renewal of the reservation that the create buys. Only with reservation="new".
cpu	int	Sets whole vCPUs. See sizes.
memory	float	Sets the memory in GiB. See sizes.
disk	float	Sets the whole guest disk in GiB, macOS included. See sizes.
persistent	bool	Keeps the disk across stop and start. See filesystem persistence.
name	str	Sets the display name.
wait_seconds	int	Sets how many seconds the call waits for the sandbox to start.
create_timeout_seconds	int	Sets how many seconds the server tries before it deletes the waiting sandbox.

TypeScript

const r = await daytona.v2.reservations.create({
  region: 'macos-1', model: 'm4pro-12c-24g', layout: 'split', idempotencyKey: 'split-mac-1',
})
const a = await daytona.v2.createMacos('base-macos', { region: 'macos-1', reservation: r.id })
const b = await daytona.v2.createMacos('base-macos', { region: 'macos-1', reservation: r.id })

The following example creates a persistent sandbox that uses a whole Mac:

const r = await daytona.v2.reservations.create({
  region: 'macos-1', model: 'm4pro-12c-24g', layout: 'whole', idempotencyKey: 'whole-mac-1',
})
const sandbox = await daytona.v2.createMacos('base-macos', {
  region: 'macos-1',
  reservation: r.id,
  cpu: 12,
  memory: 24,
  disk: 220,
  persistent: true,
  name: 'ios-builder',
  waitSeconds: 120,
})
console.log(sandbox.id, sandbox.reservationId)

Parameter	Type	Description
image	string	Sets the macOS image that the sandbox starts from, for example base-macos or a snapshot. This is the first positional argument.
region	string	Sets the region, macos-1.
reservation	string	Sets the reservation that the sandbox runs on: a reservation ID, or 'new'. See which reservation.
autoRenew	boolean	Sets automatic renewal of the reservation that the create buys. Only with reservation: 'new'.
cpu	number	Sets whole vCPUs. See sizes.
memory	number	Sets the memory in GiB. See sizes.
disk	number	Sets the whole guest disk in GiB, macOS included. See sizes.
persistent	boolean	Keeps the disk across stop and start. See filesystem persistence.
name	string	Sets the display name.
waitSeconds	number	Sets how many seconds the call waits for the sandbox to start.
createTimeoutSeconds	number	Sets how many seconds the server tries before it deletes the waiting sandbox.

CLI

Run the command two times to create two sandboxes on one split reservation:

daytona sandbox create-macos --region macos-1 --image base-macos --reservation RESERVATION_ID

The following example creates a persistent sandbox that uses a whole Mac:

daytona sandbox create-macos --region macos-1 --image base-macos --reservation RESERVATION_ID \
  --vcpus 12 --memory 24576 --disk 225280 --persistent --name ios-builder

Flag	Type	Description
--image	string	Sets the macOS image that the sandbox starts from, for example base-macos or a snapshot.
--region	string	Sets the region, macos-1.
--reservation	string	Sets the reservation that the sandbox runs on: a reservation ID, or new. See which reservation.
--auto-renew	bool	Sets automatic renewal of the reservation that the create buys. Only with --reservation new.
--vcpus	int32	Sets whole vCPUs. See sizes.
--memory	int32	Sets the memory in MiB. See sizes.
--disk	int32	Sets the whole guest disk in MiB, macOS included. See sizes.
--persistent	bool	Keeps the disk across stop and start. See filesystem persistence.
--name	string	Sets the display name.
--wait	int	Sets how many seconds the server holds the create request before it returns.
--create-ttl	int	Sets how many seconds the server tries before it deletes the waiting sandbox.

• Other create options work as on Linux sandboxes: env, labels, secrets, ports and network_policy (networkPolicy, --block-all, --allow-domain, --allow-cidr).

Sizes

A macOS sandbox takes its CPU, memory and disk from the Mac of its reservation. The disk is the whole guest disk, macOS included. On m4pro-12c-24g, the sandboxes of one Mac share 12 vCPU, 24 GiB memory and 220 GiB disk. A Mac fixes the size when it accepts the sandbox, and sandbox.cpu, sandbox.memory and sandbox.disk show it from then on.

Setting	SDK (GiB)	CLI (MiB)	Minimum	If you omit it
CPU	cpu (whole vCPUs)	--vcpus	4	Half of the Mac (split), all of it (whole)
Memory	memory	--memory	4 GiB (4096 MiB)	Half of the Mac (split), all of it (whole)
Disk	disk	--disk	80 GiB (81920 MiB)	Half of the Mac’s sandbox disk (split), all of it (whole)

Which reservation

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

• Omit reservation: the sandbox goes on any of your reservations in the region that has room. If you have none, auto-reserve buys one (if it is on).
• reservation="<id>": the sandbox goes on that reservation.
• reservation="new": the create always buys a new reservation for this sandbox. Only here can you also set auto_renew.

The create can wait for room on a reservation. wait_seconds (waitSeconds, --wait) is how long the call waits for the sandbox to start. create_timeout_seconds (createTimeoutSeconds, --create-ttl) is how long the server tries before it deletes the waiting sandbox. Both are in seconds. If that 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.

Python

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

TypeScript

const sandbox = await daytona.v2.get('SANDBOX_ID')

CLI

daytona sandbox get SANDBOX_ID
daytona sandbox list --region macos-1

Run commands

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

Python

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)

TypeScript

const result = await sandbox.exec('sw_vers -productVersion && xcodebuild -version')
console.log(result.exitCode, result.output)

CLI

daytona sandbox exec SANDBOX_ID -- sw_vers -productVersion
daytona sandbox exec SANDBOX_ID --tty -- zsh        # an interactive shell
daytona sandbox cp ./App.zip SANDBOX_ID:/Users/lume/App.zip

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 #.

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.

Python

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"')

TypeScript

const token = await sandbox.createAccessToken({ operations: ['ssh'], ttlSeconds: 3600 })
console.log(`ssh -p 2222 "${sandbox.id}#${token.accessToken}@ssh.us-macos.daytona.com"`)

CLI

daytona sandbox ssh SANDBOX_ID
daytona sandbox ssh SANDBOX_ID -- ls /Users/lume

Caution

Do not put a project API key in an SSH command. Use a sandbox token: it is limited to this sandbox and to SSH.

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.

Computer use

Take screenshots and send mouse and keyboard input inside the sandbox with sandbox.computer_use (Python) and sandbox.computerUse (TypeScript). cu.a11y reads the accessibility tree and acts on controls, and cu.recording records the screen.

Python

import base64

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

shot = cu.screen.capture()
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())

TypeScript

const cu = sandbox.computerUse
await cu.start()
const shot = await cu.screen.capture()       // shot.screenshot is a base64 PNG
await cu.mouse.click({ x: 640, y: 400 })
await cu.keyboard.type({ text: 'hello from Daytona' })
await cu.keyboard.hotkey({ keys: 'cmd+space' })

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?rlp_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.

Log	Description
Console log	The macOS sandbox’s console output and our lifecycle lines. The API route is GET /sandboxes/SANDBOX_ID/console-logs.
Your own process logs	Run a command with process.start(...) and read handle.logs() or handle.stream_logs() (TypeScript: logs(), streamLogs()), or write logs to a file and copy it out.
Usage	daytona sandbox usage SANDBOX_ID.

daytona sandbox logs SANDBOX_ID
daytona sandbox logs SANDBOX_ID --follow

• macOS images have no entrypoint, so entrypoint_logs() (entrypointLogs(), logs --entrypoint) returns (no entrypoint output).

Lifecycle

Every macOS sandbox moves through a lifecycle. Stop, start, pause and resume need a persistent sandbox (persistent=True). 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.

Action	What happens
Stop	macOS shuts down. The disk stays on the same Mac and keeps its disk room on the reservation. The CPU, memory and slot are free for other sandboxes.
Start	macOS boots from the same disk on the same Mac. The reservation needs a free slot, CPU and memory for the sandbox, or start fails with NO_FREE_SLOT. Start never buys a reservation.
Pause	The Mac saves the memory of the sandbox. It keeps its place on the reservation.
Resume	The sandbox continues from the saved memory. If the memory cannot be restored, macOS boots from the disk and mac_boot_mode is cold_after_restore_failure.
Delete	The sandbox and its disk are erased. You cannot undo this.

Caution

A stopped or paused sandbox does not keep automatic renewal going. If all sandboxes on a reservation are stopped or paused at the end of the period, the reservation ends. See when a reservation ends.

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.

Python

sandbox.stop()
sandbox.start(timeout=120)

TypeScript

await sandbox.stop()
await sandbox.start({ timeout: 120_000 })

CLI

daytona sandbox stop SANDBOX_ID
daytona sandbox start SANDBOX_ID

Pause / resume

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

Python

sandbox.pause()
sandbox.resume()

TypeScript

await sandbox.pause()
await sandbox.resume()

CLI

daytona sandbox pause SANDBOX_ID
daytona sandbox resume SANDBOX_ID

Fork

Fork a persistent macOS sandbox to copy its disk into a new sandbox. A fork does not copy memory: memory=True fails with NOT_SUPPORTED_FOR_CLASS.

Python

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

TypeScript

const twin = await sandbox.fork({ name: 'ios-builder-2' })

CLI

daytona sandbox fork SANDBOX_ID --name ios-builder-2

Delete

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

Python

sandbox.delete()

TypeScript

await sandbox.delete()

CLI

daytona sandbox delete SANDBOX_ID

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).

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.

Python

sandbox.stop()
image = sandbox.snapshot_filesystem(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)

TypeScript

await sandbox.stop()
const image = await sandbox.snapshotFilesystem({ name: 'ios-builder-ready' })
const ready = await daytona.v2.images.get(image.id, { wait: 'ready', timeout: 3_600_000 })
const copy = await daytona.v2.createMacos('ios-builder-ready', { region: 'macos-1', persistent: true })

CLI

daytona sandbox stop SANDBOX_ID
daytona image capture SANDBOX_ID --name ios-builder-ready
daytona image list --name ios-builder-ready
daytona sandbox create-macos --region macos-1 --image ios-builder-ready --persistent

• The sandbox must be persistent and stopped, and its reservation must be active.
• The sandbox cannot start until the snapshot is ready.
• A snapshot with a name is kept until you delete it. A snapshot without a name is deleted when no sandbox is created from it for 7 days.

When a reservation ends

A reservation ends at period_end when it does not renew. There is no grace period, and we do not send a notice. Watch period_end, auto_renew and renewal_error on your reservations, or renew by hand.

At the end, in this order:

1. The reservation becomes ending. 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 becomes released. Every sandbox on it is deleted.

What you keep

Data	After the end
Disk of a persistent sandbox	Kept as an image without a name, unless its export fails. It is deleted when no sandbox is created from it for 30 days. Give it a name to keep it.
Snapshots you made	Kept. Named ones until you delete them. Unnamed ones while a sandbox is created from them at least once every 7 days.
Usage records and bills	Kept.
Sandboxes that are not persistent	Lost.
Memory of paused sandboxes	Lost. The disk is exported.
Console logs	Lost.
The Mac	Erased.

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.

Python

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)

TypeScript

const exports = await daytona.v2.images.list({ anonymous: true, sandboxId: 'OLD_SANDBOX_ID' })
const image = exports.items[0]
await daytona.v2.images.promote(image.id, 'ios-builder-day-2') // optional: keep it
const sandbox = await daytona.v2.createMacos(image.id, { region: 'macos-1', persistent: true, waitSeconds: 120 })

CLI

daytona image list --anonymous true --sandbox OLD_SANDBOX_ID
daytona image promote IMAGE_ID ios-builder-day-2
daytona sandbox create-macos --region macos-1 --image IMAGE_ID --persistent

Errors

The SDKs raise these errors as ConflictError (409), ForbiddenError (403, TypeScript AuthorizationError) or DaytonaError (402). Read error.code. 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.

Code	Meaning	What to do
NO_ACTIVE_RESERVATION	You have no live reservation in the region, and auto-reserve is off. Resume also returns it when the reservation of the paused sandbox is ending.	Reserve a Mac, or use reservation="new".
NO_FREE_SLOT	Your reservations have no room for this size.	Use a smaller size, delete a sandbox, or reserve another Mac.
MAC_DISK_FULL	The Macs of the reservations with room for this size have too little free disk space. A smaller disk does not help.	Delete a macOS sandbox on one of them, or reserve another Mac.
NO_MAC_AVAILABLE	No Mac of the model is free to buy.	Try again later, or reserve fewer (min_count).
AUTO_RESERVE_LIMIT_REACHED	Auto-reserve holds its maximum number of reservations.	Reserve a Mac yourself, or ask an admin to raise the limit.
IDEMPOTENCY_KEY_REUSED	The key was used for a different purchase, or for a sandbox create with a different size.	Use a new key.
INSUFFICIENT_BALANCE	Your balance does not cover the period of each Mac you reserve (402).	Add balance, or reserve fewer Macs.
CHARGE_FAILED	The charge for the period failed (402).	Contact us.
SNAPSHOT_IN_PROGRESS	A snapshot of this sandbox is in progress.	Wait until the image is ready.
NOT_SUPPORTED_FOR_CLASS	The action does not work on macOS, for example a fork with memory.	See the section for that action.
FEATURE_NOT_ENABLED	macOS sandboxes are not on for your organization.	Contact us.