Add Cloud VM Management API

docs/content/docs/computer-sdk/cloud-vm-management.mdx

@@ -0,0 +1,240 @@
+---
+title: Cloud VM Management
+description: Manage your Cua Cloud sandboxes (VMs) via Python SDK or HTTP API
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+Use these concise examples to manage your cloud sandboxes. Pick either the Python SDK or plain HTTP (curl) for each action.
+
+> You need a CUA Database API key. Set it as an environment variable `CUA_API_KEY`.
+
+## Status values
+- `pending` – VM deployment in progress
+- `running` – VM is active and accessible
+- `stopped` – VM is stopped but not terminated
+- `terminated` – VM has been permanently destroyed
+- `failed` – VM deployment or operation failed
+
+---
+
+## List VMs
+
+<Tabs items={["Python", "curl"]}>
+  <Tab value="Python">
+
+  ```python
+  import os
+  import asyncio
+  from computer.providers.cloud.provider import CloudProvider
+
+  async def main():
+      api_key = os.getenv("CUA_API_KEY") or "your-api-key"
+      # Optional: point to a different API base
+      # os.environ["CUA_API_BASE"] = "https://api.cua.ai"
+
+      provider = CloudProvider(api_key=api_key, 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"
+  ```
+
+  Example response:
+  ```json
+  [
+    {
+      "name": "s-windows-x4snp46ebf",
+      "status": "running"
+    }
+  ]
+  ```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Start a VM
+Provide the VM name you want to start.
+
+<Tabs items={["Python", "curl"]}>
+  <Tab value="Python">
+
+  ```python
+  import os
+  import asyncio
+  from computer.providers.cloud.provider import CloudProvider
+
+  async def main():
+      api_key = os.getenv("CUA_API_KEY") or "your-api-key"
+      name = "my-vm-name"  # e.g., "m-linux-96lcxd2c2k"
+
+      provider = CloudProvider(api_key=api_key)
+      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
+  ```
+
+  Example response headers (no body):
+  ```text
+  HTTP/1.1 204 No Content
+  ```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Stop a VM
+Stops the VM asynchronously.
+
+<Tabs items={["Python", "curl"]}>
+  <Tab value="Python">
+
+  ```python
+  import os
+  import asyncio
+  from computer.providers.cloud.provider import CloudProvider
+
+  async def main():
+      api_key = os.getenv("CUA_API_KEY") or "your-api-key"
+      name = "my-vm-name"
+
+      provider = CloudProvider(api_key=api_key)
+      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"
+  ```
+
+  Example response:
+  ```json
+  { "status": "stopping" }
+  ```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Restart a VM
+Restarts the VM asynchronously.
+
+<Tabs items={["Python", "curl"]}>
+  <Tab value="Python">
+
+  ```python
+  import os
+  import asyncio
+  from computer.providers.cloud.provider import CloudProvider
+
+  async def main():
+      api_key = os.getenv("CUA_API_KEY") or "your-api-key"
+      name = "my-vm-name"
+
+      provider = CloudProvider(api_key=api_key)
+      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"
+  ```
+
+  Example response:
+  ```json
+  { "status": "restarting" }
+  ```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Query a VM by name
+Query the computer-server running on the VM. Useful for checking details like status or OS type.
+
+<Tabs items={["Python", "curl"]}>
+  <Tab value="Python">
+
+  ```python
+  import os
+  import asyncio
+  from computer.providers.cloud.provider import CloudProvider
+
+  async def main():
+      api_key = os.getenv("CUA_API_KEY") or "your-api-key"
+      name = "my-vm-name"
+
+      provider = CloudProvider(api_key=api_key)
+      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"
+  ```
+
+  Example response:
+  ```json
+  { "status": "ok", "os_type": "linux", "features": ["agent"] }
+  ```
+
+  </Tab>
+</Tabs>

docs/content/docs/computer-sdk/meta.json

@@ -3,6 +3,7 @@
 	"description": "Build computer-using agents with the Computer SDK",
 	"pages": [
         "computers",
+        "cloud-vm-management",
         "commands",
         "computer-ui",
         "sandboxed-python"

examples/cloud_api_examples.py

@@ -0,0 +1,70 @@
+import asyncio
+import os
+from utils import load_dotenv_files
+
+load_dotenv_files()
+
+from computer.providers.cloud.provider import CloudProvider
+
+async def main() -> None:
+    api_key = os.getenv("CUA_API_KEY")
+    if not api_key:
+        raise RuntimeError("CUA_API_KEY environment variable is not set")
+    api_base = os.getenv("CUA_API_BASE")
+    if api_base:
+        print(f"Using API base: {api_base}")
+
+    provider = CloudProvider(api_key=api_key, verbose=True)
+    async with provider:
+
+        # List all VMs
+        vms = await provider.list_vms()
+        print(f"Found {len(vms)} VM(s)")
+        for vm in vms:
+            print(
+                f"name: {vm['name']}\n",
+                f"status: {vm['status']}\n", # pending, running, stopped, terminated, failed
+                f"api_url: {vm.get('api_url')}\n",
+                f"vnc_url: {vm.get('vnc_url')}\n",
+            )
+
+        # # --- Additional operations (commented out) ---
+        # # To stop a VM by name:
+        # name = "m-linux-96lcxd2c2k"
+        # resp = await provider.stop_vm(name)
+        # print(
+        #     "stop_vm response:\n",
+        #     f"name: {resp['name']}\n",
+        #     f"status: {resp['status']}\n", # stopping
+        # )
+
+        # # To start a VM by name:
+        # name = "m-linux-96lcxd2c2k"
+        # resp = await provider.run_vm(name)
+        # print(
+        #     "run_vm response:\n",
+        #     f"name: {resp['name']}\n",
+        #     f"status: {resp['status']}\n", # starting
+        # )
+
+        # # To restart a VM by name:
+        # name = "m-linux-96lcxd2c2k"
+        # resp = await provider.restart_vm(name)
+        # print(
+        #     "restart_vm response:\n",
+        #     f"name: {resp['name']}\n",
+        #     f"status: {resp['status']}\n", # restarting
+        # )
+
+        # # To probe a VM's status via its public hostname (if you know the name):
+        # name = "m-linux-96lcxd2c2k"
+        # info = await provider.get_vm(name)
+        # print("get_vm info:\n", 
+        #     f"name: {info['name']}\n",
+        #     f"status: {info['status']}\n", # running
+        #     f"api_url: {info.get('api_url')}\n",
+        #     f"os_type: {info.get('os_type')}\n",
+        # )
+
+if __name__ == "__main__":
+    asyncio.run(main())