openclaw/crabbox

¿Qué hace crabbox?

Usa Crabbox cuando un proyecto necesite una verificación remota, mayor capacidad en la nube, un checkout fresco de un PR, un entorno precalentado reutilizable, una configuración tipo GitHub Actions, registros/resultados de ejecución duraderos, artefactos de prueba de interfaz de usuario, o sincronización desde un checkout local sucio.

Detectar Crabbox

• Trata crabbox.yaml o .crabbox.yaml en la raíz del repositorio como una señal intencionada para usar este skill en trabajos de validación. .crabbox.yml no es un nombre de archivo de configuración soportado.
• Si no existe ninguno de estos archivos, command -v crabbox aún identifica si el CLI está instalado. Ejecuta crabbox doctor antes de depender de él para trabajo remoto.
• Inspecciona la configuración antes de ejecutarla. La detección no implica permiso para exponer secretos, eludir la aprobación de comandos o iniciar infraestructura de pago.

Fuente de Verdad

• Ejecuta Crabbox desde la raíz del repositorio; la sincronización refleja el checkout actual.
• Trata crabbox.yaml o .crabbox.yaml local del repositorio como automatización de proyecto ejecutable. Revísalo antes de ejecuciones remotas, especialmente provider, actions, jobs, profiles, env.allow, artefactos y la política de limpieza.
• Verifica el binario instalado antes de confiar en los ejemplos: command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'.
• Usa crabbox providers o crabbox providers --json para la matriz actual de proveedores/capacidades; la documentación del proveedor puede estar desactualizada respecto al binario compilado.
• Usa crabbox doctor para comprobaciones de disponibilidad en vivo y crabbox config show para inspeccionar la configuración combinada sin mostrar secretos.
• Prefiere pruebas locales específicas para ciclos de edición rápidos. Recurre a Crabbox para suites amplias, comprobaciones con muchos paquetes, pruebas Docker/E2E/proveedor en vivo, pruebas multiplataforma, pruebas de interfaz de usuario, o comandos que ralenticen la máquina local.

Autenticación y Configuración

La operación intermediada necesita una URL de coordinador y un token. El primer inicio de sesión normalmente necesita una URL de intermediario explícita:

crabbox login --url <broker-url>
crabbox whoami
crabbox doctor

Después de que broker.url esté configurado, crabbox login puede reutilizarlo. La automatización de operadores de confianza puede almacenar un token compartido sin ponerlo en argv:

printf '%s' "$CRABBOX_COORDINATOR_TOKEN" |
  crabbox login --url <broker-url> --provider aws --token-stdin

La precedencia de configuración es flags > env > config del repo > config del usuario > valores por defecto. La configuración de usuario por defecto es ~/Library/Application Support/crabbox/config.yaml en macOS, ~/.config/crabbox/config.yaml en Linux, o $XDG_CONFIG_HOME/crabbox/config.yaml cuando está definida. crabbox config path imprime la ruta activa de configuración de usuario.

Mantén los tokens de proveedores e intermediarios fuera de la configuración del repositorio y los argumentos de los comandos. Usa variables de entorno, un almacén de credenciales, secretos gestionados por el coordinador, o un comando de token de corta duración.

Elegir la Superficie Remota

• crabbox run -- <comando>: un comando en un entorno nuevo o reutilizado.
• crabbox warmup: crea una concesión reutilizable y ejecuta comandos más tarde con --id.
• crabbox prewarm: calienta una concesión reutilizable y la hidrata desde GitHub Actions configurado.
• crabbox job run <nombre>: usa un flujo nombrado local del repositorio que se expande a warmup, hidratación opcional, ejecución y parada.
• crabbox run --pool <clave>: toma prestada una concesión de un pool listo hidratado por el coordinador, ejecuta, luego devuelve/vacía/libera según --pool-return.
• crabbox run --fresh-pr ...: ignora la sincronización local y descarga un PR de GitHub en el remoto; añade --apply-local-patch para probar cambios locales no confirmados sobre ese PR.
• crabbox run --provider ssh: usa un host macOS, Linux o Windows existente.
• crabbox warmup --desktop --browser: aprovisiona un escritorio/navegador visible para pruebas de UI, WebVNC, capturas de pantalla y artefactos.

