Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs: add run.cua.ai fleet Terraform guide (#2567)
r33drichards1bb489089160
diff --git a/docs/content/docs/how-to-guides/configure-run-cua-fleets.mdx b/docs/content/docs/how-to-guides/configure-run-cua-fleets.mdxnew file mode 100644index 0000000000..1c34b9c746--- /dev/null+++ b/docs/content/docs/how-to-guides/configure-run-cua-fleets.mdx@@ -0,0 +1,190 @@+---+title: Configure run.cua.ai fleets with Terraform+description: Create Linux and Windows run.cua.ai fleets with the temporary local Cua Fleets provider installation.+---++Use this guide to create a run.cua.ai fleet backed by the public Cua Fleets+provider. Terraform represents each fleet as a `fleets_pool` resource.++## Prerequisites++- A run.cua.ai user key or access token with permission to manage Fleet pools.+ Keep credentials in environment variables or a secret manager, not in source+ control.+- Terraform or OpenTofu and Go on the machine where you build the provider.+- The temporary local provider installation from the public+ [terraform-provider-fleets README](https://github.com/trycua/terraform-provider-fleets#temporary-local-installation-until-registry-publication).++The provider is not published to the Terraform Registry yet. Follow the public+README to clone `https://github.com/trycua/terraform-provider-fleets.git`, build+for your current OS and architecture, and configure its filesystem mirror. That+flow installs a local binary; it is not Registry resolution. Replace this+temporary setup with the normal Registry installation after `trycua/fleets` is+published.++The provider source address remains `trycua/fleets`; do not use a GitHub URL in+`required_providers.source`. Set the CLI configuration file created by the+public README before initializing either example:++```bash+export TF_CLI_CONFIG_FILE="$HOME/.terraformrc-fleets-local"+```++For OpenTofu, run the same commands with `tofu` in place of `terraform`.++## Authentication++The provider accepts either `CYCLOPS_ACCESS_TOKEN`, or all three OAuth user-key+variables: `CYCLOPS_CLIENT_ID`, `CYCLOPS_CLIENT_SECRET`, and+`CYCLOPS_TOKEN_URL`. Configure the run.cua.ai endpoint separately:++```bash+export CYCLOPS_ENDPOINT="https://run.cua.ai"+export CYCLOPS_ACCESS_TOKEN="<your-access-token>"+```++## Create a Linux fleet++Create a new directory, save this as `main.tf`, and choose a unique lowercase+DNS-label pool name. This example creates a KubeVirt Linux pool and exposes SSH.++```hcl title="main.tf"+terraform {+ required_providers {+ fleets = {+ source = "trycua/fleets"+ version = "1.0.0"+ }+ }+}++provider "fleets" {+ endpoint = "https://run.cua.ai"+}++resource "fleets_pool" "linux" {+ name = "linux-fleet"+ replicas = 0+ cpu_cores = 4+ memory = "8Gi"+ container_disk_image = "296062593712.dkr.ecr.us-west-2.amazonaws.com/desktop-workspace-duo:main-38352d34"+ runtime = "kubevirt"+ firmware = "bios"++ service {+ name = "ssh"+ target_port = 22+ protocol = "TCP"+ }++ autoscaling {+ min_pool_size = 0+ initial_pool_size = 1+ max_pool_size = 5+ }+}++output "linux_fleet" {+ value = {+ name = fleets_pool.linux.name+ namespace = fleets_pool.linux.namespace+ phase = fleets_pool.linux.phase+ }+}+```++## Create a Windows fleet++Use a distinct name for Windows. The Windows computer-server image requires+UEFI, so this example sets `firmware = "efi"` and waits for the service on port+`8000`.++```hcl title="main.tf"+terraform {+ required_providers {+ fleets = {+ source = "trycua/fleets"+ version = "1.0.0"+ }+ }+}++provider "fleets" {+ endpoint = "https://run.cua.ai"+}++resource "fleets_pool" "windows" {+ name = "windows-fleet"+ replicas = 0+ cpu_cores = 4+ memory = "4Gi"+ container_disk_image = "296062593712.dkr.ecr.us-west-2.amazonaws.com/cua-server-windows:latest"+ runtime = "kubevirt"+ firmware = "efi"++ readiness_probe_json = jsonencode({+ tcpSocket = { port = 8000 }+ initialDelaySeconds = 60+ periodSeconds = 5+ timeoutSeconds = 3+ failureThreshold = 120+ })++ service {+ name = "computer-server"+ target_port = 8000+ protocol = "TCP"+ }++ autoscaling {+ min_pool_size = 0+ initial_pool_size = 1+ max_pool_size = 5+ }+}++output "windows_fleet" {+ value = {+ name = fleets_pool.windows.name+ namespace = fleets_pool.windows.namespace+ phase = fleets_pool.windows.phase+ }+}+```++## Apply, verify, and destroy++With `TF_CLI_CONFIG_FILE` still set, initialize from the local mirror and run+one example:++```bash+rm -rf .terraform .terraform.lock.hcl+terraform init+terraform fmt -check+terraform validate+terraform plan+terraform apply+terraform output+```++`terraform init` uses the locally built provider and must not resolve+`trycua/fleets` from the public Registry. The provider returns `namespace`,+`phase`, `total_count`, `available_count`, and `claimed_count`. A ready fleet+has available sandboxes after its warm pool provisions.++Destroy the pool when finished. This deletes both the pool and its same-named+namespace:++```bash+terraform destroy+```++## Troubleshooting and security++- Use a lowercase DNS label of at most 63 characters for `name`. Changing it+ replaces the pool because it also owns its namespace.+- Check the image reference and image-pull-secret policy if creation returns+ `403`. `image_pull_secret` defaults to `ecr-credentials`.+- Use `bios` for the Linux workspace image and `efi` for the Windows+ computer-server image. A firmware mismatch prevents the guest from booting.+- Protect Terraform state and shell history as operational secrets.diff --git a/docs/content/docs/how-to-guides/meta.json b/docs/content/docs/how-to-guides/meta.jsonindex fc104ae3e5..8c909405a7 100644--- a/docs/content/docs/how-to-guides/meta.json+++ b/docs/content/docs/how-to-guides/meta.json@@ -5,6 +5,7 @@"index","driver","sandbox",+ "configure-run-cua-fleets","lume","cua-bench","recipes",