Uso del entorno aislado local

Introduction

El espacio aislado local restringe el acceso a archivos, recursos de red y credenciales en tu equipo. En este artículo se explica cómo habilitar y deshabilitar el espacio aislado local en Copilot CLI y el Copilot app. Para obtener información general conceptual sobre los espacios aislados locales y en la nube para Copilot, consulte Información sobre los entornos de pruebas en la nube y locales para GitHub Copilot. Para obtener información sobre cómo ajustar la configuración del espacio aislado, consulte Configuración de los ajustes del entorno aislado local.

Para obtener información sobre el uso del espacio aislado local en Visual Studio Code, consulte Comandos de terminal del agente Sandbox en la documentación de VS Code.

Prerequisites

• Windows: el espacio aislado local en Windows requiere Windows 11 versión 25H2 con la actualización KB5124010 o posterior, o Windows 11 versión 26H1 con la actualización KB5124006 o posterior, con compatibilidad con el nivel BaseContainer del back-end processContainer.
• Linux: Bubblewrap (bwrap) versión 0.5.0 o posterior, y slirp4netns debe estar instalado y disponible en tu PATH.

Uso del aislamiento local en Copilot CLI

Al habilitar el espacio aislado local, Copilot CLI ejecuta la mayoría de los comandos y herramientas que invoca en su nombre dentro de un espacio aislado del sistema operativo. Una vez habilitado el entorno aislado local, se utilizará en todas tus sesiones de Copilot CLI hasta que lo deshabilites o lo desactives para una sesión específica. Si la configuración administrada por la empresa requiere el entorno aislado, ni la configuración habitual ni la opción de línea de comandos --no-sandbox pueden desactivarlo. Sin embargo, si la directiva efectiva permite la omisión del espacio aislado, puede deshabilitar explícitamente el espacio aislado para el resto de la sesión actual, ya sea desde un aviso de permisos de omisión activo o ejecutando /sandbox disable. La exclusión voluntaria de esta sesión no modifica la política guardada.

De forma predeterminada, los comandos y herramientas de espacio aislado pueden escribir en el directorio de trabajo actual y en las carpetas temporales. En un repositorio de Git, los metadatos de Git del repositorio también se pueden escribir, mientras que el resto del repositorio por encima de tu directorio de trabajo actual es legible, pero no se puede escribir. Las ubicaciones seleccionadas del sistema y de las herramientas de desarrollador son legibles y algunas memorias caché de compilación y paquetes tienen permiso de escritura. Esto no concede acceso a todo el directorio personal. Otras rutas de acceso se bloquean a menos que conceda acceso.

El acceso saliente a Internet está activado de forma predeterminada. El acceso a la red local está desactivado. La forma en que esta configuración afecta a los comandos depende del sistema operativo. Consulte Configuración de los ajustes del entorno aislado local.

La autenticación para Git y GitHub CLI (gh) está habilitada de forma predeterminada, pero las operaciones como git push y gh pr create dependen de la configuración de red y la compatibilidad de herramientas. Los comandos y scripts de espacio aislado reciben credenciales de Git y de gh de marcador de posición. Un proxy local sustituye estos por sus credenciales reales solo para destinos HTTPS aprobados.

Las credenciales de Git conservan sus restricciones de ruta de acceso de host, puerto y repositorio originales. Para gh, las credenciales solo se usan para github.com, api.github.comy uploads.github.com. Puede desactivar la autenticación en la pestaña Credenciales de /sandbox config.

También puede enmascarar variables de entorno adicionales, como tokens de API. Comandos, servidores MCP locales y servidores de lenguaje que se ejecutan dentro del espacio aislado reciben marcadores de posición para estas variables. El proxy proporciona cada valor real solo a los hosts HTTPS que especifiques. Para obtener instrucciones de configuración, consulta Configuración de los ajustes del entorno aislado local.

En Windows, esto requiere una versión que admita conexiones desde el espacio aislado a los servicios del equipo (loopback del host). También debe habilitar Permitir red local en la pestaña Red de /sandbox config. Esto también permite el acceso a la red privada, no solo el acceso al proxy de credenciales.

Para obtener una visión general conceptual del aislamiento en Copilot CLI, consulte Información sobre los entornos de pruebas en la nube y locales para GitHub Copilot.

Comandos del entorno aislado

