Si prefieres no usar --shell-install, añade la línea tú mismo:```bash

zsh / bash

eval "$(cplt --shell-setup --agent opencode)"

fish

alias opencode 'cplt --agent opencode'

El mismo patrón que usan mise, direnv y starship.
</details>

**Por qué cada alias nombra a su agente.** `alias opencode=cplt` no haría lo que parece. El simple `cplt` elige su agente desde `--agent`, luego el archivo de configuración, y luego lo que encuentre en PATH — y la detección en PATH prefiere `copilot`. Escribir `opencode` aislaría a Copilot en su lugar, sin nada en pantalla que lo indique. El alias pasa `--agent` para que el comando que escribes sea el agente que obtienes.

**¿Por qué un alias en lugar de un enlace simbólico?** cplt y Copilot CLI se instalan en el mismo directorio bin de Homebrew (`/opt/homebrew/bin/`), y solo un archivo llamado `copilot` puede residir allí, por lo que un enlace simbólico entraría en conflicto. Un alias evita eso. El binario real `copilot` permanece en PATH donde cplt puede encontrarlo y envolverlo, y el alias redirige tu comando.

> **Nota:** cplt se niega a anidarse. Si detecta que ya se está ejecutando dentro de un sandbox (mediante la variable de entorno `__CPLT_WRAPPED`), no se lanzará de nuevo. Los subcomandos de solo lectura como `--print-profile` y `cplt doctor` siguen funcionando dentro de un sandbox existente.

## Uso```
cplt [OPTIONS] [-- <AGENT_ARGS>...]

Todo lo que va después de -- va directamente al proceso del agente (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh o shell).

Ajustes predefinidos de política

Un ajuste predefinido establece una base para los cinco interruptores principales del sandbox con una sola bandera en lugar de una lista de ellas. Las banderas individuales siguen prevaleciendo sobre el ajuste predefinido, así que --preset permissive --no-allow-tmp-exec hace lo que dice. También se puede configurar como [sandbox] preset = "..." en la configuración.

Matriz completa de ajustes predefinidos y orden de resolución: docs/configuration.md.

Acceso a archivos

El directorio del proyecto es el espacio de trabajo con permisos de escritura, más una lista de permitidos reducida necesaria para autenticación, runtime y herramientas (véase la tabla anterior). El kernel bloquea todo lo demás, incluidas las claves SSH y las credenciales de la nube.

Variables de entorno

cplt sanitiza el entorno hijo por defecto. Solo pasan las variables seguras, y se eliminan las credenciales de la nube, las URL de bases de datos y los tokens de paquetes. También inyecta variables de endurecimiento que bloquean los scripts de ciclo de vida de npm/yarn/pnpm (hooks de postinstall, el vector de ataque a la cadena de suministro número uno), desactivan la firma de commits y tags de git (ya que ~/.ssh y ~/.gnupg son inalcanzables dentro del sandbox) y desactivan la telemetría de herramientas de desarrollo (DO_NOT_TRACK=1, NEXT_TELEMETRY_DISABLED=1, TURBO_TELEMETRY_DISABLED=1, CHECKPOINT_DISABLE=1 y otras).

Lo que pasa:

Lista de permitidos por prefijo con protección de sufijos secretos. Una variable que coincida con un prefijo permitido como COPILOT_* o YARN_* aún se descarta si termina en un sufijo portador de secretos: _TOKEN, _AUTH, _SECRET, _SECRET_KEY, _KEY, _PASSWORD o _CREDENTIALS. Así, COPILOT_DEBUG pasa y COPILOT_API_KEY no.

Siempre bloqueadas: AWS_*, AZURE_*, NPM_TOKEN, DATABASE_URL, VAULT_TOKEN, SSH_AUTH_SOCK, variables de Docker, tokens de CI y cualquier cosa que no esté en la lista de permitidos.

Interruptores del sandbox

Runtimes compatibles

cplt autodescubre las herramientas instaladas y escribe reglas de sandbox que coincidan. Por lo general, solo los directorios que existen en disco reciben reglas, así que no hay rutas fantasma. En macOS, los directorios de aplicaciones escribibles se incluyen cuando se descubren aunque aún no existan, para que puedan crearse en el primer uso. Linux no puede permitir una escritura en una ruta inexistente, así que allí la creación tiene que ocurrir fuera del sandbox.

Ejecuta cplt doctor para ver si cplt funcionará aquí para tu agente, y cplt doctor --verbose para todo lo que detectó en tu máquina.

Depuración

Banderas de sesión

Estas se traducen a las propias banderas de sesión del agente, así que no necesitas un separador --.

--continue y --resume también se mapean para OpenCode, Antigravity y Claude Code:

¹ Ni OpenCode ni Antigravity tienen un selector de sesión interactivo, así que un --resume solo significa "continuar la última sesión". Claude Code sí lo tiene, así que se mapea directamente.

