---
title: Cloud Sandbox Management
description: Manage your Cua Cloud sandboxes via Python SDK or HTTP API
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Using the Cua Cloud API, you can manage your Cua Cloud sandboxes with Python or HTTP (curl).

All examples require a CUA API key. You can obtain one from the [Dashboard](https://www.cua.ai/dashboard/keys).

---

## List Sandboxes

<Tabs items={['Python', 'curl']}>
  <Tab value="Python">

```python
import asyncio
from computer.providers.cloud.provider import CloudProvider

async def main():
    # CloudProvider automatically reads CUA_API_KEY from environment
    # You can also pass api_key explicitly: CloudProvider(api_key="your-api-key")
    # Optional: point to a different API base
    # os.environ["CUA_API_BASE"] = "https://api.cua.ai"

    provider = CloudProvider(verbose=False)
    async with provider:
        vms = await provider.list_vms()
        for vm in vms:
            print({
                "name": vm["name"],
                "status": vm["status"],
                "api_url": vm.get("api_url"),
                "vnc_url": vm.get("vnc_url"),
            })

if __name__ == "__main__":
    asyncio.run(main())
```

  </Tab>
  <Tab value="curl">

```bash
curl -H "Authorization: Bearer $CUA_API_KEY" \
     "https://api.cua.ai/v1/vms"
```

Responses:

- 200: Array of minimal sandbox objects with fields `{ name, password, status }`
- 401: Unauthorized (missing/invalid API key)

```json
[
  {
    "name": "s-windows-x4snp46ebf",
    "password": "49b8daa3",
    "status": "running"
  }
]
```

Status values:

- `pending`: Sandbox deployment in progress
- `running`: Sandbox is active and accessible
- `stopped`: Sandbox is stopped but not terminated
- `terminated`: Sandbox has been permanently destroyed
- `failed`: Sandbox deployment or operation failed

---

      </Tab>

  </Tabs>

---

## Start a Sandbox

Provide the sandbox name you want to start.

<Tabs items={["Python", "curl"]}>
  <Tab value="Python">

```python
import asyncio
from computer.providers.cloud.provider import CloudProvider

async def main():
    # CloudProvider automatically reads CUA_API_KEY from environment
    name = "my-vm-name"  # e.g., "m-linux-96lcxd2c2k"

    provider = CloudProvider()
    async with provider:
        resp = await provider.run_vm(name)
        print(resp)  # { "name": name, "status": "starting" }

if __name__ == "__main__":
    asyncio.run(main())
```

  </Tab>
  <Tab value="curl">

```bash
curl -X POST \
     -H "Authorization: Bearer $CUA_API_KEY" \
     "https://api.cua.ai/v1/vms/my-vm-name/start" -i
```

Responses:

- 204: No Content (start accepted)
- 401: Unauthorized (missing/invalid API key)
- 404: Sandbox not found or not owned by the user

```text
HTTP/1.1 204 No Content
```

  </Tab>
</Tabs>

---

## Stop a Sandbox

Stops the sandbox asynchronously.

<Tabs items={["Python", "curl"]}>
  <Tab value="Python">

```python
import asyncio
from computer.providers.cloud.provider import CloudProvider

async def main():
    # CloudProvider automatically reads CUA_API_KEY from environment
    name = "my-vm-name"

    provider = CloudProvider()
    async with provider:
        resp = await provider.stop_vm(name)
        print(resp)  # { "name": name, "status": "stopping" }

if __name__ == "__main__":
    asyncio.run(main())
```

  </Tab>
  <Tab value="curl">

```bash
curl -X POST \
     -H "Authorization: Bearer $CUA_API_KEY" \
     "https://api.cua.ai/v1/vms/my-vm-name/stop"
```

Responses:

- 202: Accepted with `{ "status": "stopping" }`
- 401: Unauthorized (missing/invalid API key)
- 404: Sandbox not found or not owned by the user

```json
{ "status": "stopping" }
```

  </Tab>
</Tabs>

---

## Restart a Sandbox

Restarts the sandbox asynchronously.

<Tabs items={["Python", "curl"]}>
  <Tab value="Python">

```python
import asyncio
from computer.providers.cloud.provider import CloudProvider

async def main():
    # CloudProvider automatically reads CUA_API_KEY from environment
    name = "my-vm-name"

    provider = CloudProvider()
    async with provider:
        resp = await provider.restart_vm(name)
        print(resp)  # { "name": name, "status": "restarting" }

if __name__ == "__main__":
    asyncio.run(main())
```

  </Tab>
  <Tab value="curl">

```bash
curl -X POST \
     -H "Authorization: Bearer $CUA_API_KEY" \
     "https://api.cua.ai/v1/vms/my-vm-name/restart"
```

Responses:

- 202: Accepted with `{ "status": "restarting" }`
- 401: Unauthorized (missing/invalid API key)
- 404: Sandbox not found or not owned by the user

```json
{ "status": "restarting" }
```

  </Tab>
</Tabs>

---

## Query a Sandbox by name

Query the computer-server running on the sandbox. Useful for checking details like status or OS type.

<Tabs items={["Python", "curl"]}>
  <Tab value="Python">

```python
import asyncio
from computer.providers.cloud.provider import CloudProvider

async def main():
    # CloudProvider automatically reads CUA_API_KEY from environment
    name = "my-vm-name"

    provider = CloudProvider()
    async with provider:
        info = await provider.get_vm(name)
        print(info)

if __name__ == "__main__":
    asyncio.run(main())
```

  </Tab>
  <Tab value="curl">

```bash
curl "https://my-vm-name.containers.cloud.cua.ai:8443/status"
```

Responses:

- 200: Server available

```json
{ "status": "ok", "os_type": "linux", "features": ["agent"] }
```

  </Tab>
</Tabs>
