Seguridad y control

Elige cómo se ejecutan los comandos, cuándo hace falta aprobación y qué ajustes del proyecto pueden ejecutar código.

Elige un preajuste de seguridad

Pulsa Ctrl+S desde el campo de mensaje con cualquier perfil de teclado. Alt+S es una alternativa avanzada si el terminal transmite Alt u Option como Meta/Esc+. Las sesiones directas de iTerm conservan el texto normal de Option, los acentos y las teclas muertas. También puedes abrir /settings/controls.

Preajuste	Dónde se ejecutan los comandos	Decisión sobre el riesgo
free	Directamente en el anfitrión	Sin aprobación
judged	Directamente en el anfitrión	Un modelo evalúa; si hay dudas, te pregunta
approval	Directamente en el anfitrión	Siempre te pregunta cuando hace falta revisión
isolated	Sandbox nativo	Autónoma
reviewed	Sandbox nativo	Un modelo evalúa; si hay dudas, te pregunta
protected	Sandbox nativo	Siempre te pregunta cuando hace falta revisión

Antes de aplicar, el selector explica dónde se ejecutan los comandos y quién decide sobre el riesgo.

Clarvis exige una confirmación adicional de peligro para free o judged, porque ambos eliminan el aislamiento del sandbox. La etiqueta custom indica una combinación que no coincide exactamente con un preajuste.

Atención

El sandbox y la revisión resuelven problemas distintos. El primero limita dónde actúa un proceso; la segunda decide si debe ejecutarse un comando. Usa ambos para trabajo no fiable o importante.

Comprueba la disponibilidad del sandbox

El sandbox de comandos utiliza Bubblewrap en Linux y Seatbelt en macOS. En otras plataformas, el backend nativo se indica como no disponible. Con availability: "required", una máquina sin backend utilizable rechaza la ejecución en vez de ejecutar directamente en silencio. Con availability: "optional", puede recurrir a ejecución directa.

Abre /settings/sandbox o /doctor para comprobarlo. Puedes limitar el espacio a solo lectura o desactivar la red de los procesos shell y monitor_start. Este sandbox no contiene llamadas al modelo, MCP remotos, hooks ni comandos directos !. Las herramientas de edición también se ejecutan fuera y usan el confinamiento de rutas descrito en Seguridad.

El sandbox nativo ofrece un directorio temporal propio de cada ejecución y admite raíces temporales compatibles del anfitrión: la elegida por el entorno en cada plataforma y /tmp en POSIX. Estas últimas permiten escritura, pero no son almacenamiento privado de Clarvis; otros procesos locales pueden usarlas.

Comprueba el backend nativo y la política que impide ejecutar sin aislamiento cuando este es obligatorio.

Usa herramientas del anfitrión dentro del sandbox

Al iniciar, Clarvis descubre las cadenas de herramientas compatibles del entorno. Reconoce bun, node, python3, python, rust, go, java, dotnet, ruby, deno, php, zig, c-cpp, kotlin y swift.

Para el caso habitual:

1. Inicia Clarvis desde un intérprete donde la herramienta ya esté en PATH.
2. Abre /settings/sandbox y actívalo.
3. Deja Toolchain discovery en auto.
4. Si quieres, limita Included toolchains con nombres separados por espacios, como bun node rust.
5. Pulsa Ctrl+S e inicia otra ejecución.

Pasos 1 a 3. Parte del PATH del anfitrión, activa el sandbox y comprueba el descubrimiento pasivo.

Pasos 4 y 5. Limita las herramientas si hace falta, guarda y usa el resultado en la siguiente ejecución.

La parte inferior muestra las herramientas encontradas, cuáles están activas y el PATH efectivo. El descubrimiento es pasivo: resuelve rutas de ejecutables e instalaciones, pero no ejecuta cc, java, bun ni otras herramientas solo para rellenar la pantalla. Available significa que se ha encontrado el ejecutable; no es una prueba de versión o funcionamiento. Ajustes equivalentes:

{
  "sandbox": {
    "type": "native",
    "enabled": true,
    "availability": "required",
    "toolchains": {
      "mode": "auto",
      "include": ["bun", "node", "rust"]
    }
  }
}

En Apple silicon, /opt/homebrew/bin y sus destinos Homebrew Cellar se reconocen como raíces de herramientas del sistema. Permanecen en solo lectura dentro de Seatbelt y no necesitan extra_paths. Otros SDK o directorios propios usan la opción siguiente.

Expón un directorio de ejecutables propio

Un SDK o directorio arbitrario no es una cadena de herramientas conocida. Para hacerlo accesible:

1. Abre /settings/sandbox.
2. Abre Additional toolchain paths.
3. Introduce directorios absolutos separados por espacios, como /opt/company-sdk/bin.
4. Pulsa Intro y Ctrl+S.
5. Inicia otra ejecución y llama al binario por ruta absoluta o amplía PATH para ese comando.

