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

# celesto sandbox create

> Start a new sandbox with celesto sandbox create. Name it, choose an image or operating system, share a project folder, and get JSON output for scripts.

`celesto sandbox create` starts a new sandbox and leaves it running. Give it a name when you want to use the same sandbox in later commands, or let Celesto generate one for you.

## Synopsis

```bash theme={null}
celesto sandbox create [OPTIONS]
```

## Options

**--name, -n** `string`

Name for the sandbox. If you omit it, Celesto creates a unique name.

**--os** `string`

Guest operating system image. Supported values are `alpine`, `ubuntu`, `windows`, and `macos`. Omit it for the default Linux image, pair `windows` with `--image`, or see [Disposable macOS environments](https://celesto.ai/docs/celesto/guides/macos-sandboxes.md) before using `macos`.

**--image** `string`

Image reference to boot. Use an S3 image URI, a `file://` URI, or a local `qcow2` path for Windows guests.

**--memory** `integer`

Guest memory in MiB.

**--disk-size** `integer`

Guest disk size in MiB.

**--backend** `string`

Runtime backend. Choices are `auto`, `firecracker`, `qemu`, `libkrun`, and `vz`. Celesto selects `vz` automatically for macOS guests.

**--qemu-machine** `string` (default: auto)

QEMU machine model. Choices are `auto`, `q35`, and `microvm`.

**--comm-channel** `string`

Host-to-guest control channel. Choices are `ssh` and `vsock`. Leave unset for auto-selection.

**--mount** `string`

Share a host folder with the sandbox. Use `HOST_PATH` or `HOST_PATH:GUEST_PATH`. You can pass this option more than once.

**--writable-mounts** `flag`

Allow writes to every shared folder from this command.

**--clipboard / --no-clipboard** `flag` (default: --clipboard)

Share the clipboard between your Mac and a macOS sandbox desktop. On by default for macOS guests. Use `--no-clipboard` to keep the two clipboards separate. The choice is saved with the sandbox and applies across stop and start. See [Copy and paste between your Mac and the sandbox](https://celesto.ai/docs/celesto/guides/macos-sandboxes.md#copy-and-paste-between-your-mac-and-the-sandbox).

**--yes** `flag`

Approve the one-time macOS image download and preparation without an interactive prompt.

**--network** `string` (default: nat)

Network mode for the sandbox. Choices are `nat` (default, private Celesto network with NAT, port forwarding, and outbound network controls) and `bridge` (attach directly to an existing host bridge on Linux). See [Bridged networking](https://celesto.ai/docs/celesto/features/bridged-networking.md).

**--bridge** `string`

Name of the Linux bridge to attach to. Required with `--network bridge` and rejected otherwise. Run [`celesto bridge check BRIDGE`](https://celesto.ai/docs/celesto/features/bridged-networking#check-a-bridge-before-you-use-it) first to verify the bridge.

**--boot-timeout** `number` (default: 30)

Seconds to wait for the sandbox to become ready.

**--json** `flag`

Print a JSON envelope instead of formatted text.

## Examples

### Create a default sandbox

```bash theme={null}
celesto sandbox create
```

### Create a named Ubuntu sandbox

```bash theme={null}
celesto sandbox create --name dev-env --os ubuntu --disk-size 4096
```

### Share a project folder

```bash theme={null}
celesto sandbox create \
  --name code-review \
  --mount ~/Projects/my-app:/workspace
```

By default, shared folders are read-only. Add `--writable-mounts` only when the sandbox should edit host files directly.

### Use QEMU microvm explicitly

```bash theme={null}
celesto sandbox create \
  --name qemu-fast-path \
  --backend qemu \
  --qemu-machine microvm
```

### Attach a sandbox to a host bridge

On Linux, connect the sandbox directly to an existing bridge so it appears as a regular machine on that network with its own MAC and guest-managed IP:

```bash theme={null}
celesto bridge check br10
celesto sandbox create --name demo --os alpine --network bridge --bridge br10
```

In bridge mode, SSH from the host, host port forwards, workspace mounts, and Celesto-managed outbound controls are unavailable — use `celesto sandbox shell` and connect to guest services over the bridged network instead. See [Bridged networking](https://celesto.ai/docs/celesto/features/bridged-networking.md) for the full setup, tradeoffs, and SDK usage.

### Create a Windows sandbox from a local image

```bash theme={null}
celesto sandbox create \
  --name win11-test \
  --os windows \
  --image ~/.celesto/images/win11.qcow2
```

See [Windows sandboxes](https://celesto.ai/docs/celesto/guides/windows-guests.md) before running Windows guests.

### Create a macOS desktop sandbox

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

The sandbox starts immediately when a prepared macOS image is available. The output shows its `running` status and the next command:

```text theme={null}
Next: celesto sandbox desktop nimble-mac
Info: celesto sandbox info nimble-mac
```

Open the desktop:

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

The first macOS sandbox asks before downloading and preparing a local image. See [Disposable macOS environments](https://celesto.ai/docs/celesto/guides/macos-sandboxes.md) for host requirements, one-time setup, and preview limits.

## What happens

1. Celesto resolves the image, backend, and control channel.
2. It creates a per-sandbox disk and network configuration.
3. It starts the sandbox and waits for the guest to be ready.
4. It prints the sandbox name and suggested next commands.

## Related commands

* [`celesto sandbox shell`](https://celesto.ai/docs/celesto/cli/shell) - Open the fast shell
* [`celesto sandbox ssh`](https://celesto.ai/docs/celesto/cli/ssh) - Open an SSH session
* [`celesto sandbox desktop`](https://celesto.ai/docs/celesto/guides/macos-sandboxes) - Open a macOS sandbox in Screen Sharing
* [`celesto sandbox list`](https://celesto.ai/docs/celesto/cli/list) - View sandboxes
* [`celesto sandbox delete`](https://celesto.ai/docs/celesto/cli/cleanup) - Delete one or more sandboxes


## Related topics

- [celesto sandbox list](https://celesto.ai/docs/celesto/cli/list.md)
- [celesto sandbox ssh](https://celesto.ai/docs/celesto/cli/ssh.md)
- [celesto sandbox shell](https://celesto.ai/docs/celesto/cli/shell.md)
- [Run Docker in a Celesto sandbox](https://celesto.ai/docs/celesto/features/docker.md)
- [celesto server](https://celesto.ai/docs/celesto/cli/server.md)


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