Cloud Sandbox Management

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.

List Sandboxes

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

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)

[
  {
    "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

Start a Sandbox

Provide the sandbox name you want to start.

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

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

HTTP/1.1 204 No Content

Stop a Sandbox

Stops the sandbox asynchronously.

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

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

{ "status": "stopping" }

Restart a Sandbox

Restarts the sandbox asynchronously.

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

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

{ "status": "restarting" }

Query a Sandbox by name

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

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

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

Responses:

200: Server available

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

Was this page helpful?

Cloud Sandbox Management

List Sandboxes

Start a Sandbox

Stop a Sandbox

Restart a Sandbox

Query a Sandbox by name

On this page