# macOS Sandboxes (/docs/macos-sandboxes)
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. 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.
| **Term** | **Description** |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| **Reservation** | One dedicated Mac for your organization for a 24-hour period. Nobody else uses that Mac while you hold it. |
| **Size** | The cores, memory and disk of one sandbox. You choose it when you create the sandbox. |
| **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 [#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 [#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 ↗](https://app.daytona.com) and create a project API key. The examples read it from `DAYTONA_API_KEY`.
### Endpoints [#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.
```bash
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 [#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 3.10 or later:
```bash
pip install daytona==2.0.0a2
```
Node.js 22.4 or later:
```bash
npm install @daytona/sdk@2.0.0-alpha.2
```
On macOS or Linux:
```bash
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 [#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
```
- 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 [#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](#sizes) of each sandbox when you create it.
| **Status** | **Description** |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending_charge` | We are charging the period. |
| `pending_mac` | The period is paid. The reservation waits for an available 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](#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). |
- Useful reservation fields: `id`, `status`, `model`, `period_end`, `auto_renew`, `renewal_error`, `capacity` (the Mac's cores, memory and sandbox disk), `resources_used`, `slots_used` and `sandboxes_per_mac`.
### Models and prices [#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**.
| **Model** | **Cores** | **Memory** | **Sandbox disk** | **Sandboxes at a time** |
| --------------------- | --------- | ---------- | ---------------- | ----------------------- |
| **`m4pro-12c-24g`** | 12 | 24 GiB | 220 GiB | Up to 2 |
The sizes of the sandboxes on one Mac must fit in its cores, memory and sandbox disk together. See [sizes](#sizes).
Read the current price and the number of available Macs from the Mac catalog (`GET /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.
```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,
"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.vcpus, model.memory_mib, model.max_sandboxes)
```
- `available` is the number of Macs nobody has reserved.
```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, 'available:', entry.available, 'per period:', perPeriod)
}
}
// Model specs only; the catalog adds prices and available Macs per region
for (const model of await daytona.v2.macModels.list()) {
console.log(model.id, model.vcpus, model.memory_mib, model.max_sandboxes)
}
```
- `available` is the number of Macs nobody has reserved.
```bash
daytona mac-model list --region macos-1
```
```bash
# Catalog: available Macs and prices per model; region is a comma-separated list, all regions by default
curl 'https://api.us-macos.daytona.com/mac-catalog?region=macos-1' \
--header 'Authorization: Bearer YOUR_API_KEY'
# Model specs only; the catalog adds prices and available Macs per region
curl 'https://api.us-macos.daytona.com/mac-models' \
--header 'Authorization: Bearer YOUR_API_KEY'
```
| **Field** | **Description** |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `default_model` | The model a reservation in the region gets when it names none. |
| `available` | The number of Macs of the model that nobody has reserved. A guide only; another purchase can reserve one first. |
| `price` | `period_cents`, `cents_per_hour`, `period_seconds` and `currency`. `null` where billing is not enabled. |
| `max_sandboxes` | The most sandboxes a Mac of the model runs at once. |
| `sandbox_disk_mib` | The disk room for all sandboxes on one Mac, stopped sandboxes included. |
- Any API key can read the catalog and the models; no permission is required.
### Reserve a Mac [#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.
```python
reservation = daytona.v2.reservations.create(
region="macos-1",
model="m4pro-12c-24g",
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',
idempotencyKey: 'build-mac-2026-10-24',
})
console.log(reservation.id, reservation.status)
```
```bash
daytona reservation create --region macos-1 --model m4pro-12c-24g \
--idempotency-key build-mac-2026-10-24
```
```bash
curl 'https://api.us-macos.daytona.com/reservations' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Idempotency-Key: build-mac-2026-10-24' \
--data '{ "region": "macos-1", "model": "m4pro-12c-24g" }'
```
- The `Idempotency-Key` header is required. The API does not generate a key.
- A new reservation returns `201`. A retry with the same key returns `200` and the existing reservation.
- `auto_renew` (`autoRenew`, `--auto-renew`) sets [automatic renewal](#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 available, the request fails with `409 NO_MAC_AVAILABLE` (`ConflictError` in the SDKs) and you pay nothing.
### List and get reservations [#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.model, 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)
```
```bash
daytona reservation list
daytona reservation get RESERVATION_ID
```
```bash
# Paginated; follow next_cursor for more rows
curl 'https://api.us-macos.daytona.com/reservations?limit=100' \
--header 'Authorization: Bearer YOUR_API_KEY'
curl 'https://api.us-macos.daytona.com/reservations/RESERVATION_ID' \
--header 'Authorization: Bearer YOUR_API_KEY'
```
| **Field** | **Type** | **Description** |
| ------------ | ------------- | -------------------------------------------------------------------------------------- |
| `limit` | `integer` | Sets the maximum number of items, from `1` to `200`. The default is `100`. |
| `cursor` | `string` | Pass the `next_cursor` value of the previous response to read the next page. |
### Reserve many Macs [#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 with `409 NO_MAC_AVAILABLE`. Set a minimum count to accept fewer: the request then reserves as many as are available, 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,
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,
idempotencyKey: 'ci-fleet-2026-10-24',
})
console.log(`reserved ${batch.reserved} of ${batch.requested} Macs`)
```
`--dry-run` shows the price and the available Macs and reserves nothing.
```bash
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 \
--idempotency-key ci-fleet-2026-10-24
```
```bash
curl 'https://api.us-macos.daytona.com/reservations/bulk' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Idempotency-Key: ci-fleet-2026-10-24' \
--data '{ "region": "macos-1", "model": "m4pro-12c-24g", "count": 20, "min_count": 10 }'
```
- The `Idempotency-Key` header is required. The API does not generate a key.
- The response has `requested`, `reserved` and `reservations`, one entry per reserved Mac.
- `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]
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` })
```
```bash
daytona reservation renew RESERVATION_ID --idempotency-key renew-RESERVATION_ID-2
```
```bash
curl 'https://api.us-macos.daytona.com/reservations/RESERVATION_ID/renew' \
--request POST \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Idempotency-Key: renew-RESERVATION_ID-2'
```
- The `Idempotency-Key` header is required. The API does not generate a key.
### Automatic renewal [#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 })
```
```bash
daytona reservation update RESERVATION_ID --auto-renew=false
```
```bash
curl 'https://api.us-macos.daytona.com/reservations/RESERVATION_ID' \
--request PATCH \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{ "auto_renew": false }'
```
### Auto-reserve [#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 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]
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`.
You choose the [size](#sizes) of each sandbox when you create it. Two sandboxes share one Mac when their sizes fit in the Mac together. The following examples create two sandboxes of different sizes on one reservation.
```python
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,
cpu=4, memory=8, disk=100)
b = daytona.v2.create_macos("base-macos", region="macos-1", reservation=r.id,
cpu=8, memory=16, disk=120)
```
The following example creates a persistent sandbox that uses the whole Mac:
```python
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,
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](#which-reservation). |
| `auto_renew` | bool | Sets [automatic renewal](#automatic-renewal) of the reservation that the create buys. Only with `reservation="new"`. |
| `cpu` | int | Sets the number of CPU cores. See [sizes](#sizes). |
| `memory` | float | Sets the memory in GiB. See [sizes](#sizes). |
| `disk` | float | Sets the whole guest disk in GiB, macOS included. See [sizes](#sizes). |
| `persistent` | bool | Keeps the disk across stop and start. See [filesystem persistence](#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', idempotencyKey: 'shared-mac-1',
})
const a = await daytona.v2.createMacos('base-macos', {
region: 'macos-1', reservation: r.id, cpu: 4, memory: 8, disk: 100,
})
const b = await daytona.v2.createMacos('base-macos', {
region: 'macos-1', reservation: r.id, cpu: 8, memory: 16, disk: 120,
})
```
The following example creates a persistent sandbox that uses the whole Mac:
```typescript
const r = await daytona.v2.reservations.create({
region: 'macos-1', model: 'm4pro-12c-24g', idempotencyKey: 'ios-builder-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](#which-reservation). |
| `autoRenew` | boolean | Sets [automatic renewal](#automatic-renewal) of the reservation that the create buys. Only with `reservation: 'new'`. |
| `cpu` | number | Sets the number of CPU cores. See [sizes](#sizes). |
| `memory` | number | Sets the memory in GiB. See [sizes](#sizes). |
| `disk` | number | Sets the whole guest disk in GiB, macOS included. See [sizes](#sizes). |
| `persistent` | boolean | Keeps the disk across stop and start. See [filesystem persistence](#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. |
Create two sandboxes of different sizes on one reservation:
{/* snippet-check: skip The daytona CLI hides sandbox create-macos from its help. */}
```bash
daytona sandbox create-macos --region macos-1 --image base-macos --reservation RESERVATION_ID \
--vcpus 4 --memory 8192 --disk 102400
daytona sandbox create-macos --region macos-1 --image base-macos --reservation RESERVATION_ID \
--vcpus 8 --memory 16384 --disk 122880
```
The following example creates a persistent sandbox that uses the whole Mac:
{/* snippet-check: skip The daytona CLI hides sandbox create-macos from its help. */}
```bash
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](#which-reservation). |
| `--auto-renew` | bool | Sets [automatic renewal](#automatic-renewal) of the reservation that the create buys. Only with `--reservation new`. |
| `--vcpus` | int32 | Sets the number of CPU cores. See [sizes](#sizes). |
| `--memory` | int32 | Sets the memory in MiB. See [sizes](#sizes). |
| `--disk` | int32 | Sets the whole guest disk in MiB, macOS included. See [sizes](#sizes). |
| `--persistent` | bool | Keeps the disk across stop and start. See [filesystem persistence](#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](/docs/v2/linux-sandboxes#create-a-linux-sandbox): `env`, `labels`, `secrets`, `ports` and `network_policy` (`networkPolicy`, `--block-all`, `--allow-domain`, `--allow-cidr`).
### Sizes [#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 `m4pro-12c-24g`, 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 `sandbox.cpu`, `sandbox.memory` and `sandbox.disk` show it from then on.
| **Setting** | **SDK (GiB)** | **CLI (MiB)** | **Minimum** | **Maximum on `m4pro-12c-24g`** | **If you omit it, on `m4pro-12c-24g`** |
| ----------- | ----------------- | -------------- | ------------------ | ------------------------------ | -------------------------------------- |
| Cores | **`cpu`** (cores) | **`--vcpus`** | 4 | 12 | 6 |
| Memory | **`memory`** | **`--memory`** | 4 GiB (4096 MiB) | 24 GiB (24576 MiB) | 12 GiB (12288 MiB) |
| Disk | **`disk`** | **`--disk`** | 80 GiB (81920 MiB) | 220 GiB (225280 MiB) | 110 GiB (112640 MiB) |
### Which reservation [#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](#auto-reserve) buys one (if it is on).
- `reservation=""`: 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-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')
```
```bash
daytona sandbox get SANDBOX_ID
daytona sandbox list --region macos-1
```
## Run commands [#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)
```
```bash
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 [#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"`)
```
```bash
daytona sandbox ssh SANDBOX_ID
daytona sandbox ssh SANDBOX_ID -- ls /Users/lume
```
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 [#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 [#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 [#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).
```text
wss://proxy.us-macos.daytona.app/vnc/SANDBOX_ID?rlp_token=TOKEN
```
```python
token = sandbox.create_access_token(operations=["desktop"], ttl_seconds=3600)
```
## Logs [#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`. |
```bash
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 [#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 cores, memory and slot become available to other sandboxes. |
| Start | macOS boots from the same disk on the same Mac. The reservation needs an open slot and enough cores 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. |
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](#when-a-reservation-ends).
### Stop / start [#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.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)
```
```typescript
await sandbox.stop()
await sandbox.wait({ until: 'stopped' })
await sandbox.start({ timeout: 120_000 })
// Stop a sandbox by ID, without fetching it first
await daytona.v2.stop('SANDBOX_ID')
// Start a stopped sandbox by ID
await daytona.v2.start('SANDBOX_ID', { timeout: 120_000 })
```
```bash
daytona sandbox stop SANDBOX_ID
daytona sandbox start SANDBOX_ID
```
### Pause / resume [#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()
# 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")
```
```typescript
await sandbox.pause()
await sandbox.resume()
// Pause a sandbox by ID, without fetching it first
await daytona.v2.pause('SANDBOX_ID')
// Resume a paused sandbox by ID
await daytona.v2.resume('SANDBOX_ID')
```
```bash
daytona sandbox pause SANDBOX_ID
daytona sandbox resume SANDBOX_ID
```
### Fork [#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' })
```
```bash
daytona sandbox fork SANDBOX_ID --name ios-builder-2
```
### Delete [#delete]
Delete a macOS sandbox to erase the sandbox and its disk. You cannot undo this.
```python
sandbox.delete()
```
```typescript
await sandbox.delete()
```
```bash
daytona sandbox delete SANDBOX_ID
```
## Filesystem persistence [#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](#filesystem-snapshot), or let the end of the reservation save it (see [when a reservation ends](#when-a-reservation-ends)).
## Filesystem snapshot [#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 })
```
{/* snippet-check: skip The daytona CLI hides sandbox create-macos from its help. */}
```bash
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 [#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](#renew-a-reservation).
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 [#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 [#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 })
```
{/* snippet-check: skip The daytona CLI hides sandbox create-macos from its help. */}
```bash
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 [#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 disk space left. 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 available to reserve. | 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. |