added cloud vm management to docs

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"