--remote y --name son exclusivas de Copilot. Pi y el modo shell no reciben ninguna traducción, así que las cuatro banderas se descartan para ellos. La autorreanudación es un mecanismo aparte: cuando invocas cplt sin argumentos de paso ni banderas de sesión, añade --resume por ti, y eso se aplica solo a Copilot.

Combínalas con banderas de sandbox y argumentos de paso --:```bash cplt --resume=my-task # resume by name cplt --remote --name my-task -- -p "fix tests" # remote + named + prompt

### Agentes

Elige uno con `--agent <name>`, o conviértelo en el predeterminado con `cplt config set sandbox.agent <name>`. Copilot, OpenCode y Antigravity se detectan automáticamente desde `PATH` en ese orden cuando no especificas uno.

| Agente | Valor de `--agent` | Detectado automáticamente | Autenticación |
| --- | --- | --- | --- |
| GitHub Copilot CLI | `copilot` | sí, prioridad 1 | Token de GitHub, desde el Keychain o `gh` |
| [OpenCode](https://opencode.ai/) | `opencode` | sí, prioridad 2 | Suscripción de Copilot mediante `/connect`, o `--pass-env ANTHROPIC_API_KEY` |
| [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) | `antigravity`, alias `agy` y `agi` | sí, prioridad 3 | Google OAuth en el navegador |
| [Pi](https://github.com/earendil-works/pi) | `pi` | no | `--pass-env ANTHROPIC_API_KEY` y similares |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude`, alias `cc` y `claude-code` | no | OAuth de suscripción en `~/.claude` o el Keychain, `CLAUDE_CODE_OAUTH_TOKEN` (elimina la concesión del Keychain), o `--pass-env ANTHROPIC_API_KEY` |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh`, alias `deepseek` y `deepseek-harness` | no | `--pass-env DEEPSEEK_API_KEY`, o `$DSH_HOME/.env` (`~/.dsh/.env`) |
| Tu shell | `shell` | no | ninguna |

- **Pi, Claude Code, goose y DeepSeek Harness nunca se detectan automáticamente.** `pi` y `dsh` son nombres de binarios genéricos que podrían colisionar con otra cosa en tu máquina, y Claude Code debe elegirse a propósito.
- **Las claves de API de terceros son opcionales.** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` y las variables de enrutamiento de Bedrock/Vertex (`CLAUDE_CODE_USE_BEDROCK`, `AWS_BEARER_TOKEN_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `ANTHROPIC_VERTEX_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`) nunca se transfieren a menos que las nombres con `--pass-env`.
- **La autenticación por suscripción no necesita variable de entorno.** El flujo de dispositivo `/connect` de OpenCode almacena su token en `~/.local/share/opencode/auth.json`, y el token OAuth de Claude Code reside en `~/.claude` (`.credentials.json` en Linux) o en el Keychain de macOS. Ambos son accesibles dentro del sandbox, por lo que cplt no insiste con una clave de API faltante para ninguno de los dos.
- **Los flujos OAuth en el navegador necesitan `--allow-browser`** cuando aparece un aviso de inicio de sesión. Eso cubre a Antigravity; todos los demás agentes aquí usan un flujo de dispositivo que imprime un código y una URL y no necesita navegador. El flag permite al agente lanzar cualquier aplicación fuera del sandbox y no puede restringirse a URLs, así que actívalo para el inicio de sesión y desactívalo de nuevo — consulta la [tabla de flags](#sandbox-toggles) y [docs/security.md](https://github.com/navikt/cplt/blob/main/docs/security.md#--allow-browser-is-a-sandbox-escape-and-cannot-be-scoped).
- **La actualización automática de Claude Code está deshabilitada** con `DISABLE_AUTOUPDATER=1`. Claude Code no tiene un flag `--no-auto-update`, la autoactualización dentro del sandbox es un vector de persistencia, y de todos modos fallaría contra rutas de instalación de solo lectura.
- **Se respeta `CLAUDE_CONFIG_DIR`.** Cuando está definida, cplt concede ese directorio en lugar de `~/.claude` y transfiere la variable, de modo que una raíz de configuración reubicada sigue funcionando.
- OpenCode es [un cliente de Copilot oficialmente compatible](https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/), por lo que tu suscripción existente de Copilot funciona con `/connect` dentro de OpenCode.

Los directorios de configuración por agente, el uso del Keychain, los permisos de ejecución y el aislamiento del entorno están en [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md#supported-agents).

### Soporte de goose

cplt puede aislar [goose](https://github.com/aaif-goose/goose), el agente de IA de código abierto (binario `goose`). Verificado con goose 1.48.0.```bash
# Run goose (must be explicit — not auto-detected)
cplt --agent goose

# goose is provider-agnostic — pass your provider's API key
cplt --agent goose --pass-env ANTHROPIC_API_KEY
cplt --agent goose --pass-env OPENAI_API_KEY

# Skip the keyring entirely: keep the key in the environment
GOOSE_DISABLE_KEYRING=1 cplt --agent goose --pass-env OPENAI_API_KEY --pass-env GOOSE_DISABLE_KEYRING

# Set goose as your default agent
cplt config set sandbox.agent goose

Notas de seguridad para goose:

• No se detecta automáticamente: selecciónalo explícitamente con --agent goose o establece sandbox.agent = "goose" en la configuración
• Agnóstico al proveedor: goose enruta el tráfico del modelo a un proveedor configurado por el usuario (Anthropic, OpenAI, Google, Databricks, OpenRouter, …). Las claves de proveedor habituales (ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, GOOGLE_API_KEY, DATABRICKS_HOST/DATABRICKS_TOKEN, GROQ_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, AWS_BEARER_TOKEN_BEDROCK) se reconocen como indicios de autenticación y deben pasarse mediante --pass-env. goose lee , no . Cualquier proveedor fuera de este subconjunto sigue funcionando: nombra su variable con

Soporte de DeepSeek Harness

cplt puede ejecutar en sandbox DeepSeek Harness (binario dsh), el harness de agentes orientado a plugins de DeepSeek. Upstream lo distribuye como vista previa para desarrolladores y su propio SAFETY.md indica que no se debe confiar en sus controles como única frontera, que es precisamente el caso para el que existe cplt.```bash

Run DSH (must be explicit — not auto-detected)

cplt --agent dsh

Pass the API key, or keep it in $DSH_HOME/.env

cplt --agent dsh --pass-env DEEPSEEK_API_KEY

Set DSH as your default agent

cplt config set sandbox.agent dsh

**Notas de seguridad para DSH:**
- **No se detecta automáticamente**: selecciónalo con `--agent dsh` (alias `deepseek`, `deepseek-harness`) o establece `sandbox.agent = "dsh"`. `dsh` es un nombre de comando corto y genérico que podría pertenecer a otra cosa en tu máquina
- **Desactiva el propio sandbox de DSH dentro de cplt**: DSH envuelve cada llamada a herramientas de shell y archivos en su propio sandbox de proceso — Seatbelt en macOS, bwrap o Landlock en Linux. Ninguno se anida dentro de cplt. macOS no admite llamadas anidadas a `sandbox-exec` (la misma limitación que hace que cplt desactive el sandbox interno de Gradle, consulta [Limitaciones](#limitations)), y bwrap construye su namespace con `unshare`, que el filtro seccomp de cplt deniega. cplt es el límite de aplicación en cualquier caso, así que elige el preset de permisos `danger-full-access` que DSH incluye para sesiones en sandbox. Si dejas el runner interno activado, las llamadas a herramientas fallan con un error del runner del sandbox en lugar de un error de tarea
- **Una raíz de home, y cplt sigue la anulación**: DSH mantiene sesiones, ajustes, caché y perfiles bajo `$DSH_HOME` (`~/.dsh` por defecto). `DSH_HOME` está en la lista de permitidos del entorno, así que el hijo resuelve la misma raíz que cplt concede. Un valor que apunte a una raíz del sistema o a tu directorio home se rechaza antes del lanzamiento, el mismo veto por el que pasa `CLAUDE_CONFIG_DIR`
- **Protección de persistencia en el host**: `$DSH_HOME/cordis.patch.yml`, la superposición a nivel de home que el Loader lee al arrancar, tiene denegada la escritura. `$DSH_HOME/profiles/` permanece escribible porque DSH reescribe la raíz de inclusión `cordis.yml` de cada perfil en cada arranque, así que un `cordis.patch.yml` por perfil y los plugins instalados son un residual documentado — haz las ediciones de perfiles y de `dsh plugin` fuera de cplt, y lanza siempre `dsh` a través de cplt para que cualquier cosa plantada siga ejecutándose en sandbox
- **Dominios por defecto**: solo `deepseek.com`. El adaptador `dsh-llm-deepseek` incluido usa por defecto `https://api.deepseek.com`. Si apuntas `DEEPSEEK_BASE_URL` a una pasarela, tienes que añadir el dominio de esa pasarela mediante `allowed_domains`
- **Autenticación**: pasa la clave con `--pass-env DEEPSEEK_API_KEY`, o guárdala en `$DSH_HOME/.env`. Una clave guardada a través de la propia interfaz de modelos de DSH acaba en `$DSH_HOME/.credentials.yaml`, dentro de la misma raíz escribible. El Llavero de macOS está denegado, así que `git push` por HTTPS necesita el token de `gh` en `hosts.yml` o `--pass-env GH_TOKEN`

### Modo shell

Ejecuta un shell simple en sandbox sin agente de IA y con las mismas restricciones. Útil para probar herramientas de compilación, depurar problemas del sandbox o simplemente trabajar con cuidado a mano.```bash
# Interactive sandboxed shell (uses $SHELL: fish, zsh, bash)
cplt --agent shell

# Inspect what's allowed without entering the shell
cplt --agent shell --print-profile

Se aplican las mismas reglas de denegación por defecto: aislamiento del sistema de archivos, restricciones de red, saneamiento del entorno. Los directorios de configuración del shell (variables e historial de fish, historial de zsh) permanecen escribibles.

Para un solo comando, cplt exec es más limpio que cplt --agent shell -- -c 'cmd'.

Modo exec

Ejecuta cualquier comando dentro del sandbox sin iniciar un agente. Sin banner de inicio, sin prompt de confirmación, por lo que es adecuado para scripts, pipes y alias de shell.```bash

Sandbox a single command

cplt exec -- npm install cplt exec -- make build cplt exec -- go test ./...

Compound commands via $SHELL -c

cplt exec -c "npm install && npm test"

Pass sandbox flags as usual

cplt exec --allow-lifecycle-scripts -- npm install cplt exec --project-dir /path/to/repo -- make build cplt exec --with-proxy -- curl https://example.com

Shell aliases for sandboxed tools

alias npm="cplt exec -- npm" alias node="cplt exec -- node" alias python="cplt exec -- python"

Cada flag de nivel superior de `cplt` se aplica: `--project-dir`, `--allow-read`, `--deny-path`, `--with-proxy`, `--pass-env`, y el resto. Añade `--no-quiet` para ver el resumen completo de la configuración del sandbox antes de que se ejecute el comando.

### Ejemplos```bash
# The common case: Copilot in the sandbox
cplt -- -p "fix the tests"

# Sessions
cplt --resume                                   # pick one interactively
cplt --resume=my-refactor                       # by name
cplt --continue                                 # most recent in this directory
cplt --remote --name my-task -- -p "fix tests"  # named remote session

# Check the environment before the first run
cplt doctor

# Let Copilot read a shared library directory
cplt --allow-read ~/shared-libs -- -p "use shared-libs"

# Block a path you don't want Copilot to see
cplt --deny-path ~/.config/gh -- -p "refactor auth"

# Extra outbound port, e.g. an external API
cplt --allow-port 8443 -- -p "test the API"

# Localhost for MCP servers or dev servers
cplt --allow-localhost 3000 --allow-localhost 8080 -- -p "use the MCP server"

# All of localhost, needed by Next.js/Turbopack and Vite builds
cplt --allow-localhost-any -- -p "fix the build"

# Pass specific env vars through
cplt --pass-env MY_CUSTOM_VAR --pass-env ANOTHER_VAR -- -p "run with custom config"

# Inherit the full environment (dangerous, debugging only)
cplt --inherit-env -- -p "debug the build"

# Network
cplt --no-proxy -- -p "fix the tests"                    # proxy is on by default
cplt --blocked-domains ./blocked-domains.txt -- -p "refactor"
cplt --allow-private-domain intern.nav.no -- -p "use mcp-onboarding"

# Non-interactive / CI (skip the confirmation prompt)
cplt --yes -- -p "fix the tests"

# Inspect and debug the sandbox itself
cplt --print-profile
cplt --show-denials -- -p "fix the tests"

Configuración

La configuración se realiza en dos niveles: global, para las preferencias del desarrollador, y por repositorio, para las políticas del equipo.```bash

Browse and change settings interactively

cplt settings

Set global preferences

cplt config set sandbox.quiet true cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt" cplt config set git_guard.mode warn # observe pushes instead of blocking them cplt config set gh_guard.enabled false # opt out of the gh guard entirely

Set per-repo policy (committed to .cplt.toml)

cplt config set --repo sandbox.allow_jvm_attach true cplt config set --repo deny.paths "~/secrets"

Inspect

cplt config show # effective config (file + defaults) cplt config explain # every key with its description

`cplt settings` es el editor interactivo, con vistas Effective, Global y Repository, búsqueda, cambios por etapas y una confirmación explícita antes de guardar cualquier cosa sensible para la seguridad. `cplt config` sigue siendo la interfaz estable no interactiva para scripts y CI. Las propuestas de repositorio todavía se confirman y aprueban por separado con `cplt trust`. El editor nunca las confirma ni las aprueba automáticamente.

La precedencia se ejecuta con los flags de CLI, luego el archivo de configuración global en `~/.config/cplt/config.toml`, y después los valores predeterminados integrados. La configuración por repositorio en `.cplt.toml` es una capa separada en lugar de un peldaño en esa escalera: `[deny]` se endurece incondicionalmente, y los permisos aprobados son solo aditivos, por lo que un repositorio puede habilitar una función pero nunca puede desactivar algo establecido por un flag de CLI o la configuración global.

Un `.cplt.toml` en la raíz del repositorio contiene la política del equipo:```toml
[deny]                    # Applied automatically, no opt-in needed
paths = ["~/secrets", "~/.vault-token"]
env = ["VAULT_TOKEN", "DATABASE_URL"]

[propose]                 # Requires developer approval (cplt trust accept)
gh_guard = true
git_push_prevention = true
allow_jvm_attach = true
allow_docker = true

[propose.allow]
ports = [5432]
localhost = [3000]
socket = ["/var/run/docker.sock"]

cplt lo lee desde git HEAD, por lo que el agente no puede manipular su propia política a mitad de sesión, y las aprobaciones de confianza quedan fijadas al contenido del archivo. Un .cplt.toml sin confirmar no otorga nada hasta que se confirma, aunque sus claves [deny] siguen aplicándose. En CI y scripts, donde nadie puede responder a un prompt, --accept-repo-config aprueba las propuestas del archivo confirmado para esa única ejecución sin persistir ninguna confianza. cplt init escribe uno por ti detectando las herramientas del proyecto:```bash cplt init # preview detected permissions cplt init --write # write .cplt.toml to disk cplt init --quiet # output only TOML (pipe-friendly) cplt init --global # generate a personal ~/.config/cplt/config.toml

Conoce JVM (Gradle/Maven), Node.js, Docker, Python, Rust, Go, Playwright, Spring Boot, Ktor, TestContainers, Next.js, Vite, Flyway, Cypress y secretos de entorno desde `.env.example`. Los permisos peligrosos salen del generador con una advertencia de riesgo adjunta. `--global` examina en su lugar elementos a nivel de máquina: navegadores de Playwright, firma GPG, credenciales de registro, agentes alternativos.

Algunas claves son solo globales y se rechazan desde `.cplt.toml` porque son específicas de la máquina o una preferencia local: `sandbox.agent`, `sandbox.quiet`, `sandbox.yes`, `sandbox.validate`, `sandbox.scratch_dir`, `sandbox.pass_env`, `sandbox.inherit_env`, `sandbox.allow_cache_exec`, `sandbox.allow_cache_exec_any`, `proxy.enabled`, `proxy.port`, `proxy.log_file`, `proxy.log_level`, `proxy.blocked_domains`, `proxy.allowed_domains`, y todas las claves de `[gh_guard]` y `[git_guard]`.

Detalles completos, incluido el modelo de confianza, las reglas de expansión de rutas y la referencia completa del archivo de configuración: [docs/configuration.md](https://github.com/navikt/cplt/blob/main/docs/configuration.md).

## Arquitectura```
┌──────────────────────────────────┐
│  cplt (Rust binary)              │
│  ┌───────────┐  ┌─────────────┐  │
│  │ Policy    │  │ CONNECT     │  │
│  │ Generator │  │ Proxy       │  │
│  └─────┬─────┘  │ (optional)  │  │
│        │        └─────────────┘  │
│        ▼                         │
│  ┌─────────────┬────────────┐    │
│  │   macOS     │   Linux    │    │
│  │  Seatbelt   │  Landlock  │    │
│  │  sandbox-   │  + seccomp │    │
│  │  exec       │  pre_exec  │    │
│  └─────────────┴────────────┘    │
│        │                         │
│        ▼                         │
│  copilot (sandboxed)             │
│  ├── All child processes         │
│  ├── Cannot read ~/.ssh          │
│  ├── Network port-restricted     │
│  ├── SSH agent blocked           │
│  └── Filesystem = primary ctrl   │
└──────────────────────────────────┘

El modelo de seguridad es un sistema de archivos de denegación por defecto con aplicación a nivel de kernel. En macOS, y en Linux con kernel 6.7+ (Landlock ABI v4), la red está restringida al puerto 443 por defecto, con --allow-port para puertos adicionales. En kernels de Linux más antiguos, el proxy CONNECT proporciona esa restricción en su lugar, razón por la cual está habilitado por defecto. El acceso al agente SSH y la salida a localhost están bloqueados en el kernel en macOS. En Linux ninguno de los dos lo está: las reglas de Landlock basadas en puertos no pueden distinguir localhost de un host remoto, y connect() de sockets unix no está controlado por Landlock por debajo del kernel 7.1, así que aparte de los sockets que bubblewrap enmascara, el SSH_AUTH_SOCK retenido es lo único que se interpone entre el agente y tus claves cargadas. El generador de perfiles descubre tu entorno (cplt doctor --verbose muestra los mismos resultados de sondeo) y emite reglas solo para los directorios de herramientas que realmente existen en disco. Menos reglas, sandbox más estricto.

• macOS: se genera un perfil Seatbelt/SBPL y se entrega a sandbox-exec
• Linux: reglas de Landlock LSM más un filtro seccomp-BPF, aplicados mediante pre_exec (kernel 5.13+, filtrado de puertos TCP en 6.7+)

Internals y estructura de módulos: docs/architecture.md. Modelo de amenazas, capas de defensa y brechas honestas: SECURITY.md.

Seguridad

Un solo binario, dependencias mínimas, sin servicios en tiempo de ejecución, sin telemetría. Tres capas de defensa, con límites claros entre ellas:

Contra qué protege cplt:

• Exfiltración de secretos (claves SSH, credenciales de la nube, archivos .env): bloqueado por el kernel
• Ejecución de código no autorizada desde directorios temporales: bloqueado por el kernel
• Persistencia mediante binarios en directorios de caché: bloqueado por el kernel, ya que esos directorios tienen exec denegado
• Persistencia mediante hooks de git en el proyecto: .git/hooks tiene escritura denegada a nivel de kernel en macOS. En Linux, con Landlock y sin Bubblewrap, permanece escribible, y el propio git del lado padre de cplt se ejecuta entonces con core.hooksPath=/dev/null, por lo que nunca ejecuta un hook plantado, aunque un git que ejecutes tú mismo sí lo hará
• Persistencia mediante directorios de herramientas de gestores de paquetes que son tanto escribibles como ejecutables (shims de mise, PNPM_HOME, ~/.deno/bin, ~/.bun/bin): allí se concede escritura para que pnpm add -g y similares funcionen dentro del sandbox, así que un agente puede dejar atrás un binario que un shell posterior recoja de tu PATH
• Un binario plantado que secuestre el agente que cplt lanza: en el lanzamiento y en la auditoría, cplt resuelve los ayudantes que ejecuta él mismo (, , , , y el del que lee un token) desde directorios de sistema fijos en lugar de , pero el binario del agente en sí se ejecuta desde donde fue descubierto, que para una instalación global de npm suele estar bajo un árbol de mise o node escribible. cplt no puede resolverlo desde un directorio fijo —legítimamente vive donde tu gestor de versiones lo puso—, así que comprueba la ruta resuelta contra las reglas de escritura que el sandbox está a punto de aplicar y , nombrando el binario y el árbol escribible, y luego continúa

Contra qué no protege cplt:

• Código malicioso que ya esté dentro del directorio del proyecto. El agente tiene lectura/escritura completa allí
• Errores de lógica que introduzca el agente. Sigues revisando el código
• Un adversario sofisticado que eluda la guardia de comandos. Usa protección de ramas del lado del servidor
• Ataques de red a dominios permitidos. Si github.com está permitido, el agente puede leer y escribir allí
• Acceso al Keychain de macOS, para agentes que almacenan autenticación allí. Los contenidos están protegidos por contraseña, y sandbox.keychain_substitute puede ceder el permiso cuando un agente tiene otra credencial

Nuestras prioridades, en orden: correcto (cada afirmación está probada, cada caso límite tiene una CVE o una referencia de investigación), transparente (SECURITY.md no oculta nada), simple (un binario, cero configuración requerida, valores por defecto sensatos) y útil (apartarse del camino y dejar que el agente trabaje, de forma segura).

Más: docs/security.md · SECURITY.md

Red y proxy

El proxy está activado por defecto. Todo el tráfico saliente de Copilot CLI, gh y curl pasa por un proxy CONNECT en localhost mediante HTTP_PROXY/HTTPS_PROXY y NODE_USE_ENV_PROXY=1. Escucha en un puerto efímero asignado por el sistema operativo, así que nada colisiona. Obtienes registro de conexiones en tiempo real, bloqueo de dominios, listas de dominios permitidos, un registro de auditoría persistente y la misma política de puertos que aplica el sandbox (443 más cualquier cosa en allow.ports).```bash cplt --proxy-forced -- -p "fix tests" # force all egress through the proxy cplt --no-proxy -- -p "fix tests" # disable for one run cplt --blocked-domains blocked-domains.txt -- -p "x" # block known-bad domains cplt --allowed-domains allowed-domains.txt -- -p "x" # allowlist mode cplt --default-allowlist -- -p "x" # fail-closed: only the agent's own domains cplt --observe-domains -- -p "x" # record what the agent contacts, block nothing cplt --proxy-upstream http://proxy.corp:8080 -- -p "x" # chain through a corporate proxy

`--observe-domains-out <FILE>` escribe el conjunto observado con un dominio por línea, y
`--proxy-upstream-no-proxy <HOST>` lista los hosts a los que llegar directamente en lugar de a través
del upstream.```bash
cplt config set proxy.enabled false
cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt"
cplt config set proxy.allowed_domains "~/.config/cplt/allowed-domains.txt"
cplt config set proxy.log_file "~/.config/cplt/proxy.log"

El modo forzado por proxy es opcional. Restringe la salida del kernel al puerto del proxy para que un socket abierto directamente, o un env -u HTTPS_PROXY, no pueda escabullirse. La aplicación es total en macOS, que fija a localhost:<proxy_port>. En Linux bloquea TCP directo :443, y una regla seccomp permite solo SOCK_STREAM con protocolo 0 o IPPROTO_TCP para AF_INET/AF_INET6, por lo que UDP, raw, SCTP y DCCP también quedan cerrados — a costa de cualquier cosa que abra dicho socket, no solo el código que envía UDP. Lo que queda es un residual basado en puerto, evil.com:<proxy_port>, hasta #114.

Fuera del modo forzado por proxy, Linux no restringe UDP. Los derechos de red de Landlock son solo TCP hasta ABI v10, cplt maneja AccessNet::ConnectTcp por sí solo, y la regla seccomp anterior deliberadamente no se aplica — denegar SOCK_DGRAM allí rompería getaddrinfo(3), y por tanto todo el DNS, para cada herramienta no proxificada. El UDP saliente a cualquier host, el bind UDP entrante, el túnel DNS y QUIC/HTTP-3 quedan por tanto sin mediación en el modo predeterminado, y el proxy CONNECT transporta solo TCP, así que nada de ello aparece en el registro del proxy. macOS restringe UDP en el modo predeterminado pero tampoco lo enruta: remote ip "*:443" cubre UDP, así que QUIC/HTTP-3 en 443 sale sin tocar el proxy allí también. Bajo proxy.forced el registro del proxy es un registro completo de la salida en macOS. En Linux es completo excepto por el residual evil.com:<proxy_port> anterior, que no atraviesa el proxy y por tanto no aparece en su registro.

Ambas listas coinciden de la misma manera: example.com cubre el dominio exacto y todos los subdominios, la coincidencia no distingue mayúsculas y minúsculas, y los puntos finales se eliminan. Los archivos de lista de bloqueo y lista de permitidos se releen cada cinco segundos, así que puedes editarlos en vivo. El tráfico a localhost omite el proxy mediante NO_PROXY y nunca aparece en el registro de auditoría. --proxy-timeout <SECONDS> limita las lecturas de solicitud y cabeceras (predeterminado 60) y no derriba los túneles CONNECT establecidos, que pueden permanecer inactivos hasta una hora.

Cada flag del proxy, detalle de filtrado de dominios, encadenamiento a proxy corporativo ascendente y el formato del registro de conexiones: docs/proxy.md.

Guardas de comandos

Actívalas y cplt intercepta gh y git mediante scripts envoltorio en $PATH:

Esta es la Capa 3, una barrera blanda. Impide que un agente conforme haga algo destructivo por accidente. Para un límite duro, apóyate en el sandbox del kernel y la protección de ramas del lado del servidor.

Con la guarda de gh activada, cplt también cachea el token de GitHub al lanzar y lo sirve una vez a través del callback gh auth token, luego elimina la caché. Eso reduce las filtraciones accidentales y basadas en el entorno. No es un límite contra un agente hostil, porque la caché vive en el propio TMPDIR del agente y un agente que la lea antes que el consumidor legítimo igualmente obtiene el token. SECURITY.md tiene la declaración completa sobre block_auth_token.

Comportamiento completo: docs/gh-guard.md · docs/git-guard.md

Impactos conocidos

El sandbox bloquea algunos flujos de trabajo a propósito. Los comunes y sus soluciones:

Playwright Chromium necesita cplt config set sandbox.allow_cache_exec ms-playwright, y Chromium debe ejecutarse sin su propio sandbox anidado. En macOS sus ayudantes no pueden inicializar un segundo sandbox Seatbelt dentro de cplt (forbidden-sandbox-reinit); en Linux el filtro seccomp de cplt bloquea las llamadas al sistema de namespace que ese sandbox necesita. Playwright como biblioteca ya se lanza con --no-sandbox, y esa misma opción establece PLAYWRIGHT_MCP_SANDBOX=false para Playwright MCP, que de lo contrario lo volvería a activar. Cualquier otro lanzador de Chromium necesita --no-sandbox por sí mismo. cplt sigue siendo el límite de kernel que aplica, pero un renderer comprometido recibe entonces el perfil completo de Playwright de cplt en lugar del perfil hijo más restringido de Chromium. Ver Cache exec y SECURITY.md.

Git commit funciona para todos los agentes; si git push funciona sobre HTTPS depende del agente. Tres requisitos previos: usa remotos HTTPS en lugar de SSH (git remote set-url origin https://github.com/org/repo.git, o reescribe globalmente con git config --global url."https://github.com/".insteadOf "[email protected]:"), ejecuta gh auth login una vez fuera del sandbox, y ejecuta gh auth setup-git si el helper de credenciales aún no está configurado. El push entonces ejecuta gh auth git-credential, que necesita un token que gh pueda alcanzar desde dentro del sandbox — eso difiere según el agente, ver Git workflow. Los push a la rama predeterminada y todos los push forzados son rechazados por la guarda de git por defecto; haz push a una rama de característica. El socket del agente SSH está bloqueado porque desbloquea todas las claves cargadas y puede autenticarse ante cualquier host, mientras que el helper de credenciales de gh está limitado a GitHub.

La JVM es consciente del proxy, así que un repositorio Maven interno en una IP privada ahora necesita ser permitido. cplt inyecta http(s).proxyHost/proxyPort en JAVA_TOOL_OPTIONS, así que la resolución de dependencias de Gradle y Maven pasa por el proxy CONNECT y aparece en el registro del proxy en lugar de omitirlo. La guarda SSRF del proxy entonces rechaza un Nexus o Artifactory interno que resuelve a espacio de direcciones privado, exactamente como ya lo hace para curl, npm y pip. Añade su nombre DNS a proxy.allow_private_domains. Una URL de repositorio escrita como IP literal desnuda (https://10.20.30.40/repository/maven-public/) no puede permitirse con ninguna clave — esa comprobación se ejecuta antes de consultar la lista de permitidos — así que tal repositorio necesita un nombre DNS. Los forks de plugin WorkerExecutor, y un daemon de Gradle iniciado fuera de cplt y reutilizado dentro, no están proxificados. Ver Internal Maven/Gradle repositories on private IPs.

Gradle 9+ ejecuta su propio sandbox anidado, y cplt lo desactiva. Desde Gradle 8.8 el daemon se envuelve a sí mismo en sandbox-exec (controlado por GRADLE_MACOS_SANDBOX, anteriormente la propiedad org.gradle.daemon.sandbox). macOS no soporta llamadas anidadas a sandbox-exec, así que el sandbox interno falla con "Operation not permitted" en operaciones de socket. cplt inyecta GRADLE_MACOS_SANDBOX=off, ya que él mismo proporciona sandboxing a nivel de kernel. Este es un problema conocido upstream que afecta a cualquier herramienta que envuelva Gradle en un sandbox externo. Anúlalo con --pass-env GRADLE_MACOS_SANDBOX si realmente quieres el sandbox propio de Gradle.

Copilot CLI 1.0.83 ejecuta su propio sandbox anidado, y cplt lo desactiva. En Linux ese sandbox construye un namespace de red — slirp4netns, iptables, /dev/net/tun — y el filtro seccomp de cplt deniega el unshare que toma. cplt también establece HTTP_PROXY/HTTPS_PROXY, lo que en 1.0.83 pone un sandbox de Linux en la ruta de salida del proxy lo hayas pedido o no, así que los dos colisionan en cada lanzamiento. Síntoma: [cplt] Starting Copilot in sandbox... y luego nada. cplt inyecta la propia opción de exclusión de Copilot, COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE=unsupported; Copilot se retira para la sesión, lo dice, y deja intacto tu sandbox.enabled guardado. cplt es el límite, como lo es para Gradle y Chromium. Anúlalo con --pass-env COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE. Una política gestionada empresarial que requiera el sandbox anula todo esto — ver Copilot CLI's own command sandbox.

Cada impacto, con las tablas por herramienta, notas sobre el daemon de JVM y Kotlin, solución de problemas de GPG, y las diferencias de plataforma del registro privado: docs/known-impacts.md.

Limitaciones

macOS

• sandbox-exec está obsoleto. Apple no lo ha eliminado, pero puede hacerlo en una versión futura de macOS.
• SBPL no tiene filtrado basado en dominio. El proxy CONNECT opcional proporciona bloqueo de dominios en su lugar.
• El lsopen de SBPL tampoco tiene filtro, así que --allow-browser es todo Launch Services o nada. Con él activado el agente puede lanzar cualquier aplicación fuera del sandbox, y ningún envoltorio puede acotar eso — ver docs/security.md.

Linux

• Se requiere kernel 5.13+, con Landlock LSM habilitado.
• El filtrado de puertos TCP necesita kernel 6.7+. Los kernels más antiguos obtienen aplicación solo de sistema de archivos.
• Landlock no puede denegar subrutas dentro de rutas permitidas, así que la lectura/escritura/borrado de .env dentro del directorio del proyecto no está aplicada por el kernel. Las escrituras en .git/hooks se bloquean cuando Bubblewrap está activo.
• --deny-path requiere Bubblewrap. Se aplica mediante máscaras de montaje cuando bwrap está activo. Sin él, Landlock es solo lista de permitidos y cplt advierte sobre la denegación en lugar de aplicarla.

Más: docs/security.md

Contribuir

Las contribuciones son bienvenidas.```bash git clone https://github.com/navikt/cplt.git && cd cplt git config core.hooksPath hack # enables pre-commit fmt + clippy checks mise run check # runs fmt, clippy, and tests

Abre un issue antes de comenzar un cambio grande. Cada PR debe pasar CI (fmt, clippy, tests).

## Referencias

- [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md), el modelo de seguridad completo, análisis de amenazas, estrategia de pruebas y trabajos previos
- [Apple sandbox-exec(1)](https://keith.github.io/xcode-man-pages/sandbox-exec.1.html)
- [Chromium Seatbelt V2 Design](https://chromium.googlesource.com/chromium/src/sandbox/+show/refs/heads/main/mac/seatbelt_sandbox_design.md)
- [Landlock LSM documentation](https://docs.kernel.org/userspace-api/landlock.html)
- [seccomp-BPF documentation](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html)
- [OWASP SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
- [michaelneale/agent-seatbelt-sandbox](https://github.com/michaelneale/agent-seatbelt-sandbox)

## Licencia

[MIT](https://github.com/navikt/cplt/blob/main/LICENSE)