Puede administrar el espacio aislado local desde dentro de una Copilot CLI sesión mediante el /sandbox comando de barra diagonal. Tiene los siguientes subcomandos.

Habilitación del espacio aislado local

Para activar el aislamiento local, introduzca el siguiente comando en una sesión interactiva Copilot CLI:

/sandbox enable

/sandbox enable

El espacio aislado comienza a usarse inmediatamente para la sesión actual.

Después de habilitar el aislamiento local, este se seguirá utilizando tanto en las sesiones interactivas actuales y futuras como en las sesiones programáticas.

Desactivación del entorno de pruebas local

Si la configuración administrada de empresa requiere espacio aislado, /sandbox disable se rechaza a menos que la directiva efectiva permita la omisión del espacio aislado. Cuando se permite la elusión, ejecutar /sandbox disable —o responder a una solicitud activa de permiso de elusión— desactiva el aislamiento solo durante el resto de la sesión actual, sin flexibilizar la política guardada.

Para dejar de utilizar el aislamiento local, escriba el siguiente comando en una sesión interactiva Copilot CLI:

/sandbox disable

/sandbox disable

A menos que la configuración administrada de la empresa requiera aislamiento, se desactiva en la sesión actual y en sesiones nuevas y reiniciadas. Bajo una directiva administrada que permite omitir, se desactiva el aislamiento solo para la sesión actual.

Un comando de habilitación o deshabilitación normal guarda su elección como sandbox.enabled en el archivo de configuración personal (~/.copilot/settings.json de forma predeterminada). Una exclusión de solo sesión administrada no cambia este archivo. Ejecute /sandbox enable para restaurar el aislamiento en esa sesión.

Uso del entorno de pruebas para una sola sesión

Puede usar la opción de línea de comandos --sandbox para usar el aislamiento en una sola sesión, sin habilitar el aislamiento para sus otras sesiones. Si el aislamiento ya está habilitado, puede deshabilitarlo para una sola sesión mediante la opción --no-sandbox. La opción --no-sandbox no puede anular la configuración administrada por la empresa que requiera el uso del entorno de pruebas.

Puede combinar estas opciones con la opción de línea de comandos -p para controlar el entorno de pruebas en el uso programático de la CLI. Por ejemplo:

copilot --sandbox -p "PROMPT"

copilot --sandbox -p "PROMPT"

Ejecutar un solo comando fuera del entorno aislado

Cuando el espacio aislado bloquea un comando, Copilot puede pedirle que apruebe otro intento con acceso más amplio. El mensaje describe el comando y el reintento propuesto. Puede aprobarlo, mantener el resultado bloqueado o deshabilitar el espacio aislado para el resto de la sesión actual. Deshabilitar el espacio aislado para la sesión solo está disponible si la directiva efectiva permite la omisión del espacio aislado. Cuando se permite, también puede hacerlo en cualquier momento ejecutando /sandbox disable.

Las solicitudes de omisión están habilitadas de forma predeterminada y se pueden desactivar en la configuración del sandbox.

Una omisión autorizada de comandos evita el enmascaramiento de credenciales y el proxy de espacio aislado. El comando se ejecuta con su entorno normal, que puede contener valores secretos reales. Las restricciones de host de variables enmascaradas no protegen un comando que se ejecuta fuera del espacio aislado.

El espacio aislado es solo una de las razones por las que un comando puede fallar. Copilot ofrece un reintento con acceso más amplio solo cuando el sandbox es la causa probable y la ejecución fuera de él podría realmente ayudar. Otros errores no muestran ningún aviso de omisión. Para ver el comportamiento de reintento específico de la plataforma, consulte Configuración de los ajustes del entorno aislado local.

Comprobando si se está utilizando el aislamiento

Para comprobar si se está usando el aislamiento local para la sesión actual, escriba:

/sandbox status

/sandbox status

Copilot CLI informa de si el espacio aislado está habilitado para la sesión. Si la configuración administrada de la organización requiere espacio aislado, el estado también indica esto. Dado que el estado refleja lo que la sesión realmente impone, es la forma fiable de confirmar si los comandos que ejecuta Copilot se están ejecutando en un entorno aislado.

Para ver no solo si el aislamiento está activado, sino también exactamente qué rutas pueden leerse, escribirse o están bloqueadas, introduzca /sandbox policy. Para obtener más información, vea Descripción de las directivas del sistema de archivos para el entorno de pruebas local en GitHub Copilot CLI.