Si la verificación remota está bloqueada, nombra la capacidad faltante con precisión: autenticación, coordinador, capacidad, soporte de proveedor, SO objetivo, hidratación, acceso a secretos, almacenamiento de artefactos, soporte de escritorio, o una limitación del proveedor delegado.

Verificación Remota Común

Comando único:

crabbox run --preflight --timing-json -- pnpm test

Calentar y reutilizar una concesión:

crabbox warmup --class beast --idle-timeout 90m
crabbox status --id <cbx_id-o-slug> --wait
crabbox run --id <cbx_id-o-slug> -- pnpm test:changed
crabbox run --id <cbx_id-o-slug> --full-resync -- pnpm test:changed
crabbox stop <cbx_id-o-slug>

Usar un job local del repositorio cuando esté configurado:

crabbox job list
crabbox job run --dry-run <job-name>
crabbox job run <job-name>
crabbox job run --id <cbx_id-o-slug> <job-name>

Usar una concesión de pool listo cuando el coordinador tenga capacidad de pool hidratado:

crabbox pool ready
crabbox run --pool <pool-key> -- pnpm test
crabbox run --pool <pool-key> --pool-return drain -- pnpm test:flaky

Usar hidratación de GitHub Actions cuando el repositorio ya tenga la configuración en CI:

crabbox warmup --idle-timeout 90m
crabbox actions hydrate --id <cbx_id-o-slug>
crabbox run --id <cbx_id-o-slug> -- pnpm test

Usa --github-runner solo cuando el workflow necesite todas las semánticas de GitHub Actions, como secretos del repositorio, OIDC, contenedores de servicio, contenedores de trabajo, o pasos uses: no soportados:

crabbox actions hydrate --github-runner --id <cbx_id-o-slug>

Sincronización y Checkouts Frescos

La sincronización normal transfiere archivos rastreados más archivos no rastreados y no ignorados, excluye la salida de dependencias/compilación/caché ignorada, respeta .crabboxignore y sync.exclude, siembra el checkout remoto desde origin cuando es posible, y omite rsync cuando la huella de sincronización coincide.

Usa crabbox sync-plan antes de ejecuciones grandes. Recuentos inesperados normalmente significan cambios locales generados; actualiza .crabboxignore o sync.exclude en lugar de forzar grandes subidas.

crabbox sync-plan
crabbox run --debug --timing-json -- pnpm test
crabbox run --full-resync -- pnpm test

Usa checkout fresco de PR cuando el cambio local de dependencias o una sincronización sucia pueda confundir el resultado:

crabbox run --fresh-pr example-org/my-app#123 --script ./scripts/e2e-smoke.sh
crabbox run --fresh-pr 123 --apply-local-patch -- pnpm test

--fresh-pr acepta owner/repo#number, URLs de PR de GitHub, o un número de PR del origin de GitHub actual. Los hosts que no son de GitHub son rechazados. El checkout fresco de PR es una característica de sincronización por SSH; los proveedores delegados lo rechazan. Los destinos SSH nativos de Windows son compatibles.

Cuando una concesión caliente huele a estancada, prefiere --full-resync (alias --fresh-sync) para restablecer el directorio de trabajo remoto, omitir la ruta rápida de la huella de sincronización, resembrar Git cuando sea posible, y subir el checkout desde cero.

Scripts, Shells y Destinos Windows

Usa argv plano después de -- para un solo ejecutable. Usa --shell para fragmentos de shell de múltiples sentencias, tuberías o expansión de shell:

crabbox run --id <lease> -- go test ./...
crabbox run --id <lease> --shell 'corepack enable && pnpm install --frozen-lockfile && pnpm test'

Prefiere scripts subidos para comandos de múltiples líneas. Los scripts se incluyen en los paquetes de fallo y evitan cadenas de shell frágiles entre comillas:

crabbox run --script ./scripts/e2e-smoke.sh --timing-json
printf '%s\n' 'echo CRABBOX_PHASE:test' 'pnpm test' | crabbox run --script-stdin

