Si vous préférez ne pas utiliser --shell-install, ajoutez la ligne vous-même :```bash

zsh / bash

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

fish

alias opencode 'cplt --agent opencode'

Le même schéma que celui utilisé par mise, direnv et starship.
</details>

**Pourquoi chaque alias nomme son agent.** `alias opencode=cplt` ne ferait pas ce qu'il laisse penser. Un simple `cplt` choisit son agent via `--agent`, puis le fichier de configuration, puis ce qu'il trouve dans le PATH — et la détection dans le PATH privilégie `copilot`. Taper `opencode` mettrait donc Copilot en sandbox à la place, sans rien à l'écran pour le signaler. L'alias passe `--agent` afin que la commande que vous tapez soit l'agent que vous obtenez.

**Pourquoi un alias plutôt qu'un lien symbolique ?** cplt et Copilot CLI s'installent dans le même répertoire bin de Homebrew (`/opt/homebrew/bin/`), et un seul fichier nommé `copilot` peut y résider, donc un lien symbolique entrerait en conflit. Un alias contourne ce problème. Le véritable binaire `copilot` reste dans le PATH où cplt peut le trouver et l'envelopper, et l'alias redirige votre commande.

> **Remarque :** cplt refuse de s'imbriquer. S'il détecte qu'il s'exécute déjà à l'intérieur d'un sandbox (via la variable d'environnement `__CPLT_WRAPPED`), il ne se lancera pas à nouveau. Les sous-commandes en lecture seule telles que `--print-profile` et `cplt doctor` fonctionnent toujours à l'intérieur d'un sandbox existant.

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

Tout ce qui suit -- est transmis directement au processus de l'agent (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh ou shell).

Préréglages de politique

Un préréglage définit une base pour les cinq principaux commutateurs de sandbox avec un seul drapeau au lieu d'une liste de ceux-ci. Les drapeaux individuels l'emportent toujours sur le préréglage, donc --preset permissive --no-allow-tmp-exec fait ce qu'il dit. Également définissable via [sandbox] preset = "..." dans la configuration.

Matrice complète des préréglages et ordre de résolution : docs/configuration.md.

Accès aux fichiers

Le répertoire du projet est l'espace de travail inscriptible, plus une liste d'autorisation étroite nécessaire pour l'authentification, l'exécution et l'outillage (voir le tableau ci-dessus). Le noyau bloque tout le reste, y compris les clés SSH et les identifiants cloud.

Variables d'environnement

cplt assainit l'environnement enfant par défaut. Seules les variables sûres passent, et les identifiants cloud, les URL de bases de données et les jetons de paquets sont supprimés. Il injecte également des variables de durcissement qui bloquent les scripts de cycle de vie npm/yarn/pnpm (hooks postinstall, le vecteur d'attaque de chaîne d'approvisionnement numéro un), désactivent la signature des commits et tags git (puisque ~/.ssh et ~/.gnupg sont inaccessibles à l'intérieur du sandbox), et désactivent la télémétrie des outils de développement (DO_NOT_TRACK=1, NEXT_TELEMETRY_DISABLED=1, TURBO_TELEMETRY_DISABLED=1, CHECKPOINT_DISABLE=1, et autres).

Ce qui passe :

Liste d'autorisation par préfixe avec protection contre les suffixes secrets. Une variable correspondant à un préfixe autorisé tel que COPILOT_* ou YARN_* est tout de même supprimée si elle se termine par un suffixe porteur de secret : _TOKEN, _AUTH, _SECRET, _SECRET_KEY, _KEY, _PASSWORD ou _CREDENTIALS. Ainsi COPILOT_DEBUG passe et COPILOT_API_KEY ne passe pas.

Toujours bloqués : AWS_*, AZURE_*, NPM_TOKEN, DATABASE_URL, VAULT_TOKEN, SSH_AUTH_SOCK, les variables Docker, les jetons CI, et tout ce qui n'est pas dans la liste d'autorisation.

Commutateurs de sandbox

Runtimes pris en charge

cplt découvre automatiquement les outils installés et écrit les règles de sandbox en conséquence. Généralement, seuls les répertoires qui existent sur le disque reçoivent des règles, donc il n'y a pas de chemins fantômes. Sous macOS, les répertoires d'applications inscriptibles sont inclus lorsqu'ils sont découverts même s'ils n'existent pas encore, afin qu'ils puissent être créés à la première utilisation. Linux ne peut pas autoriser une écriture vers un chemin inexistant, donc la création doit avoir lieu en dehors du sandbox dans ce cas.

Exécutez cplt doctor pour voir si cplt fonctionnera ici pour votre agent, et cplt doctor --verbose pour tout ce qu'il a détecté sur votre machine.

Débogage

Drapeaux de session

Ceux-ci se traduisent en drapeaux de session propres à l'agent, donc vous n'avez pas besoin d'un séparateur --.

--continue et --resume sont également mappés pour OpenCode, Antigravity et Claude Code :

¹ Ni OpenCode ni Antigravity n'a de sélecteur de session interactif, donc un --resume seul signifie « continuer la dernière session ». Claude Code en a un, donc il est mappé directement.

--remote et --name sont réservés à Copilot. Le mode Pi et shell ne reçoit aucune traduction du tout, donc les quatre drapeaux sont abandonnés pour eux. La reprise automatique est un mécanisme distinct : lorsque vous invoquez cplt sans arguments de passage ni drapeaux de session, il ajoute --resume pour vous, et cela ne s'applique qu'à Copilot.

Combinez-les avec les drapeaux de sandbox et les arguments de passage -- :```bash cplt --resume=my-task # resume by name cplt --remote --name my-task -- -p "fix tests" # remote + named + prompt