También puede ver de un vistazo el estado del entorno aislado en la línea de estado, que contiene sandbox enabled cuando se está usando el entorno aislado. La visualización de la información del sandbox en la línea de estado está activada de manera predeterminada. Si se ha desactivado, puede volver a activarlo:

1. Escribe /statusline.
2. Desplace la selección hacia abajo en la lista de opciones hasta sandbox.
3. Presione Entrar para alternar la configuración para que muestre una marca de verificación.

Troubleshooting

Utilice las instrucciones siguientes para solucionar problemas de comandos bloqueados, PowerShell y Git en Windows y errores de autenticación.

Solución de problemas de comandos bloqueados

Si un comando no puede acceder a un archivo, usar una herramienta o conectarse a un host, compruebe la directiva de espacio aislado antes de conceder acceso más amplio.

1. Ejecute /sandbox status para confirmar si el espacio aislado está activado para la sesión actual.

2. Ejecute /sandbox policy para inspeccionar la directiva efectiva. Para ver las rutas de acceso adicionales disponibles para las herramientas que usa un comando, incluya el comando después de /sandbox policy. Por ejemplo:

   Shell

   /sandbox policy npm install
   

   Esto muestra una vista previa de la directiva sin ejecutar npm install. Revise las rutas de acceso enumeradas y la configuración de red. Compruebe Notas para ver la configuración que no se pudo aplicar.

3. Si la directiva bloquea el acceso que quiere permitir, use /sandbox config para actualizar la ruta de acceso requerida o las reglas de host requeridas. Conceda solo el acceso necesario para el comando. Para ver las rutas de acceso que faltan y los vínculos simbólicos, consulte Descripción de las directivas del sistema de archivos para el entorno de pruebas local en GitHub Copilot CLI. Agregar un directorio con /add-dir no concede acceso al sandbox.

4. Si la configuración la administra su organización, póngase en contacto con el administrador. Si el error nombra una característica de sistema operativo que falta o una dependencia de Linux, cumpla ese requisito y reinicie Copilot CLI antes de intentarlo de nuevo.

5. Pida Copilot que vuelva a ejecutar el comando. Si se ofrece un bypass de un solo comando, apruébelo solo si se siente cómodo con el acceso más amplio descrito. Deshabilitar el espacio aislado para toda la sesión proporciona acceso más amplio a los comandos posteriores, no solo al comando bloqueado.

Solución de problemas de rutas bloqueadas inexistentes

La configuración del espacio aislado puede bloquear el acceso a archivos o directorios específicos. Si no existe una ruta de acceso bloqueada en el equipo, Copilot CLI crea un directorio en esa ubicación antes de iniciar un comando de espacio aislado. También crea los directorios padre que faltan. Estos directorios no se eliminan automáticamente posteriormente.

Por ejemplo, si bloquea el acceso a .env antes de que exista ese archivo, Copilot CLI crea un directorio denominado .env, no un archivo.

• Si la ruta de acceso bloqueada está pensada para ser un archivo, cree ese archivo fuera del espacio aislado antes de ejecutar un comando de espacio aislado.
• Si ve Failed to prepare denied sandbox path, el comando no se ha iniciado. Compruebe que la ruta de acceso configurada es correcta y que la cuenta tiene permiso para crear directorios allí. Use /sandbox config para corregir una ruta de acceso incorrecta o póngase en contacto con el administrador si la configuración está administrada.

Ejecutar /sandbox policy no crea estos directorios. En Linux, las rutas de acceso que aún no existen se omiten de la directiva efectiva que se muestra en la versión preliminar. Permanecen en tus ajustes configurados.

Solución de problemas de PowerShell y Git en Windows

En instalaciones de Windows sin las actualizaciones necesarias, PowerShell en espacio aislado puede notificar una raíz de unidad, como C:\, como su directorio actual. Set-Location y los comandos de Git que se basan en el directorio actual pueden producir un error aunque Se inicie PowerShell.

1. Instale la actualización de septiembre de 2026 o posterior para una versión de Windows compatible. Si su organización administra las actualizaciones de Windows, póngase en contacto con el administrador.

2. Si no puede actualizar inmediatamente, pida Copilot que use una ruta de acceso de repositorio absoluta para los comandos de Git. Por ejemplo:

   Shell

   git -C "C:\PATH\TO\REPOSITORY" status
   

   Esto evita depender del directorio actual de PowerShell. El entorno aislado todavía debe permitir el acceso al repositorio. No corrige otros errores de autenticación o sistema de archivos.

