Resolución de problemas

Ejecutar diagnósticos

Antes de investigar un problema específico, ejecuta sbx diagnose para verificar si hay problemas comunes con tu instalación, como la falta del binario de la CLI, un demonio que no responde, una discrepancia de versiones entre la CLI y el demonio, la falta de directorios de almacenamiento o una autenticación rota.

$ sbx diagnose

El comando imprime un resumen de las comprobaciones que se aprobaron, las que generaron advertencias o las que fallaron, junto con las soluciones sugeridas. Usa --output json para obtener una salida legible por máquina, o --output github-issue para generar un fragmento de Markdown adecuado para pegar en un problema de GitHub.

Restablecer los sandboxes

Si encuentras problemas persistentes o un estado dañado, ejecuta sbx reset para detener todas las VMs y eliminar todos los datos de los sandboxes. Crea sandboxes nuevos después de esto.

El agente no puede instalar paquetes o acceder a una API

Los sandboxes utilizan una política de red de denegar por defecto. Si el agente no puede instalar paquetes o llamar a una API externa, es probable que el dominio de destino no esté en la lista de permitidos. Comprueba qué solicitudes se están bloqueando:

$ sbx policy log

Luego, permite los dominios que requiere tu flujo de trabajo:

$ sbx policy allow network -g "*.npmjs.org,*.pypi.org,files.pythonhosted.org"

Para permitir todo el tráfico saliente en su lugar:

$ sbx policy allow network -g "**"

Si sbx policy allow no desbloquea la solicitud, es posible que tu organización gestione las políticas de los sandboxes de forma centralizada, las cuales tienen prioridad sobre las reglas locales. Consulta Gobernanza de la organización.

Las conexiones SSH y otras conexiones que no son HTTP fallan

Las conexiones TCP que no son HTTP, como SSH, se pueden permitir añadiendo una regla de política para la dirección IP y el puerto de destino. Por ejemplo, para permitir SSH a un host específico:

$ sbx policy allow network -g "10.1.2.3:22"

Las reglas basadas en nombres de host (por ejemplo, myhost:22) no funcionan para conexiones que no son HTTP porque el proxy no puede resolver el nombre de host a una dirección IP en este contexto. Usa la dirección IP directamente.

El tráfico UDP e ICMP se bloquea en la capa de red y no se puede desbloquear con reglas de política.

Para operaciones de Git a través de SSH, puedes añadir una regla de permiso para la dirección IP del servidor Git o usar URLs de HTTPS en su lugar:

$ git clone https://github.com/owner/repo.git

No se puede acceder a un servicio que se ejecuta en el host

Si una solicitud a 127.0.0.1 o a una IP de red local devuelve "conexión rechazada" desde dentro de un sandbox, significa que la dirección no es accesible desde el interior de la VM del sandbox. Consulta Acceso a servicios del host desde un sandbox.

Fallo de autenticación de Docker

Si ves un mensaje como You are not authenticated to Docker, tu sesión de inicio de sesión ha expirado. En una terminal interactiva, la CLI te pedirá que inicies sesión nuevamente. En entornos no interactivos, como scripts o CI, ejecuta sbx login para volver a autenticarte.

Fallo de autenticación del agente

Si el agente no puede comunicarse con su proveedor de modelos o ves errores de clave de API, es probable que la clave sea inválida, haya expirado o no esté configurada. Verifica que esté configurada en tu archivo de configuración de shell y que hayas cargado dicha configuración o abierto una nueva terminal.

Para los agentes que utilizan el proxy de credenciales, asegúrate de no haber configurado la clave de API con un valor inválido dentro del sandbox; el proxy inyecta las credenciales automáticamente en las solicitudes salientes.

Si las credenciales están configuradas correctamente pero las llamadas a la API siguen fallando, verifica sbx policy log y observa la columna PROXY. Las solicitudes enrutadas a través del proxy transparent no reciben inyección de credenciales. Esto puede ocurrir cuando un cliente dentro del sandbox (como un proceso en un contenedor Docker) no está configurado para usar el proxy de reenvío. Consulta Supervisión de la actividad de red para obtener más detalles.

La exportación de docker build falla con un error de propiedad

Ejecutar docker build con el exportador local (--output=type=local o -o <ruta>) dentro de un sandbox falla porque el exportador intenta hacer lchown en los archivos de salida para preservar la propiedad de la compilación. Los procesos dentro del sandbox se ejecutan como un usuario sin privilegios y sin CAP_CHOWN, por lo que la operación es denegada.

Usa el exportador de tar y extrae el archivo en su lugar:

$ mkdir -p ./result
$ docker build --output type=tar,dest=- . | tar xf - -C ./result

Extraer el archivo tar como el usuario actual evita la llamada a chown.

Directorio de trabajo de Git (worktree) huérfano después de eliminar un sandbox

Si utilizaste --branch, la limpieza del directorio de trabajo (worktree) durante sbx rm se realiza en la medida de lo posible. Si falla, el sandbox se elimina pero la rama y el directorio de trabajo se quedan allí. Si git worktree list muestra un directorio de trabajo huérfano en .sbx/ después de eliminar un sandbox, límpialo manualmente:

$ git worktree remove .sbx/<nombre-sandbox>-worktrees/<nombre-rama>
$ git branch -D <nombre-rama>

Las confirmaciones (commits) del sandbox no están firmadas

Docker Sandboxes puede firmar confirmaciones (commits) de Git con claves SSH del agente de tu host. Para ver los pasos de configuración, consulta Confirmaciones firmadas.

Si ssh-add -L imprime The agent has no identities., significa que el sandbox puede comunicarse con el agente reenviado, pero el agente del host no tiene ninguna clave cargada. Carga la clave de firma en el agente SSH de tu host:

$ ssh-add ~/.ssh/id_ed25519

Si la firma de confirmaciones funciona en el host pero falla en un sandbox, verifica si Git está configurado para firmar con una ruta de archivo del host como /Users/yo/.ssh/id_ed25519.pub. El sandbox utiliza el agente SSH reenviado, no la ruta del archivo de clave del host. En su lugar, utiliza el formato de clave pública en línea:

$ git config --global gpg.format ssh
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"

Si Git informa que falta ssh-keygen, utiliza una plantilla de sandbox que incluya las herramientas de cliente de OpenSSH.

Si git log --show-signature informa que es necesario configurar gpg.ssh.allowedSignersFile, significa que Git no puede verificar la firma SSH localmente. Esta configuración de verificación no es necesaria para crear confirmaciones firmadas. GitHub utiliza las claves de firma SSH configuradas en tu cuenta de GitHub para verificar las confirmaciones.

Las claves de firma GPG y S/MIME no están disponibles dentro del sandbox. Si tu repositorio u organización requiere firmas GPG o S/MIME, o si la firma SSH no está configurada, utiliza una de estas soluciones alternativas:

• Confirma fuera del sandbox. Deja que el agente realice los cambios sin confirmarlos, luego confirma y firma desde la terminal de tu host.

• Firma a posteriori. Deja que el agente confirme los cambios dentro del sandbox y luego vuelve a firmar las confirmaciones en tu host:

  $ git rebase --exec 'git commit --amend --no-edit -S' origin/main
  

  Esto vuelve a aplicar cada confirmación en la rama y la firma de nuevo con tu clave de firma local.

Desviación del reloj después de la suspensión/activación

Si tu portátil se suspende y se activa mientras se ejecuta un sandbox, el reloj de la VM puede quedar retrasado con respecto al reloj del host. Esto causa problemas como:

• Fallo en las llamadas a APIs externas debido a la validación de marcas de tiempo.
• Confirmaciones de Git con marcas de tiempo incorrectas.
• Errores de certificados TLS debido a discrepancias horarias.

Para solucionar el problema, detiene y reinicia el sandbox:

$ sbx stop <nombre-sandbox>
$ sbx run <nombre-sandbox>

Reiniciar el sandbox vuelve a sincronizar el reloj de la VM con el del host.

El demonio no se inicia después de una degradación de versión (downgrade)

Si degradas la versión de sbx a una más antigua que la que gestionó por última vez tu estado local, es posible que el demonio no se inicie y muestre una discrepancia de versiones de base de datos:

ERROR: failed to start backend in-process: start backend: creating containerd
server: ... database is at major version 6, but this binary only supports up
to major version 1

Una versión más nueva de sbx actualizó la base de datos local a un esquema que los binarios más antiguos no comprenden. Para solucionarlo, restablece todo el estado del sandbox:

$ sbx reset --preserve-secrets

Esto detiene todas las VMs y elimina todos los datos de los sandboxes. Tendrás que crear sandboxes nuevos después de esto. La bandera --preserve-secrets conserva los secretos que hayas configurado para que no tengas que volver a configurarlos.

Eliminar todo el estado

Como último recurso, si sbx reset no resuelve el problema, puedes eliminar el directorio de estado de sbx por completo. Esto elimina todos los datos de los sandboxes, la configuración y las imágenes almacenadas en caché. Detén todos los sandboxes que se estén ejecutando primero con sbx reset.

$ rm -rf ~/Library/Application\ Support/com.docker.sandboxes/

> Remove-Item -Recurse -Force "$env:LOCALAPPDATA\DockerSandboxes"

$ rm -rf ~/.local/state/sandboxes/
$ rm -rf ~/.cache/sandboxes/
$ rm -rf ~/.config/sandboxes/

Reportar un problema

Si has agotado los pasos anteriores y el problema persiste, abre un reporte en GitHub en github.com/docker/sbx-releases/issues.

Para ayudar a Docker a investigar, genera un paquete de diagnóstico y compártelo cuando reportes el problema:

$ sbx diagnose --upload

El paquete contiene los registros del demonio, los resultados de las comprobaciones de diagnóstico y la información básica del sistema. Una vez confirmada la opción --upload, el paquete se carga al soporte de Docker y el comando imprime un ID de diagnóstico. Incluye este ID en tu reporte para que el equipo pueda correlacionarlo con el paquete cargado.