### Agents

Choisissez-en un avec `--agent <name>`, ou définissez-le par défaut avec `cplt config set sandbox.agent <name>`. Copilot, OpenCode et Antigravity sont auto-détectés depuis `PATH` dans cet ordre lorsque vous n'en nommez aucun.

| Agent | Valeur `--agent` | Auto-détecté | Auth |
| --- | --- | --- | --- |
| GitHub Copilot CLI | `copilot` | oui, priorité 1 | Jeton GitHub, depuis le Keychain ou `gh` |
| [OpenCode](https://opencode.ai/) | `opencode` | oui, priorité 2 | Abonnement Copilot via `/connect`, ou `--pass-env ANTHROPIC_API_KEY` |
| [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) | `antigravity`, alias `agy` et `agi` | oui, priorité 3 | Google OAuth dans le navigateur |
| [Pi](https://github.com/earendil-works/pi) | `pi` | non | `--pass-env ANTHROPIC_API_KEY` et autres |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude`, alias `cc` et `claude-code` | non | OAuth d'abonnement dans `~/.claude` ou le Keychain, `CLAUDE_CODE_OAUTH_TOKEN` (supprime l'autorisation Keychain), ou `--pass-env ANTHROPIC_API_KEY` |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh`, alias `deepseek` et `deepseek-harness` | non | `--pass-env DEEPSEEK_API_KEY`, ou `$DSH_HOME/.env` (`~/.dsh/.env`) |
| Votre shell | `shell` | non | aucun |

- **Pi, Claude Code, goose et DeepSeek Harness ne sont jamais auto-détectés.** `pi` et `dsh` sont des noms de binaires génériques qui pourraient entrer en collision avec autre chose sur votre machine, et Claude Code doit être choisi intentionnellement.
- **Les clés API tierces sont opt-in.** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` et les variables de routage Bedrock/Vertex (`CLAUDE_CODE_USE_BEDROCK`, `AWS_BEARER_TOKEN_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `ANTHROPIC_VERTEX_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`) ne passent jamais à moins que vous ne les nommiez avec `--pass-env`.
- **L'authentification par abonnement ne nécessite aucune variable d'environnement.** Le flux d'appareil `/connect` d'OpenCode stocke son jeton dans `~/.local/share/opencode/auth.json`, et le jeton OAuth de Claude Code réside dans `~/.claude` (`.credentials.json` sous Linux) ou dans le Keychain macOS. Les deux sont accessibles à l'intérieur du sandbox, donc cplt ne vous ennuie pas avec une clé API manquante pour l'un ou l'autre.
- **Les flux OAuth dans le navigateur nécessitent `--allow-browser`** lorsqu'une invite de connexion apparaît. Cela couvre Antigravity ; tous les autres agents ici utilisent un flux d'appareil qui affiche un code et une URL et ne nécessite aucun navigateur. Le flag permet à l'agent de lancer n'importe quelle application en dehors du sandbox et ne peut pas être restreint à des URLs, donc activez-le pour la connexion puis désactivez-le — voir le [tableau des flags](#sandbox-toggles) et [docs/security.md](https://github.com/navikt/cplt/blob/main/docs/security.md#--allow-browser-is-a-sandbox-escape-and-cannot-be-scoped).
- **La mise à jour automatique de Claude Code est désactivée** avec `DISABLE_AUTOUPDATER=1`. Claude Code n'a pas de flag `--no-auto-update`, l'auto-mise à jour à l'intérieur du sandbox est un vecteur de persistance, et elle échouerait de toute façon contre des chemins d'installation en lecture seule.
- **`CLAUDE_CONFIG_DIR` est honoré.** Lorsqu'il est défini, cplt accorde ce répertoire au lieu de `~/.claude` et transmet la variable, afin qu'une racine de configuration déplacée continue de fonctionner.
- OpenCode est [un client Copilot officiellement pris en charge](https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/), donc votre abonnement Copilot existant fonctionne avec `/connect` dans OpenCode.

Les répertoires de configuration par agent, l'utilisation du Keychain, les permissions d'exécution et l'isolation de l'environnement sont dans [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md#supported-agents).

### Prise en charge de goose

cplt peut sandboxer [goose](https://github.com/aaif-goose/goose), l'agent IA open-source (binaire `goose`). Vérifié avec 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

Notes de sécurité pour goose :

• Non détecté automatiquement : sélectionnez-le explicitement avec --agent goose ou définissez sandbox.agent = "goose" dans la config
• Indépendant du fournisseur : goose route le trafic du modèle vers un fournisseur configuré par l'utilisateur (Anthropic, OpenAI, Google, Databricks, OpenRouter, …). Les clés de fournisseur courantes (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) sont reconnues comme indices d'authentification et doivent être passées via --pass-env. goose lit , pas . Tout fournisseur en dehors de ce sous-ensemble fonctionne quand même : nommez sa variable avec

Prise en charge de DeepSeek Harness

cplt peut sandboxer DeepSeek Harness (binaire dsh), le harnais d'agent orienté plugins de DeepSeek. En amont, il est livré en aperçu développeur et son propre SAFETY.md indique de ne pas se fier à ses contrôles comme seule frontière, ce qui est précisément le cas pour lequel cplt existe.```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

**Notes de sécurité pour DSH :**
- **Non détecté automatiquement** : sélectionnez-le avec `--agent dsh` (alias `deepseek`, `deepseek-harness`) ou définissez `sandbox.agent = "dsh"`. `dsh` est un nom de commande court et générique qui pourrait appartenir à autre chose sur votre machine
- **Désactivez le sandbox propre à DSH à l'intérieur de cplt** : DSH enveloppe chaque appel d'outil shell et fichier dans son propre sandbox de processus — Seatbelt sur macOS, bwrap ou Landlock sur Linux. Ni l'un ni l'autre ne s'imbrique dans cplt. macOS ne prend pas en charge les appels `sandbox-exec` imbriqués (la même limitation qui fait que cplt désactive le sandbox interne de Gradle, voir [Limitations](#limitations)), et bwrap construit son namespace avec `unshare`, que le filtre seccomp de cplt refuse. cplt est la frontière d'application dans tous les cas, donc choisissez le preset de permissions `danger-full-access` fourni par DSH pour les sessions sandboxées. Laissez le runner interne activé et les appels d'outils échoueront avec une erreur de runner sandbox plutôt qu'une erreur de tâche
- **Une seule racine home, et cplt suit la substitution** : DSH conserve les sessions, les paramètres, le cache et les profils sous `$DSH_HOME` (`~/.dsh` par défaut). `DSH_HOME` figure sur la liste d'autorisation des variables d'environnement, donc le processus enfant résout la même racine que celle accordée par cplt. Une valeur pointant vers une racine système ou votre répertoire home est refusée avant le lancement, le même veto que subit `CLAUDE_CONFIG_DIR`
- **Garde de persistance de l'hôte** : `$DSH_HOME/cordis.patch.yml`, l'overlay au niveau du home que le Loader lit au démarrage, est en écriture refusée. `$DSH_HOME/profiles/` reste accessible en écriture car DSH réécrit la racine d'inclusion `cordis.yml` de chaque profil à chaque démarrage, donc un `cordis.patch.yml` par profil et les plugins installés constituent un résidu documenté — effectuez les modifications de profil et de `dsh plugin` en dehors de cplt, et lancez toujours `dsh` via cplt pour que tout ce qui est planté s'exécute malgré tout en sandbox
- **Domaines par défaut** : `deepseek.com` uniquement. L'adaptateur `dsh-llm-deepseek` fourni pointe par défaut vers `https://api.deepseek.com`. Pointez `DEEPSEEK_BASE_URL` vers une passerelle et vous devrez ajouter le domaine de cette passerelle via `allowed_domains`
- **Authentification** : passez la clé avec `--pass-env DEEPSEEK_API_KEY`, ou conservez-la dans `$DSH_HOME/.env`. Une clé enregistrée via l'interface de modèles propre à DSH atterrit dans `$DSH_HOME/.credentials.yaml`, à l'intérieur de la même racine accessible en écriture. Le Keychain macOS est refusé, donc `git push` via HTTPS nécessite le token de `gh` dans `hosts.yml` ou `--pass-env GH_TOKEN`

### Mode shell

Lancez un shell sandboxé simple sans agent IA et avec les mêmes restrictions. Pratique pour tester des outils de build, déboguer des problèmes de sandbox, ou simplement travailler soigneusement à la main.```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

Les mêmes règles de refus par défaut s'appliquent : isolation du système de fichiers, restrictions réseau, assainissement de l'environnement. Les répertoires de configuration du shell (variables et historique fish, historique zsh) restent inscriptibles.

Pour une seule commande, cplt exec est plus propre que cplt --agent shell -- -c 'cmd'.

Mode exec

Exécutez n'importe quelle commande à l'intérieur du bac à sable sans démarrer d'agent. Pas de bannière de démarrage, pas d'invite de confirmation, ce qui le rend adapté aux scripts, aux pipes et aux 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"

Chaque option de premier niveau de `cplt` s'applique : `--project-dir`, `--allow-read`, `--deny-path`, `--with-proxy`, `--pass-env`, et le reste. Ajoutez `--no-quiet` pour voir le résumé complet de la configuration du bac à sable avant l'exécution de la commande.

### Exemples```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"

Configuration

La configuration s'effectue à deux niveaux : global, pour les préférences du développeur, et par dépôt, pour la politique d'équipe.```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` est l'éditeur interactif, avec les vues Effective, Global et Repository, la recherche, les modifications indexées et une confirmation explicite avant d'enregistrer tout élément sensible pour la sécurité. `cplt config` reste l'interface non interactive stable pour les scripts et la CI. Les propositions de dépôt sont toujours validées et approuvées séparément avec `cplt trust`. L'éditeur ne les valide ni ne les approuve automatiquement.

La priorité s'applique aux indicateurs CLI, puis au fichier de configuration global à `~/.config/cplt/config.toml`, puis aux valeurs par défaut intégrées. La configuration par dépôt dans `.cplt.toml` est une couche distincte plutôt qu'un échelon de cette hiérarchie : `[deny]` se resserre inconditionnellement, et les permissions approuvées sont uniquement additives, de sorte qu'un dépôt peut activer une fonctionnalité mais ne peut jamais désactiver quelque chose défini par un indicateur CLI ou la configuration globale.

Un `.cplt.toml` à la racine du dépôt porte la politique d'équipe :```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 le lit depuis git HEAD, donc l'agent ne peut pas altérer sa propre politique en cours de session, et les approbations de confiance sont épinglées au contenu du fichier. Un .cplt.toml non commité n'accorde rien tant qu'il n'est pas commité, bien que ses clés [deny] s'appliquent toujours. Dans les CI et les scripts, où personne ne peut répondre à une invite, --accept-repo-config approuve les propositions du fichier commité pour cette exécution unique sans persister aucune confiance. cplt init en écrit un pour vous en détectant l'outillage du projet :```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

Il connaît la JVM (Gradle/Maven), Node.js, Docker, Python, Rust, Go, Playwright, Spring Boot, Ktor, TestContainers, Next.js, Vite, Flyway, Cypress, et les secrets d'environnement depuis `.env.example`. Les permissions dangereuses sortent du générateur avec un avertissement de risque attaché. `--global` examine plutôt les éléments au niveau de la machine : navigateurs Playwright, signature GPG, identifiants de registre, agents alternatifs.

Certaines clés sont globales uniquement et rejetées depuis `.cplt.toml` car elles sont spécifiques à la machine ou constituent une préférence locale : `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`, et toutes les clés `[gh_guard]` et `[git_guard]`.

Détails complets, y compris le modèle de confiance, les règles d'expansion des chemins, et la référence complète du fichier de configuration : [docs/configuration.md](https://github.com/navikt/cplt/blob/main/docs/configuration.md).

## Architecture```
┌──────────────────────────────────┐
│  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   │
└──────────────────────────────────┘

Le modèle de sécurité est un système de fichiers en refus par défaut avec application au niveau du noyau. Sur macOS, et sur Linux avec un noyau 6.7+ (Landlock ABI v4), le réseau est restreint au port 443 par défaut, avec --allow-port pour les exceptions. Sur les noyaux Linux plus anciens, le proxy CONNECT assure cette restriction à la place, ce qui explique qu'il soit activé par défaut. L'accès à l'agent SSH et les connexions sortantes vers localhost sont bloqués dans le noyau sur macOS. Sur Linux, ni l'un ni l'autre ne l'est : les règles Landlock basées sur les ports ne peuvent pas distinguer localhost d'un hôte distant, et le connect() sur socket unix n'est pas contrôlé par Landlock avant le noyau 7.1, donc à part les sockets masqués par bubblewrap, le SSH_AUTH_SOCK retenu est la seule chose qui sépare l'agent de vos clés chargées. Le générateur de profil découvre votre environnement (cplt doctor --verbose affiche les mêmes résultats de sonde) et n'émet des règles que pour les répertoires d'outils qui existent réellement sur le disque. Moins de règles, un bac à sable plus strict.

• macOS : un profil Seatbelt/SBPL est généré et transmis à sandbox-exec
• Linux : des règles Landlock LSM plus un filtre seccomp-BPF, appliqués via pre_exec (noyau 5.13+, filtrage des ports TCP sur 6.7+)

Fonctionnement interne et organisation des modules : docs/architecture.md. Modèle de menace, couches de défense et lacunes assumées : SECURITY.md.

Sécurité

Un seul binaire, des dépendances minimales, aucun service d'exécution, aucune télémétrie. Trois couches de défense, avec des frontières claires entre elles :

Ce contre quoi cplt protège :

• Exfiltration de secrets (clés SSH, identifiants cloud, fichiers .env) : bloqué par le noyau
• Exécution de code non autorisée depuis des répertoires temporaires : bloqué par le noyau
• Persistance via des binaires dans les répertoires de cache : bloqué par le noyau, puisque ces répertoires sont en refus d'exec
• Persistance via des hooks git dans le projet : .git/hooks est en refus d'écriture au niveau du noyau sur macOS. Sur Linux, avec Landlock et sans Bubblewrap, il reste accessible en écriture, et le git parent de cplt s'exécute alors avec core.hooksPath=/dev/null pour ne jamais exécuter un hook planté, bien qu'un git que vous lancez vous-même le fera toujours
• Persistance via des répertoires d'outils de gestionnaires de paquets à la fois accessibles en écriture et exécutables (shims mise, PNPM_HOME, ~/.deno/bin, ~/.bun/bin) : l'écriture y est accordée pour que pnpm add -g et compagnie fonctionnent dans le bac à sable, donc un agent peut y laisser un binaire qu'un shell ultérieur récupérera depuis votre PATH
• Un binaire planté détournant l'agent que cplt lance : au lancement et à l'audit, cplt résout les assistants qu'il exécute lui-même (, , , , et le dont il lit un jeton) depuis des répertoires système fixes plutôt que depuis le , mais le binaire de l'agent lui-même s'exécute depuis l'endroit où il a été découvert, ce qui, pour une installation npm-globale, se trouve couramment sous une arborescence mise ou node accessible en écriture. cplt ne peut pas le résoudre depuis un répertoire fixe — il réside légitimement là où votre gestionnaire de versions l'a placé — donc il vérifie le chemin résolu par rapport aux règles d'écriture que le bac à sable s'apprête à appliquer et , en nommant le binaire et l'arborescence accessible en écriture, puis poursuit

Ce contre quoi cplt ne protège pas :

• Du code malveillant déjà présent dans le répertoire du projet. L'agent y dispose d'un accès complet en lecture/écriture
• Les bugs de logique introduits par l'agent. Vous relisez toujours le code
• Un adversaire sophistiqué contournant la garde de commandes. Utilisez la protection de branche côté serveur
• Les attaques réseau sur les domaines autorisés. Si github.com est autorisé, l'agent peut y lire et écrire
• L'accès au Keychain macOS, pour les agents qui y stockent l'authentification. Les contenus sont protégés par mot de passe, et sandbox.keychain_substitute peut échanger cette autorisation là où un agent dispose d'un autre identifiant

Nos priorités, dans l'ordre : correct (chaque affirmation est testée, chaque cas limite a une référence CVE ou de recherche), transparent (SECURITY.md ne cache rien), simple (un binaire, aucune configuration requise, des valeurs par défaut raisonnables), et utile (s'effacer et laisser l'agent travailler, en toute sécurité).

Plus : docs/security.md · SECURITY.md

Réseau et proxy

Le proxy est activé par défaut. Tout le trafic sortant de Copilot CLI, gh et curl passe par un proxy CONNECT localhost via HTTP_PROXY/HTTPS_PROXY et NODE_USE_ENV_PROXY=1. Il écoute sur un port éphémère attribué par l'OS, donc rien n'entre en collision. Vous obtenez la journalisation des connexions en temps réel, le blocage de domaines, la liste d'autorisation de domaines, un journal d'audit persistant, et la même politique de ports que celle appliquée par le bac à sable (443 plus tout ce qui figure dans 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>` écrit l'ensemble observé, un domaine par ligne, et
`--proxy-upstream-no-proxy <HOST>` liste les hôtes à joindre directement plutôt qu'en passant par
l'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"

Le mode forcé par proxy est opt-in. Il restreint la sortie réseau du noyau au port du proxy afin qu'un socket ouvert directement, ou un env -u HTTPS_PROXY, ne puisse pas passer outre. L'application est complète sur macOS, qui s'ancre à localhost:<proxy_port>. Sur Linux, il bloque le TCP direct :443, et une règle seccomp n'autorise que SOCK_STREAM avec le protocole 0 ou IPPROTO_TCP pour AF_INET/AF_INET6, de sorte qu'UDP, raw, SCTP et DCCP sont également fermés — au prix de tout ce qui ouvre un tel socket, pas seulement du code qui envoie de l'UDP. Ce qui subsiste est un résidu basé sur le port, evil.com:<proxy_port>, jusqu'à #114.

En dehors du mode forcé par proxy, Linux ne restreint pas l'UDP. Les droits réseau de Landlock sont TCP uniquement jusqu'à l'ABI v10, cplt ne gère que AccessNet::ConnectTcp, et la règle seccomp ci-dessus n'est délibérément pas appliquée — refuser SOCK_DGRAM à cet endroit casserait getaddrinfo(3), et donc tout le DNS, pour chaque outil non proxifié. L'UDP sortant vers n'importe quel hôte, le bind UDP entrant, le tunnelling DNS et QUIC/HTTP-3 sont donc non médiés en mode par défaut, et le proxy CONNECT ne transporte que du TCP, donc rien de tout cela n'apparaît dans le journal du proxy. macOS restreint l'UDP en mode par défaut mais ne le route pas non plus : remote ip "*:443" couvre l'UDP, donc QUIC/HTTP-3 sur 443 sort sans passer par le proxy là aussi. Sous proxy.forced, le journal du proxy est un enregistrement complet de la sortie réseau sur macOS. Sur Linux, il est complet sauf pour le résidu evil.com:<proxy_port> ci-dessus, qui ne traverse pas le proxy et n'apparaît donc pas dans son journal.

Les deux listes fonctionnent de la même manière : example.com couvre le domaine exact et tous les sous-domaines, la correspondance est insensible à la casse, et les points finaux sont supprimés. Les fichiers de blocklist et d'allowlist sont relus toutes les cinq secondes, vous pouvez donc les modifier à chaud. Le trafic localhost contourne le proxy via NO_PROXY et n'apparaît jamais dans le journal d'audit. --proxy-timeout <SECONDS> borne les lectures de requête et d'en-tête (60 par défaut) et ne démonte pas les tunnels CONNECT établis, qui peuvent rester inactifs jusqu'à une heure.

Chaque option de proxy, détail de filtrage de domaine, chaînage de proxy d'entreprise en amont, et le format du journal de connexion : docs/proxy.md.

Gardes de commandes

Activez-les et cplt intercepte gh et git via des scripts wrapper dans $PATH :

C'est la couche 3, une barrière souple. Elle empêche un agent conforme de faire quelque chose de destructeur par accident. Pour une frontière dure, appuyez-vous sur le sandbox noyau et la protection de branche côté serveur.

Avec la garde gh activée, cplt met aussi en cache le token GitHub au lancement et le sert une fois via le callback gh auth token, puis supprime le cache. Cela réduit les fuites accidentelles et liées à l'environnement. Ce n'est pas une frontière contre un agent hostile, car le cache réside dans le TMPDIR de l'agent lui-même et un agent qui le lit avant le consommateur légitime obtient quand même le token. SECURITY.md contient la déclaration complète sur block_auth_token.

Comportement complet : docs/gh-guard.md · docs/git-guard.md

Impacts connus

Le sandbox bloque certains workflows à dessein. Les plus courants et leurs correctifs :

Playwright Chromium nécessite cplt config set sandbox.allow_cache_exec ms-playwright, et Chromium doit s'exécuter sans son propre sandbox imbriqué. Sur macOS, ses helpers ne peuvent pas initialiser un second sandbox Seatbelt à l'intérieur de cplt (forbidden-sandbox-reinit) ; sur Linux, le filtre seccomp de cplt bloque les appels système de namespace dont ce sandbox a besoin. Playwright en tant que bibliothèque se lance déjà avec --no-sandbox, et cette même option active PLAYWRIGHT_MCP_SANDBOX=false pour Playwright MCP, qui sinon le réactiverait. Tout autre lanceur Chromium a besoin de --no-sandbox lui-même. cplt reste la frontière noyau appliquée, mais un renderer compromis reçoit alors le profil Playwright complet de cplt au lieu du profil enfant plus restreint de Chromium. Voir Cache exec et SECURITY.md.

Git commit fonctionne pour chaque agent ; le bon fonctionnement de git push en HTTPS dépend de l'agent. Trois prérequis : utilisez des remotes HTTPS plutôt que SSH (git remote set-url origin https://github.com/org/repo.git, ou réécrivez globalement avec git config --global url."https://github.com/".insteadOf "[email protected]:"), exécutez gh auth login une fois en dehors du sandbox, et exécutez gh auth setup-git si le credential helper n'est pas encore configuré. Le push exécute alors gh auth git-credential, qui a besoin d'un token que gh peut atteindre depuis l'intérieur du sandbox — cela diffère selon l'agent, voir Git workflow. Les pushs vers la branche par défaut et tous les force pushs sont refusés par défaut par la garde git ; poussez une branche de fonctionnalité. Le socket de l'agent SSH est bloqué car il déverrouille toutes les clés chargées et peut s'authentifier auprès de n'importe quel hôte, tandis que le credential helper gh est limité à GitHub.

La JVM est proxy-aware, donc un dépôt Maven interne sur une IP privée doit désormais être autorisé. cplt injecte http(s).proxyHost/proxyPort dans JAVA_TOOL_OPTIONS, de sorte que la résolution de dépendances Gradle et Maven passe par le proxy CONNECT et apparaît dans le journal du proxy au lieu de le contourner. La garde SSRF du proxy refuse alors un Nexus ou Artifactory interne qui se résout dans l'espace d'adressage privé, exactement comme elle le fait déjà pour curl, npm et pip. Ajoutez son nom DNS à proxy.allow_private_domains. Une URL de dépôt écrite comme un littéral IP nu (https://10.20.30.40/repository/maven-public/) ne peut être autorisée par aucune clé — cette vérification s'exécute avant que l'allow list ne soit consultée — donc un tel dépôt a besoin d'un nom DNS. Les forks de plugin WorkerExecutor, et un daemon Gradle démarré en dehors de cplt et réutilisé à l'intérieur, ne sont pas proxifiés. Voir Internal Maven/Gradle repositories on private IPs.

Gradle 9+ exécute son propre sandbox imbriqué, et cplt le désactive. Depuis Gradle 8.8, le daemon s'enveloppe dans sandbox-exec (contrôlé par GRADLE_MACOS_SANDBOX, auparavant la propriété org.gradle.daemon.sandbox). macOS ne prend pas en charge les appels sandbox-exec imbriqués, donc le sandbox interne échoue avec « Operation not permitted » sur les opérations de socket. cplt injecte GRADLE_MACOS_SANDBOX=off, puisqu'il fournit déjà un sandboxing au niveau noyau. C'est un problème amont connu qui touche tout outil enveloppant Gradle dans un sandbox externe. Remplacez avec --pass-env GRADLE_MACOS_SANDBOX si vous voulez vraiment le sandbox propre de Gradle.

Copilot CLI 1.0.83 exécute son propre sandbox imbriqué, et cplt le désactive. Sur Linux, ce sandbox construit un namespace réseau — slirp4netns, iptables, /dev/net/tun — et le filtre seccomp de cplt refuse le unshare qu'il effectue. cplt définit aussi HTTP_PROXY/HTTPS_PROXY, ce qui en 1.0.83 place un sandbox Linux sur le chemin de sortie proxy que vous l'ayez demandé ou non, de sorte que les deux entrent en collision à chaque lancement. Symptôme : [cplt] Starting Copilot in sandbox... puis rien. cplt injecte l'opt-out propre de Copilot, COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE=unsupported ; Copilot se met en retrait pour la session, le signale, et laisse votre sandbox.enabled enregistré intact. cplt est la frontière, comme pour Gradle et Chromium. Remplacez avec --pass-env COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE. Une politique gérée d'entreprise qui exige le sandbox prime sur tout cela — voir Copilot CLI's own command sandbox.

Chaque impact, avec les tableaux par outil, les notes sur les daemons JVM et Kotlin, le dépannage GPG, et les différences de plateforme pour les registres privés : docs/known-impacts.md.

Limitations

macOS

• sandbox-exec est déprécié. Apple ne l'a pas supprimé, mais pourrait le faire dans une future version de macOS.
• SBPL n'a pas de filtrage basé sur le domaine. Le proxy CONNECT optionnel fournit à la place un blocage par domaine.
• Le lsopen de SBPL n'a pas de filtre non plus, donc --allow-browser c'est tout Launch Services ou rien. Avec cette option activée, l'agent peut lancer n'importe quelle application en dehors du sandbox, et aucun wrapper ne peut restreindre cela — voir docs/security.md.

Linux

• Noyau 5.13+ requis, avec le LSM Landlock activé.
• Le filtrage de port TCP nécessite le noyau 6.7+. Les noyaux plus anciens n'obtiennent qu'une application au niveau du système de fichiers.
• Landlock ne peut pas refuser des sous-chemins à l'intérieur de chemins autorisés, donc la lecture/écriture/suppression de .env dans le répertoire du projet n'est pas appliquée par le noyau. Les écritures dans .git/hooks sont bloquées lorsque Bubblewrap est actif.
• --deny-path nécessite Bubblewrap. Il est appliqué via des masques de montage lorsque bwrap est actif. Sans lui, Landlock est en allowlist uniquement et cplt avertit à propos du deny au lieu de l'appliquer.

Plus d'informations : docs/security.md

Contribuer

Les contributions sont les bienvenues.```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

Ouvrez une issue avant d’entamer une modification importante. Chaque PR doit passer la CI (fmt, clippy, tests).

## Références

- [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md), le modèle de sécurité complet, l’analyse des menaces, la stratégie de test et les travaux antérieurs
- [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)
- [Documentation de Landlock LSM](https://docs.kernel.org/userspace-api/landlock.html)
- [Documentation de seccomp-BPF](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html)
- [Aide-mémoire OWASP sur la prévention des SSRF](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
- [michaelneale/agent-seatbelt-sandbox](https://github.com/michaelneale/agent-seatbelt-sandbox)

## Licence

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