Los destinos nativos de Windows usan PowerShell y sincronización de manifiesto basada en tar. Prefiere argv plano para un solo ejecutable como dotnet test; usa --shell para PowerShell de múltiples sentencias y --script <file.ps1> para scripts más largos.

Concesiones Windows Hyper-V

hyperv necesita un VHDX de Generación 2, DHCP y una contraseña de administrador local conocida en la configuración de confianza o CRABBOX_HYPERV_GUEST_PASSWORD. Instala paquetes OpenSSH y MinGit fijados y verificados cuando faltan, usando PowerShell Direct. Consulta docs/providers/hyperv.md para la plantilla y los detalles del ciclo de vida.

Para pruebas de proveedor, prefiere un ejecutor sin cabeza elevado; los fallos tempranos de PowerShell Direct pueden mostrar la UI de credenciales. Mantén las contraseñas fuera de los argumentos y registros, y verifica que la concesión se vuelva lista, se ejecute a través de SSH y se libere.

Secretos y Reenvío de Entorno

Crabbox no reenvía todo el entorno local. El reenvío se basa en nombres: solo los nombres en la lista blanca que están realmente establecidos localmente o en un perfil permitido cruzan el límite. Evita poner en la lista blanca nombres con forma de secreto a menos que la ejecución sea una prueba explícita de secreto en vivo.

crabbox run --allow-env CI,NODE_OPTIONS -- pnpm test
crabbox run \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --preflight \
  --script ./scripts/live-smoke.sh

--env-from-profile analiza líneas simples export NOMBRE=valor y NOMBRE=valor sin ejecutar el perfil. Crabbox imprime metadatos de presencia/longitud redactados, no valores. Las concesiones POSIX SSH pueden persistir un helper para comandos posteriores en una concesión que controlas:

crabbox run \
  --id <lease> \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --env-helper live \
  -- true
crabbox run --id <lease> -- ./.crabbox/env/live ./scripts/live-smoke.sh

El helper generado y el perfil de secreto correspondiente permanecen en el directorio de trabajo remoto hasta la limpieza, el restablecimiento de la concesión o --full-resync; no persistas helpers en concesiones compartidas o no confiables.

Perfiles, Preajustes, Verificación y Resultados

La configuración del repositorio puede definir perfiles, preajustes, requisitos de doctor, globos de artefactos, artefactos requeridos y plantillas de verificación. Úsalos para carriles de validación estables en lugar de codificar el conocimiento del proyecto en prompts de agente.

crabbox run \
  --profile live-qa \
  --preset qa-live \
  --scenario login-regression \
  --emit-proof /tmp/proof.md \
  --stop-after success

Usa --preflight para una instantánea de capacidad objetivo antes del comando, no como un instalador. Usa --preflight-tools para ajustar las sondas:

crabbox run --preflight --preflight-tools node,bun,docker -- bun test
crabbox run --preflight --preflight-tools default,uv -- node --test

Adjunta resultados estructurados y artefactos de verificación cuando el comando los emita:

crabbox run --junit reports/junit.xml -- ./scripts/test-with-junit.sh
crabbox run --artifact-glob 'reports/**' --require-artifact reports/summary.json -- pnpm test:e2e
crabbox run --download reports/summary.json=.crabbox/logs/summary.json -- pnpm test:e2e

--require-artifact falla la ejecución si el comando remoto sale con 0 pero el archivo de verificación falta. Mantén los artefactos requeridos acotados y depurados; no recojas conjuntos de datos brutos, secretos, credenciales, URLs firmadas o filas de clientes sin redactar.

Identificadores de Ejecución y Observabilidad

Las ejecuciones respaldadas por el coordinador imprimen un identificador duradero run_... antes de que comience la concesión. Mantén ese ID de ejecución en las actualizaciones de estado y notas de PR.

crabbox history --limit 20
crabbox history --lease <cbx_id-o-slug> --limit 20
crabbox attach <run_id>
crabbox attach <run_id> --after <seq>
crabbox events <run_id> --after <seq> --limit 100
crabbox events <run_id> --json
crabbox logs <run_id>
crabbox results <run_id>