Añade solo directorios absolutos revisados, guarda y úsalos desde una ejecución nueva.

El ajuste expone el directorio mediante un montaje de solo lectura:

{
  "sandbox": {
    "type": "native",
    "enabled": true,
    "toolchains": {
      "extra_paths": ["/opt/company-sdk/bin"]
    }
  }
}

Sustituye el ejemplo por una ruta que exista en el anfitrión del kernel. Una ruta ausente puede permanecer configurada, pero se marca no disponible y no se monta. Las entradas globales deben ser absolutas. extra_paths no añade permanentemente el directorio al PATH del sandbox. Usa la ruta absoluta:

/opt/company-sdk/bin/acme --version

O amplía PATH solo para ese comando:

PATH="/opt/company-sdk/bin:$PATH" acme --version

El resto de la ejecución conserva el PATH filtrado de Clarvis. No añadas PATH, HOME, TMPDIR, TEMP ni TMP a pass_env: pertenecen al entorno del sandbox, no son valores normales que deban copiarse.

Revisa los comandos

El control de comandos tiene tres modos:

• off: no emite decisiones de revisión;
• on: te pregunta si hace falta aprobación;
• auto: consulta un modelo evaluador y te pregunta si este no puede decidir.

Las reglas de denegación se aplican antes de aprobar y prevalecen sobre las de permiso. Cambiar de preajuste conserva los patrones existentes.

En la configuración inicial, Clarvis crea una lista global visible para comandos habituales de inspección, compilación, pruebas, lint y tipos de varios lenguajes. Nunca amplía una lista ya existente, aunque esté vacía. Los intérpretes y ejecutores genéricos, instalaciones de paquetes, publicaciones, despliegues y migraciones siguen sujetos a revisión. La lista controla aprobaciones, no aísla procesos: mantén activo el sandbox cuando necesites aislamiento.

Configura la política globalmente o por espacio en settings.json:

{
  "guard": {
    "type": "shell",
    "mode": "on",
    "allowed_commands": ["git status", "bun test"],
    "denied_commands": ["git push --force*", "rm -rf /*"]
  }
}

Una entrada sin * es un prefijo con límite de espacio sobre el comando normalizado. Con *, es un glob anclado. Cada segmento del comando debe cumplir la política: una denegación rechaza todo el comando, un permiso autoriza ese segmento y un segmento sin decisión sigue el modo de revisión elegido.

Para una política de evaluación del proyecto, crea .clarvis/guard-judge.md:

Approve read-only inspection and focused test commands.

Ask me before publishing, deploying, deleting, changing credentials, or modifying infrastructure.

Never approve a command that pipes a network response into a shell.

Es la única sustitución del prompt de revisión basada en archivo. La prioridad es: archivo no vacío del espacio, archivo global no vacío ~/.clarvis/guard-judge.md y prompt integrado. No se concatenan. Un archivo ilegible, vacío o demasiado grande se trata como ausente y se usa la siguiente fuente.

Revisa la confianza del espacio

Un repositorio no puede activar su configuración ejecutable por el mero hecho de abrirlo. Clarvis retiene hooks, MCP, selecciones de plugins en ajustes, todos los plugins del repositorio, proveedores ejecutables e instrucciones de agentes hasta aprobar el contenido protegido o usar /workspace-trust. Los plugins globales siguen activos porque instalarlos ya fue un consentimiento del operador.

La huella incluye todo el inventario de plugins del repositorio antes de seleccionar el perfil. Una aprobación cubre los cambios de perfil hasta que cambie contenido de plugins u otro campo protegido. Añadir un plugin o cambiar sus aportaciones incluidas en la huella exige revisión nueva.

Las declaraciones de proveedores de suscripción son una excepción permanente: aprobar el espacio nunca las activa. Configúralas globalmente. Un espacio solo puede seleccionar un modelo de suscripción ya habilitado.

Revisa el contenido identificado antes de aprobar. Si cambia, cambia la huella y se necesita otra revisión. Ejecutar /workspace-trust de nuevo en un espacio de confianza revoca la aprobación.

Aprueba solo si la huella y el contenido mostrados coinciden con lo que esperas del repositorio.

Distingue las acciones directas

Peligro

Una entrada que comienza por ! es un comando local directo. No pasa por el sandbox ni la revisión del agente. Ejecútalo solo después de revisar personalmente el comando completo.

No guardes secretos en prompts, cuerpos de agentes, skills, hooks, documentos de flujos ni ajustes incluidos en Git. Usa los controles de credenciales o referencias al entorno.

Consulta también

• Extension Profiles
• Ámbitos y confianza
• Seguridad
• Configuración
• Hooks