CubeLabs

1. Qué es un agente computer-use

Un agente computer-use no se limita a llamar APIs: mira una pantalla, decide dónde pulsar y escribe como lo haría una persona. Cua es la infraestructura que hace eso posible de forma segura y reproducible, en lugar de dejar al modelo suelto sobre tu escritorio.

La idea central del proyecto es Computer-Use 2.0: un agente moviéndose entre código, APIs e interfaces gráficas dentro de la misma tarea. Cuando existe una API, la usa; cuando no, opera la interfaz. Esa mezcla es lo que convierte a un asistente en algo capaz de completar trabajo real.

2. El stack de Cua: seis piezas

Cua no es una sola herramienta, sino un conjunto coordinado. Reconocer cada pieza te evita instalar de más y ayuda a elegir la capa correcta para tu caso.

La arquitectura de una ejecución típica es siempre la misma:

modelo -> harness del agente -> Cua Driver (MCP, CLI o SDK)
       -> accesibilidad + entrada del SO -> aplicaciones

3. Instalación paso a paso

El instalador de Cua muestra una checklist y añade el CLI, el MCP de Cua Driver y las instrucciones de agente que correspondan. No necesitas permisos de administrador para el driver.

# macOS / Linux
curl -fsSL https://cua.ai/install.sh | sh

# Windows (PowerShell)
irm https://cua.ai/install.ps1 | iex

# Comprobar host y runtime
cua runtime doctor
cua runtime setup
cua --version

4. Tu primer sandbox con el SDK

Un sandbox es una máquina aislada y efímera donde tu agente ejecuta comandos, abre servicios y controla un escritorio. El SDK de Python expone una API asíncrona muy directa: Sandbox.ephemeral crea, arranca y destruye el entorno al salir del bloque.

pip install cua-sandbox

import asyncio
from cua_sandbox import Image, Sandbox, http

async def main():
    async with Sandbox.ephemeral(
        Image.from_registry("python:3.12-slim"),
        command=["python", "-m", "http.server", "8000"],
        services={"web": 8000},
        wait_for=http("web", "/"),
    ) as sb:
        print((await sb.service("web").request("GET", "/")).status_code)
        print(await sb.service("web").url())

asyncio.run(main())

El mismo arranque desde la CLI, útil para depurar sin escribir código:

$ cua sb create python:3.12-slim --name web \
    --service web=8000 --wait http:web/ \
    -- python -m http.server 8000
$ cua sb url web web
200
http://127.0.0.1:53817

5. Cua Driver: controlar apps reales

Cua Driver es la capa que convierte instrucciones en acciones concretas sobre aplicaciones de escritorio. Su tutorial canónico es contundente: pedir al agente que abra la calculadora, compute 6 × 7 y lea el resultado (42) desde una captura nueva.

# macOS: instala y arranca el daemon
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
open -n -g -a CuaDriver --args serve
cua-driver permissions grant

# Linux
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
cua-driver serve

Con el daemon en marcha, comprueba que ve tus aplicaciones:

$ cua-driver call list_apps

Una lista vacía significa que el driver no llega al escritorio: ejecuta cua-driver doctor. Después conecta tu agente e indica:

Usando Cua Driver, abre la calculadora, calcula 6 × 7
y lee el resultado desde una captura nueva.

La limpieza es explícita: cua-driver stop detiene el daemon cuando terminas.

6. Cómo funciona por dentro: observar y actuar

El driver sigue un ciclo observar → actuar → verificar. La herramienta get_window_state(pid, window_id) devuelve en una sola llamada el árbol de accesibilidad (roles, etiquetas y un element_token por elemento) y una captura. El árbol dice qué es accionable; la imagen dice cuál y muestra lo que el árbol omite.

Cada acción apunta a un destino explícito y sigue una escalera de precisión:

1. Elemento, en segundo plano: actúa por element_token (la única ruta que el driver puede verificar por sí mismo).
2. Píxel, en segundo plano: actúa por coordenadas leídas de la misma captura.
3. Página: en pestañas de navegador, usa las herramientas de navegador (DOM por CDP, sin robar el foco).
4. Primer plano: reintenta solo esa acción con delivery_mode: "foreground" (juegos, canvas, apps que exigen foco).

7. Conectar tu agente por MCP

Un agente llega a Cua Driver de dos formas: un cliente MCP lanza cua-driver mcp, o una skill enseña a un agente con shell a ejecutar cua-driver call <tool>. En ambos casos el harness conserva el modelo y el bucle.

# Imprime el comando o JSON exacto para tu cliente
cua-driver mcp-config --client <cliente>

# Instala la skill de agente (y comprueba)
cua-driver skills install
cua-driver skills status

Para cualquier otro cliente MCP estándar basta con esta configuración:

{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": ["mcp"]
    }
  }
}

8. Lume: VMs macOS y Linux locales

Lume crea y gestiona VMs de macOS y Linux sobre Apple Silicon usando el Virtualization.Framework de Apple. Es la base para dar a un agente un macOS completo y aislado sin tocar tu máquina.

/bin/bash -c "$(curl -fsSL https://cua.ai/lume/install.sh)"
lume --version

# macOS Tahoe desde la imagen de restauración más reciente
lume create macos-tahoe --ipsw latest --unattended tahoe
lume run macos-tahoe

# Conectar por SSH
lume ssh macos-tahoe 'sw_vers; id -un'

El preset tahoe prepara el invitado sin conexión a red externa: usuario lume con contraseña lume, SSH activado y autologin.

El proyecto incluye lumier, una interfaz compatible con Docker para las VMs de Lume, y cua sb create macos para lanzar un sandbox macOS desde la CLI.

9. Imágenes y despliegue: local, cloud y tu nube

Cua publica imágenes canónicas para Linux, Windows, macOS y Omarchy. Cada una se ofrece como contenedor (rápido, con gVisor si está instalado) o como VM (más fiel al escritorio real). El mismo código escala de tu portátil a la nube.

Puedes ejecutar los mismos sandboxes en la nube de Cua o en tu propia cuenta:

# Tu propia nube
cua sb create --on aws ...
cua sb create --on gcp ...
cua sb create --on modal ...

10. Cua Bench y buenas prácticas

Para saber si un agente de computer-use mejora de verdad, hay que medirlo. Cua Bench crea tareas, las puntúa con un oráculo y exporta trayectorias para entrenamiento. El arranque no necesita clave de API ni VM.

uv tool install 'cua-bench[browser]'
uv tool run --from 'cua-bench[browser]' playwright install chromium

# Listar y ejecutar una tarea del registro con su oráculo
cb dataset list
cb run cua-bench-basic --task-filter click-button --max-variants 1

# Resolverla tú mismo, o pasársela a un agente
cb interact click-button --dataset cua-bench-basic
cb run cua-bench-basic --agent cua-agent \
  --model anthropic/claude-sonnet-4-20250514 -j 4

Cada variante deja result.json, run.log y trajectory.json en ~/.local/share/cua-bench/runs/. El registro incluye benchmarks conocidos como OSWorld-Verified (369 tareas de escritorio Ubuntu) y WebVoyager (643 sitios en vivo).

Buenas prácticas para no quemar contexto ni permisos

• Acota la observación: limita get_window_state con max_elements y max_depth.
• Reutiliza pid y window_id entre llamadas en vez de reindexar cada vez.
• Agrupa el texto en una sola llamada a type_text.
• Permisos de mínimo privilegio: el lanzador fija el modo y los grants al arrancar; un agente no puede ampliarlos.
• Verifica siempre: un ok no es evidencia; vuelve a observar tras cada acción.