Usa --timing-json en run, warmup y actions hydrate cuando se necesite un registro de tiempo estable y legible por máquina. Los comandos pueden marcar subfases imprimiendo marcadores en stdout o stderr:

echo CRABBOX_PHASE:install
pnpm install --frozen-lockfile
echo CRABBOX_PHASE:test
pnpm test

Los eventos de salida son vistas previas limitadas. Usa logs para las colas de salida retenidas y results para resúmenes de pruebas analizadas.

Escritorio, WebVNC y Verificación de UI

Crea concesiones de escritorio/navegador para QA visual, automatización de navegador con cabeza, o verificación de UI:

crabbox warmup --desktop --browser
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env wayland
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env gnome

ubuntu:26.04 es el selector de SO Linux portátil por defecto donde el catálogo del proveedor lo soporta. Usa --os ubuntu:24.04 solo cuando una prueba deba permanecer en la LTS anterior. Las banderas explícitas de imagen de proveedor siguen ganando a --os.

Para demostraciones humanas, prefiere WebVNC sobre VNC nativo porque crabbox webvnc --open precarga la contraseña de la concesión en el fragmento del navegador:

crabbox webvnc --id <lease> --open --take-control
crabbox webvnc status --id <lease>
crabbox webvnc reset --id <lease> --open --take-control
crabbox vnc --id <lease> --open

Para automatización de entrada, usa asistentes de primera clase en lugar de xdotool escrito a mano:

crabbox desktop doctor --id <lease>
crabbox desktop launch --id <lease> --browser --url https://example.com --webvnc --open --take-control
crabbox desktop click --id <lease> --x 640 --y 420
crabbox desktop paste --id <lease> --text "[email protected]"
printf '[email protected]' | crabbox desktop paste --id <lease>
crabbox desktop type --id <lease> --text "[email protected]"
crabbox desktop key --id <lease> ctrl+l
crabbox screenshot --id <lease> --output desktop.png

Cuando el escritorio/WebVNC se cuelgue, confía primero en la salida de rescate en línea: las líneas problem: y rescue: normalmente nombran los siguientes comandos exactos como webvnc status/reset, desktop doctor, o vnc --open nativo.

Usa artefactos para la verificación de UI en lugar de confirmar capturas de pantalla o videos en una rama del repositorio del producto:

crabbox artifacts collect --id <lease> --all --output artifacts/<slug>
crabbox artifacts publish --dir artifacts/<slug> --pr <number>
crabbox artifacts list <artifact-manifest-url-o-dir>
crabbox artifacts pull <artifact-manifest-url-o-dir> --output /tmp/<slug>-proof

artifacts publish usa almacenamiento intermediado cuando está configurado, o banderas explícitas de alojamiento S3/R2 / Cloudflare/local. Usa --dry-run antes de comentarios públicos en PR al revisar Markdown generado o comandos de almacenamiento.

Límites del Proveedor

Los proveedores de concesión SSH soportan toda la superficie de sincronización/ejecución cuando el destino lo soporta: scripts, checkouts frescos de PR, capturas, descargas, hidratación de Actions, SSH, puertos, WebVNC, code-server, escritorio, navegador, volúmenes de caché y limpieza.

Los proveedores de ejecución delegada poseen el transporte de comandos. Se espera que rechacen características de ejecución SSH como --capture-stdout, --capture-stderr, --capture-on-fail, --script, --script-stdin, --fresh-pr, capturas locales, --download, --full-resync y --env-helper a menos que crabbox providers --json y la documentación del proveedor anuncien la capacidad correspondiente. --keep-on-failure sigue siendo útil para proveedores delegados de un solo uso que Crabbox detendría de otro modo después de un comando fallido.

Los proveedores delegados de tiempo de ejecución de módulo, que ejecutan el comando en un contenedor o microVM, no exponen un shell SSH completo. Usa crabbox run --script en su lugar, que serializa el script en el manifiesto del módulo. La mayoría de los flags --capture-* funcionan; --fresh-pr no. Las funciones de escritorio no están disponibles. Los artefactos se transfieren al final de la ejecución a través del plano de control; no hay sincronización inversa dinámica ni reenvío de puertos del módulo.