> ## Documentation Index
> Fetch the complete documentation index at: https://celesto.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Disposable macOS environments

> Create a disposable macOS desktop on an Apple Silicon Mac, open it with Screen Sharing, share local folders, and delete it when you finish.

A macOS sandbox gives you a temporary Mac desktop for testing apps, opening installers, and trying changes away from your everyday system. It runs locally on your Apple Silicon Mac and opens in Apple's built-in Screen Sharing app.

![Disposable macOS desktop with Safari open to Hacker News inside a local virtualization window](https://mintcdn.com/celestoai/ERCC6T-f6R93UrWo/assets/celesto-macos-desktop.png?fit=max\&auto=format\&n=ERCC6T-f6R93UrWo\&q=85\&s=9a834e890dbec2b991192a97a9ce770d)

A disposable macOS sandbox running Safari on an Apple Silicon Mac

## What you can do

* Open and use a full macOS desktop.
* Test apps and installers, including apps distributed in `.dmg` files.
* Share a local folder with read-only access by default.
* Stop and restart a sandbox without losing its private files.
* Delete the sandbox to discard its apps, files, and changes.
* Reuse one prepared macOS image to create later sandboxes quickly.

Celesto keeps System Integrity Protection, Gatekeeper, and normal macOS permission prompts enabled. Apps behave as they would on a regular Mac.

## Before you start

You need:

* An Apple Silicon Mac
* macOS 14 or newer
* About 50 GB of free space for the first image preparation
* An APFS volume, the standard file system on modern Macs
* Celesto installed locally using the [installation guide](https://celesto.ai/docs/celesto/installation.md)

The first image preparation downloads an Apple restore file of about 15–18 GB. Download and installation usually take 20–40 minutes, depending on your connection and Mac.

> [!NOTE]
>
> The Apple restore file and prepared macOS image stay on the Mac where you create them. Image publishing, export, and transfer are unavailable for macOS images.

## Create your first macOS sandbox

After the one-time setup, you only need two commands: create the sandbox, then open its desktop.

**1. Prepare your Mac once**

Install the tested macOS desktop runtime:

```bash theme={null}
celesto setup --macos
```

Check that your Mac is ready:

```bash theme={null}
celesto doctor --backend vz
```

`vz` is the local runtime that uses Apple's built-in virtualization support.

> [!TIP]
>
> Continue when the doctor summary shows `Result: OK` and `Failures: 0`.

**2. Create the sandbox**

Create a sandbox named `nimble-mac`:

```bash theme={null}
celesto sandbox create --os macos --name nimble-mac
```

On the first run, Celesto asks before downloading and preparing macOS. Enter `y` to continue. The progress bar follows the download, installation, and desktop setup.

```text theme={null}
No local macOS image is ready. Celesto will download macOS from Apple...
Continue? [y/N]: y
```

When creation finishes, the sandbox is already running. The output includes the next command. Your start time will differ:

```text theme={null}
╭─────── VM Created ───────╮
│ Created VM 'nimble-mac'. │
╰──────────────────────────╯
             VM Details
┌─────────┬─────────────────────────┐
│ Name    │ nimble-mac              │
│ Status  │ running                 │
│ OS      │ macos                   │
│ Started │ 2026-07-24 18:08:50 UTC │
└─────────┴─────────────────────────┘
Next: celesto sandbox desktop nimble-mac
Info: celesto sandbox info nimble-mac
```

> [!TIP]
>
> If installation fails after the download completes, run the same command again. Celesto keeps the completed restore file and reuses it instead of downloading another copy.

**3. Open the desktop**

Run the `Next` command from the create output:

```bash theme={null}
celesto sandbox desktop nimble-mac
```

Celesto opens Screen Sharing and confirms the connection:

```text theme={null}
Opened the desktop for sandbox 'nimble-mac'.
```

Celesto supplies the private Screen Sharing password automatically. At the macOS login screen, use:

* **Username:** `lume`
* **Password:** `lume`

> [!WARNING]
>
> The fixed guest login is a preview limitation. Keep the sandbox local and avoid sensitive accounts or data.

## Copy and paste between your Mac and the sandbox

Copy and paste works in both directions between your Mac and a macOS sandbox out of the box. Copy on one side, paste on the other — no extra setup.

If you would rather keep the two clipboards separate, turn clipboard sync off when you create the sandbox:

```bash theme={null}
celesto sandbox create --os macos --name private-mac --no-clipboard
```

The choice is saved with the sandbox, so stopping and starting it later keeps the same setting.

> [!WARNING]
>
> With clipboard sync on, text you copy on your Mac is readable from inside the running sandbox, including passwords, API keys, and other secrets. Use `--no-clipboard` for sandboxes where you do not want the guest to see host clipboard contents.

## Share a local folder

Create a new sandbox that can read your current folder:

```bash theme={null}
celesto sandbox create --os macos --name shared-mac --mount "$PWD"
```

Open Finder inside the sandbox to access the shared folder. The sandbox receives read-only access by default.

Allow changes only when the sandbox needs to edit your local files:

```bash theme={null}
celesto sandbox create --os macos --name editing-mac --mount "$PWD" --writable-mounts
```

> [!WARNING]
>
> A writable shared folder lets apps inside the sandbox change or delete files in that folder. Share only the files needed for the task.

## Stop, reopen, and discard the sandbox

Stop the sandbox when you want to keep its private files for later:

```bash theme={null}
celesto sandbox stop nimble-mac
```

Start it and open the desktop again:

```bash theme={null}
celesto sandbox desktop nimble-mac --start
```

Delete it when you want to discard its installed apps, files, and other changes:

```bash theme={null}
celesto sandbox delete nimble-mac
```

The reusable macOS image remains after deletion, so the next sandbox starts much faster.

> [!TIP]
>
> Deleting a sandbox removes its private desktop. The reusable base image and files in read-only shared folders remain available.

## Prepare the image ahead of time

Run the long preparation step before you need your first sandbox:

```bash theme={null}
celesto image build --os macos --ipsw latest -t macos-latest
```

> [!NOTE]
>
> Celesto uses the macOS image's fixed size and selects `vz` automatically. Run the command as shown; `--size-mb` and `--backend` are available for Linux image builds instead.

Celesto downloads the latest compatible restore file from Apple, installs it locally, and prepares the desktop account. Later `sandbox create` commands reuse this image.

List local images:

```bash theme={null}
celesto image list
```

Remove the reusable macOS image when you no longer need it:

```bash theme={null}
celesto image rm macos-latest
```

Removing the image frees its local storage. The next macOS sandbox must prepare a new image.

## How it works

Celesto keeps one reusable macOS base image. Each sandbox receives a fast APFS clone, a private copy that stores only its own changes.

This means:

* Installing an app in one sandbox does not add it to the base image.
* Two sandboxes do not share their private changes.
* Stopping a sandbox keeps its changes.
* Deleting a sandbox discards its private clone.

The Screen Sharing connection listens on `127.0.0.1`, an address that only your Mac can reach. Screen Sharing uses VNC (Virtual Network Computing, a standard way to view and control another computer's screen). Celesto stores the generated connection password in the sandbox's private files and keeps it out of commands, logs, and API responses.

### Lume

Celesto uses [Lume](https://github.com/trycua/cua/tree/main/libs/lume) behind the scenes to prepare and run the macOS desktop. Lume is an open-source project that works with Apple's built-in system for running virtual Macs.

`celesto setup --macos` installs the tested Lume version for you, and Celesto handles it through the commands in this guide. The `lume` login name comes from the desktop account that Lume creates during automatic setup.

## Preview limits

* You can run at most two macOS sandboxes at the same time.
* Each sandbox uses 4 CPU cores, 8 GB of memory, and an 80 GB logical disk. Custom sizes are not available yet.
* Shell commands, SSH sessions, file transfer commands, and SSH tunnels are not available through Celesto for macOS guests yet.
* Bridge networking, outbound-domain rules, pause and resume, snapshots, and browser sessions are not available for macOS guests yet.
* The prepared image and sandbox clones remain tied to the local Mac.

Review [Apple's software license agreements](https://www.apple.com/legal/sla/) and use a Mac you own or control for permitted development and testing.

## Troubleshooting

> [accordion] The confirmation prompt says invalid input
>
> Enter only `y` or `n` at `Continue? [y/N]:`. For unattended scripts, approve the one-time image preparation explicitly:
>
> ```bash theme={null}
> celesto sandbox create --os macos --name nimble-mac --yes
> ```

> [accordion] Image installation failed after the download
>
> Run the create command again. Celesto stores a completed restore download under `~/.celesto/images/macos/.downloads/` and reuses it for the next installation attempt.

> [accordion] Screen Sharing did not open
>
> Confirm that the sandbox is running, then allow more time for startup:
>
> ```bash theme={null}
> celesto sandbox desktop nimble-mac --start --boot-timeout 120
> ```

> [accordion] Celesto reports an unsupported or unreadable runtime
>
> Reinstall the tested runtime and check it again:
>
> ```bash theme={null}
> celesto setup --macos
> celesto doctor --backend vz
> ```

> [accordion] A third macOS sandbox will not start
>
> Apple allows at most two running macOS virtual machines on supported hardware. Stop one sandbox, then start the other:
>
> ```bash theme={null}
> celesto sandbox stop nimble-mac
> ```

## Next steps

> [card] [Create a sandbox](https://celesto.ai/docs/celesto/cli/create.md)
>
> Review the sandbox creation options

> [card] [Share local folders](https://celesto.ai/docs/celesto/features/host-mounts.md)
>
> Control read-only and writable folder access

> [card] [Sandbox lifecycle](https://celesto.ai/docs/celesto/guides/vm-lifecycle.md)
>
> Start, stop, inspect, and delete sandboxes

> [card] [Security model](https://celesto.ai/docs/celesto/concepts/security.md)
>
> Understand isolation and local access


## Related topics

- [CLI overview](https://celesto.ai/docs/celesto/cli/overview.md)
- [celesto sandbox create](https://celesto.ai/docs/celesto/cli/create.md)
- [Install Celesto on Linux or macOS](https://celesto.ai/docs/celesto/installation.md)
- [Firecracker, QEMU, and libkrun backends](https://celesto.ai/docs/celesto/concepts/backends.md)
- [Authenticate the Celesto SDK and CLI](https://celesto.ai/docs/cloud/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.