Solución de problemas de autenticación

Cuando el enmascaramiento de credenciales está habilitado, Copilot CLI usa un proxy local para agregar las credenciales reales a las solicitudes salientes. Las herramientas que usan esas credenciales deben admitir el proxy y confiar en su certificado de seguridad.

Copilot CLI proporciona automáticamente un conjunto de certificados temporal a las herramientas de espacio aislado. Algunas herramientas no usan este paquete y pueden notificar errores de autenticación o certificado.

En macOS y Windows, puede instalar opcionalmente la entidad de certificación del proxy en el almacén de confianza del sistema operativo para mejorar la compatibilidad. En una sesión Copilot CLI, ejecute /sandbox ca create y, a continuación, /sandbox ca trust. En Windows, la instalación del certificado requiere la aprobación del administrador. Esto también cambia la confianza de certificado para las aplicaciones fuera de Copilot CLI.

La instalación del certificado no resuelve todos los problemas de compatibilidad. Las herramientas que requieren HTTP/2, aceptan solo certificados de servidor específicos (anclaje de certificados), usan certificados de cliente o usan credenciales para firmar las solicitudes pueden producir errores.

Para las variables de entorno enmascaradas, compruebe que la variable está disponible para la CLI, el destino coincide con sus hosts de inyección y la configuración de red permite la conexión. Las herramientas deben enviar el marcador de posición como una credencial en un encabezado de solicitud HTTPS, como Authorization o X-Api-Key. La autenticación HTTP Básica también funciona cuando el marcador de posición es la contraseña. HTTP en texto claro, los cuerpos de solicitud, las direcciones URL y las solicitudes firmadas no reciben el valor real.

El enmascaramiento protege solo las variables de entorno configuradas y la autenticación de Git y gh habilitada. No oculta secretos en los archivos de credenciales, otras variables de entorno ni la autenticación remota de MCP.

Uso del aislamiento local en Copilot app

En función de cualquier configuración administrada de empresa que se pueda aplicar, puede usar comandos de barra diagonal para habilitar o deshabilitar el espacio aislado local para la sesión activa actualmente.

Activar y desactivar el aislamiento para su sesión

Para activar el espacio aislado local, escriba:

/sandbox on

Para desactivar el espacio aislado, escriba:

/sandbox off

Estos comandos activan o desactivan el aislamiento (sandboxing) inmediatamente, a menos que la configuración administrada de la empresa impida el cambio. Su elección se aplica a la sesión actual, incluida después de un reinicio, y tiene prioridad sobre el valor predeterminado del proyecto. No cambia el valor predeterminado del proyecto para otras sesiones.

Cuando el espacio aislado local está desactivado, los comandos de ejecución del agente pueden acceder a los mismos archivos, redes y credenciales que la cuenta de usuario.

No puede usar el espacio aislado local para una sesión de espacio aislado en la nube ni una sesión que se ejecute en un host remoto.

Ejecutar una herramienta fuera del entorno aislado

Si una herramienta necesita acceso que la directiva de espacio aislado no permite, la aplicación puede mostrar un mensaje Ejecutar fuera del espacio aislado . En función de la directiva efectiva, puede hacer lo siguiente:

• Cancele la operación.
• Ejecute la operación una vez fuera del entorno aislado.
• Desactive el aislamiento durante el resto de la sesión actual y ejecute la operación.

Para deshabilitar el espacio aislado desde este cuadro de diálogo, haga clic en Más opciones, luego en Deshabilitar espacio aislado y ejecutar y confirme su elección.

Si desactiva el aislamiento desde este aviso, la aplicación muestra Aislamiento desactivado para esta sesión. Haga clic en Volver a habilitar el espacio aislado para activarlo de nuevo.

Deshabilitar temporalmente el espacio aislado no cambia el valor predeterminado del proyecto ni la configuración guardada de la sesión. Finaliza cuando la sesión se reinicia o se vuelve a conectar.

El propietario de una empresa puede impedir que los usuarios ejecuten herramientas fuera del entorno aislado. Para obtener más información, vea Configuración administrada por la empresa.

Lectura adicional

• Información sobre los entornos de pruebas en la nube y locales para GitHub Copilot
• Configuración de los ajustes del entorno aislado local