Wenn du --shell-install lieber nicht verwenden möchtest, füge die Zeile selbst hinzu:```bash

zsh / bash

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

fish

alias opencode 'cplt --agent opencode'

Dasselbe Muster, das mise, direnv und starship verwenden.
</details>

**Warum jeder Alias seinen Agenten benennt.** `alias opencode=cplt` würde nicht das tun, wonach es aussieht. Ein einfaches `cplt` wählt seinen Agenten aus `--agent`, dann aus der Konfigurationsdatei und schließlich aus dem, was es in PATH findet – und die PATH-Erkennung bevorzugt `copilot`. Wenn du `opencode` eingibst, würde stattdessen Copilot in einer Sandbox ausgeführt, ohne dass auf dem Bildschirm etwas darauf hinweist. Der Alias übergibt `--agent`, damit der Befehl, den du eingibst, auch der Agent ist, den du bekommst.

**Warum ein Alias statt eines Symlinks?** cplt und Copilot CLI installieren sich in dasselbe Homebrew-bin-Verzeichnis (`/opt/homebrew/bin/`), und dort kann nur eine Datei namens `copilot` liegen, sodass ein Symlink einen Konflikt verursachen würde. Ein Alias umgeht das. Die echte `copilot`-Binärdatei bleibt in PATH, wo cplt sie finden und umschließen kann, und der Alias leitet deinen Befehl um.

> **Hinweis:** cplt weigert sich zu verschachteln. Wenn es erkennt, dass es bereits in einer Sandbox läuft (über die Umgebungsvariable `__CPLT_WRAPPED`), startet es nicht erneut. Schreibgeschützte Unterbefehle wie `--print-profile` und `cplt doctor` funktionieren weiterhin innerhalb einer bestehenden Sandbox.

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

Alles nach -- geht direkt an den Agentenprozess (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh oder shell).

Policy-Presets

Ein Preset setzt eine Baseline für die fünf Haupt-Sandbox-Toggles mit einem einzigen Flag statt einer Liste von ihnen. Einzelne Flags gewinnen weiterhin gegen das Preset, also tut --preset permissive --no-allow-tmp-exec genau das, was es sagt. Auch als [sandbox] preset = "..." in der Config setzbar.

Vollständige Preset-Matrix und Auflösungsreihenfolge: docs/configuration.md.

Dateizugriff

Das Projektverzeichnis ist der beschreibbare Arbeitsbereich, plus eine schmale Allowlist, die für Auth, Runtime und Tooling benötigt wird (siehe Tabelle oben). Der Kernel blockiert alles andere, SSH-Keys und Cloud-Credentials eingeschlossen.

Umgebungsvariablen

cplt bereinigt standardmäßig die Kindumgebung. Nur sichere Variablen werden durchgelassen, und Cloud-Credentials, Datenbank-URLs und Package-Tokens werden entfernt. Es injiziert außerdem Härtungsvariablen, die npm/yarn/pnpm-Lifecycle-Skripte blockieren (Postinstall-Hooks, der Supply-Chain-Angriffsvektor Nummer eins), Git-Commit- und Tag-Signierung deaktivieren (da ~/.ssh und ~/.gnupg innerhalb der Sandbox unerreichbar sind) und Developer-Tooling-Telemetrie abwählen (DO_NOT_TRACK=1, NEXT_TELEMETRY_DISABLED=1, TURBO_TELEMETRY_DISABLED=1, CHECKPOINT_DISABLE=1 und andere).

Was durchgelassen wird:

Präfix-Allowlist mit Secret-Suffix-Schutz. Eine Variable, die einem erlaubten Präfix wie COPILOT_* oder YARN_* entspricht, wird trotzdem verworfen, wenn sie auf ein secret-tragendes Suffix endet: _TOKEN, _AUTH, _SECRET, _SECRET_KEY, _KEY, _PASSWORD oder _CREDENTIALS. Also wird COPILOT_DEBUG durchgelassen und COPILOT_API_KEY nicht.

Immer blockiert: AWS_*, AZURE_*, NPM_TOKEN, DATABASE_URL, VAULT_TOKEN, SSH_AUTH_SOCK, Docker-Variablen, CI-Tokens und alles, was nicht in der Allowlist steht.

Sandbox-Toggles

Unterstützte Runtimes

cplt entdeckt installierte Tools automatisch und schreibt passende Sandbox-Regeln. Im Allgemeinen erhalten nur Verzeichnisse, die auf der Festplatte existieren, Regeln, sodass es keine Phantom-Pfade gibt. Unter macOS werden beschreibbare App-Verzeichnisse bei Entdeckung einbezogen, auch wenn sie noch nicht existieren, sodass sie bei der ersten Verwendung erstellt werden können. Linux kann einen Schreibzugriff auf einen nicht existierenden Pfad nicht erlauben, also muss die Erstellung dort außerhalb der Sandbox erfolgen.

Führe cplt doctor aus, um zu sehen, ob cplt hier für deinen Agenten funktionieren wird, und cplt doctor --verbose für alles, was es auf deinem Rechner entdeckt hat.

Debugging

Session-Flags

Diese werden in die eigenen Session-Flags des Agenten übersetzt, sodass du kein ---Trennzeichen benötigst.

--continue und --resume werden auch für OpenCode, Antigravity und Claude Code gemappt:

¹ Weder OpenCode noch Antigravity hat einen interaktiven Session-Picker, also bedeutet ein bloßes --resume „letzte Sitzung fortsetzen". Claude Code hat einen, also wird es direkt übernommen.

--remote und --name sind nur für Copilot. Pi und Shell-Modus erhalten überhaupt keine Übersetzung, also werden alle vier Flags für sie verworfen. Auto-Resume ist ein separater Mechanismus: Wenn du cplt ohne Pass-Through-Args und ohne Session-Flags aufrufst, hängt es --resume für dich an, und das gilt nur für Copilot.

Kombiniere sie mit Sandbox-Flags und ---Pass-Through-Args:```bash cplt --resume=my-task # resume by name cplt --remote --name my-task -- -p "fix tests" # remote + named + prompt

### Agents

Wähle einen mit `--agent <name>` aus oder mache ihn mit `cplt config set sandbox.agent <name>` zum Standard. Copilot, OpenCode und Antigravity werden automatisch aus `PATH` in dieser Reihenfolge erkannt, wenn du keinen benennst.

| Agent | `--agent`-Wert | Automatisch erkannt | Auth |
| --- | --- | --- | --- |
| GitHub Copilot CLI | `copilot` | ja, Priorität 1 | GitHub-Token, aus dem Keychain oder `gh` |
| [OpenCode](https://opencode.ai/) | `opencode` | ja, Priorität 2 | Copilot-Abonnement via `/connect` oder `--pass-env ANTHROPIC_API_KEY` |
| [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) | `antigravity`, Aliase `agy` und `agi` | ja, Priorität 3 | Google OAuth im Browser |
| [Pi](https://github.com/earendil-works/pi) | `pi` | nein | `--pass-env ANTHROPIC_API_KEY` und Verwandte |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude`, Aliase `cc` und `claude-code` | nein | Abonnement-OAuth in `~/.claude` oder dem Keychain, `CLAUDE_CODE_OAUTH_TOKEN` (entfernt die Keychain-Berechtigung) oder `--pass-env ANTHROPIC_API_KEY` |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh`, Aliase `deepseek` und `deepseek-harness` | nein | `--pass-env DEEPSEEK_API_KEY` oder `$DSH_HOME/.env` (`~/.dsh/.env`) |
| Deine Shell | `shell` | nein | keine |

- **Pi, Claude Code, goose und DeepSeek Harness werden nie automatisch erkannt.** `pi` und `dsh` sind generische Binärnamen, die mit etwas anderem auf deinem Rechner kollidieren könnten, und Claude Code muss bewusst ausgewählt werden.
- **API-Schlüssel von Drittanbietern sind Opt-in.** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` und die Bedrock/Vertex-Routing-Variablen (`CLAUDE_CODE_USE_BEDROCK`, `AWS_BEARER_TOKEN_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `ANTHROPIC_VERTEX_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`) werden nie durchgereicht, es sei denn, du benennst sie mit `--pass-env`.
- **Abonnement-Auth benötigt keine Umgebungsvariable.** Der `/connect`-Device-Flow von OpenCode speichert sein Token in `~/.local/share/opencode/auth.json`, und das OAuth-Token von Claude Code liegt in `~/.claude` (`.credentials.json` unter Linux) oder im macOS-Keychain. Beide sind innerhalb der Sandbox erreichbar, sodass cplt bei keinem von beiden wegen eines fehlenden API-Schlüssels nervt.
- **OAuth-Browser-Flows benötigen `--allow-browser`**, wenn eine Anmeldeaufforderung erscheint. Das betrifft Antigravity; jeder andere Agent hier verwendet einen Device-Flow, der einen Code und eine URL ausgibt und keinen Browser benötigt. Das Flag erlaubt dem Agenten, jede Anwendung außerhalb der Sandbox zu starten, und kann nicht auf URLs eingeschränkt werden, also aktiviere es für die Anmeldung und deaktiviere es danach wieder — siehe die [Flag-Tabelle](#sandbox-toggles) und [docs/security.md](https://github.com/navikt/cplt/blob/main/docs/security.md#--allow-browser-is-a-sandbox-escape-and-cannot-be-scoped).
- **Claude Code Auto-Update ist deaktiviert** mit `DISABLE_AUTOUPDATER=1`. Claude Code hat kein `--no-auto-update`-Flag, Selbstaktualisierung innerhalb der Sandbox ist ein Persistenzvektor, und sie würde ohnehin an schreibgeschützten Installationspfaden scheitern.
- **`CLAUDE_CONFIG_DIR` wird berücksichtigt.** Wenn es gesetzt ist, gewährt cplt dieses Verzeichnis anstelle von `~/.claude` und reicht die Variable durch, sodass ein verschobenes Konfigurationsstammverzeichnis weiterhin funktioniert.
- OpenCode ist [ein offiziell unterstützter Copilot-Client](https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/), sodass dein bestehendes Copilot-Abonnement mit `/connect` innerhalb von OpenCode funktioniert.

Konfigurationsverzeichnisse pro Agent, Keychain-Nutzung, Exec-Berechtigungen und Env-Isolation findest du in [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md#supported-agents).

### goose-Unterstützung

cplt kann [goose](https://github.com/aaif-goose/goose) sandboxen, den Open-Source-KI-Agenten (Binärdatei `goose`). Verifiziert gegen 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

Sicherheitshinweise für goose:

• Nicht automatisch erkannt: explizit auswählen mit --agent goose oder sandbox.agent = "goose" in der Konfiguration setzen
• Provider-agnostisch: goose leitet den Modellverkehr an einen vom Benutzer konfigurierten Provider weiter (Anthropic, OpenAI, Google, Databricks, OpenRouter, …). Gängige Provider-Schlüssel (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) werden als Auth-Hinweise erkannt und müssen über --pass-env übergeben werden. goose liest , nicht . Jeder Provider außerhalb dieser Teilmenge funktioniert trotzdem: Benennen Sie seine Variable mit

DeepSeek Harness-Unterstützung

cplt kann DeepSeek Harness (Binary dsh) sandboxen, das plugin-orientierte Agent-Harness von DeepSeek. Upstream liefert es als Developer Preview aus, und seine eigene SAFETY.md besagt, dass man sich nicht auf seine Kontrollen als einzige Grenze verlassen sollte — genau der Fall, für den cplt existiert.```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

**Sicherheitshinweise für DSH:**
- **Nicht automatisch erkannt**: Wähle es mit `--agent dsh` (Aliase `deepseek`, `deepseek-harness`) aus oder setze `sandbox.agent = "dsh"`. `dsh` ist ein kurzer, generischer Befehlsname, der auf deinem System zu etwas anderem gehören könnte
- **Schalte DSHs eigene Sandbox innerhalb von cplt aus**: DSH verpackt jeden Shell- und Datei-Tool-Aufruf in seine eigene Prozess-Sandbox — Seatbelt unter macOS, bwrap oder Landlock unter Linux. Keine davon lässt sich in cplt verschachteln. macOS unterstützt keine verschachtelten `sandbox-exec`-Aufrufe (dieselbe Einschränkung, die cplt dazu bringt, Gradles innere Sandbox zu deaktivieren, siehe [Limitations](#limitations)), und bwrap baut seinen Namespace mit `unshare` auf, was cplts seccomp-Filter verweigert. cplt ist in jedem Fall die durchsetzende Grenze, also wähle für sandboxed Sessions das von DSH mitgelieferte Berechtigungs-Preset `danger-full-access`. Lass den inneren Runner aktiviert und Tool-Aufrufe schlagen mit einem Sandbox-Runner-Fehler statt einem Task-Fehler fehl
- **Ein Home-Root, und cplt folgt der Überschreibung**: DSH speichert Sessions, Einstellungen, Cache und Profile unter `$DSH_HOME` (standardmäßig `~/.dsh`). `DSH_HOME` steht auf der Env-Allowlist, sodass das Kind denselben Root auflöst, den cplt gewährt. Ein Wert, der auf ein System-Root oder dein Home-Verzeichnis zeigt, wird vor dem Start abgelehnt — dasselbe Veto, das `CLAUDE_CONFIG_DIR` durchläuft
- **Host-Persistenz-Guard**: `$DSH_HOME/cordis.patch.yml`, das Home-Level-Overlay, das der Loader beim Boot liest, ist schreibgeschützt. `$DSH_HOME/profiles/` bleibt beschreibbar, weil DSH bei jedem Boot den Include-Root von `cordis.yml` jedes Profils neu schreibt, sodass ein profilweises `cordis.patch.yml` und installierte Plugins ein dokumentiertes Residuum sind — nimm Profil- und `dsh plugin`-Änderungen außerhalb von cplt vor und starte `dsh` immer über cplt, damit alles Eingeschleuste trotzdem sandboxed läuft
- **Standard-Domains**: nur `deepseek.com`. Der mitgelieferte `dsh-llm-deepseek`-Adapter verwendet standardmäßig `https://api.deepseek.com`. Richte `DEEPSEEK_BASE_URL` auf ein Gateway und du musst die Domain dieses Gateways über `allowed_domains` hinzufügen
- **Auth**: Übergib den Key mit `--pass-env DEEPSEEK_API_KEY` oder bewahre ihn in `$DSH_HOME/.env` auf. Ein Key, der über DSHs eigene Models-UI gespeichert wird, landet in `$DSH_HOME/.credentials.yaml`, innerhalb desselben beschreibbaren Roots. Der macOS Keychain ist gesperrt, also benötigt `git push` über HTTPS das Token von `gh` in `hosts.yml` oder `--pass-env GH_TOKEN`

### Shell-Modus

Führe eine einfache sandboxed Shell ohne KI-Agent und mit denselben Einschränkungen aus. Praktisch zum Testen von Build-Tools, zum Debuggen von Sandbox-Problemen oder einfach zum sorgfältigen manuellen Arbeiten.```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

Die gleichen Deny-by-default-Regeln gelten: Dateisystem-Isolierung, Netzwerkbeschränkungen, Env-Bereinigung. Shell-Konfigurationsverzeichnisse (fish-Variablen und -History, zsh-History) bleiben beschreibbar.

Für einen einzelnen Befehl ist cplt exec sauberer als cplt --agent shell -- -c 'cmd'.

Exec-Modus

Führe einen beliebigen Befehl innerhalb der Sandbox aus, ohne einen Agenten zu starten. Kein Startbanner, keine Bestätigungsaufforderung, daher eignet es sich für Skripte, Pipes und Shell-Aliase.```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"

Jedes Top-Level-`cplt`-Flag gilt: `--project-dir`, `--allow-read`, `--deny-path`, `--with-proxy`, `--pass-env` und der Rest. Füge `--no-quiet` hinzu, um die vollständige Zusammenfassung der Sandbox-Konfiguration zu sehen, bevor der Befehl ausgeführt wird.

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

Konfiguration

Die Konfiguration erfolgt auf zwei Ebenen: global, für Entwicklerpräferenzen, und pro Repository, für Teamrichtlinien.```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` ist der interaktive Editor mit den Ansichten Effective, Global und Repository, Suche, gestaffelten Änderungen und einer expliziten Bestätigung, bevor sicherheitsrelevante Einstellungen gespeichert werden. `cplt config` bleibt die stabile nicht-interaktive Schnittstelle für Skripte und CI. Repository-Vorschläge werden weiterhin separat mit `cplt trust` committet und genehmigt. Der Editor committet oder genehmigt sie niemals automatisch.

Die Rangfolge verläuft über CLI-Flags, dann die globale Konfigurationsdatei unter `~/.config/cplt/config.toml`, dann integrierte Standardwerte. Die Konfiguration pro Repository in `.cplt.toml` ist eine separate Ebene und keine Sprosse auf dieser Leiter: `[deny]` verschärft bedingungslos, und genehmigte Berechtigungen sind ausschließlich additiv, sodass ein Repository eine Funktion aktivieren, aber niemals etwas deaktivieren kann, das durch ein CLI-Flag oder die globale Konfiguration festgelegt wurde.

Eine `.cplt.toml` im Repository-Stammverzeichnis enthält die Team-Richtlinie:```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 liest sie aus git HEAD, sodass der Agent seine eigene Richtlinie nicht mitten in der Sitzung manipulieren kann und Trust-Genehmigungen an den Inhalt der Datei gebunden sind. Eine nicht committete .cplt.toml gewährt nichts, bis sie committet wird, obwohl ihre [deny]-Schlüssel weiterhin gelten. In CI und Skripten, wo niemand eine Eingabeaufforderung beantworten kann, genehmigt --accept-repo-config die Vorschläge der committeten Datei für diesen einen Lauf, ohne einen Trust zu persistieren. cplt init schreibt eine für dich, indem es die Tooling-Landschaft des Projekts erkennt:```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

Es kennt JVM (Gradle/Maven), Node.js, Docker, Python, Rust, Go, Playwright, Spring Boot, Ktor, TestContainers, Next.js, Vite, Flyway, Cypress und Umgebungsgeheimnisse aus `.env.example`. Gefährliche Berechtigungen kommen mit einer Risikowarnung versehen aus dem Generator heraus. `--global` betrachtet stattdessen Dinge auf Maschinenebene: Playwright-Browser, GPG-Signierung, Registry-Anmeldedaten, alternative Agenten.

Einige Schlüssel sind nur global gültig und werden aus `.cplt.toml` abgelehnt, weil sie maschinenspezifisch oder eine lokale Präferenz sind: `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` und jeder `[gh_guard]`- und `[git_guard]`-Schlüssel.

Vollständige Details, einschließlich des Vertrauensmodells, der Pfaderweiterungsregeln und der vollständigen Konfigurationsdateireferenz: [docs/configuration.md](https://github.com/navikt/cplt/blob/main/docs/configuration.md).

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

Das Sicherheitsmodell ist ein Dateisystem mit Deny-by-Default und Kernel-Durchsetzung. Unter macOS und unter Linux mit Kernel 6.7+ (Landlock ABI v4) ist das Netzwerk standardmäßig auf Port 443 beschränkt, mit --allow-port für zusätzliche Ports. Auf älteren Linux-Kernels übernimmt der CONNECT-Proxy diese Beschränkung, weshalb er standardmäßig aktiviert ist. SSH-Agent-Zugriff und ausgehende Verbindungen zu localhost werden unter macOS im Kernel blockiert. Unter Linux ist weder das eine noch das andere der Fall: Port-basierte Landlock-Regeln können localhost nicht von einem entfernten Host unterscheiden, und unix socket connect() wird von Landlock unterhalb von Kernel 7.1 nicht abgefangen, sodass – abgesehen von den Sockets, die bubblewrap maskiert – der zurückgehaltene SSH_AUTH_SOCK das Einzige ist, was zwischen dem Agenten und deinen geladenen Schlüsseln steht. Der Profilgenerator erkennt deine Umgebung (cplt doctor --verbose zeigt dieselben Probe-Ergebnisse) und erzeugt Regeln nur für Tool-Verzeichnisse, die tatsächlich auf der Festplatte existieren. Weniger Regeln, engere Sandbox.

• macOS: Ein Seatbelt/SBPL-Profil wird generiert und an sandbox-exec übergeben
• Linux: Landlock-LSM-Regeln plus ein seccomp-BPF-Filter, angewendet über pre_exec (Kernel 5.13+, TCP-Port-Filterung ab 6.7+)

Interna und Modulaufbau: docs/architecture.md. Bedrohungsmodell, Verteidigungsschichten und ehrliche Lücken: SECURITY.md.

Sicherheit

Ein Binary, minimale Abhängigkeiten, keine Laufzeitdienste, keine Telemetrie. Drei Verteidigungsschichten mit klaren Grenzen dazwischen:

Wogegen cplt schützt:

• Exfiltration von Geheimnissen (SSH-Schlüssel, Cloud-Anmeldedaten, .env-Dateien): kernel-blockiert
• Unautorisierte Codeausführung aus Temp-Verzeichnissen: kernel-blockiert
• Persistenz über Binaries in Cache-Verzeichnissen: kernel-blockiert, da für diese Verzeichnisse exec verweigert wird
• Persistenz über Git-Hooks im Projekt: .git/hooks ist unter macOS im Kernel schreibgeschützt. Unter Linux bleibt es mit Landlock und ohne Bubblewrap beschreibbar, und cplts eigenes parent-seitiges git läuft dann mit core.hooksPath=/dev/null, sodass es niemals einen platzierten Hook ausführt – ein git, das du selbst ausführst, jedoch schon
• Persistenz über Package-Manager-Tool-Verzeichnisse, die sowohl beschreibbar als auch ausführbar sind (mise-Shims, PNPM_HOME, ~/.deno/bin, ~/.bun/bin): Schreibzugriff wird dort gewährt, damit pnpm add -g und Verwandte in der Sandbox funktionieren, sodass ein Agent ein Binary hinterlassen kann, das eine spätere Shell aus deinem PATH aufgreift
• Ein platziertes Binary, das den Agenten kapert, den cplt startet: Beim Start und Audit löst cplt die Helfer, die es selbst ausführt (, , , und das , aus dem es ein Token liest), aus festen Systemverzeichnissen statt aus auf, aber das Agent-Binary selbst läuft von dort, wo es entdeckt wurde, was bei einer npm-global-Installation üblicherweise unter einem beschreibbaren mise- oder node-Baum liegt. cplt kann es nicht aus einem festen Verzeichnis auflösen – es lebt legitimerweise dort, wo dein Versionsmanager es abgelegt hat –, also prüft es den aufgelösten Pfad gegen die Schreibregeln, die die Sandbox gleich anwenden wird, und , wobei es das Binary und den beschreibbaren Baum benennt, und fährt dann fort

Wogegen cplt nicht schützt:

• Bösartigen Code, der sich bereits im Projektverzeichnis befindet. Der Agent hat dort vollständigen Lese-/Schreibzugriff
• Logikfehler, die der Agent einführt. Du reviewst den Code weiterhin
• Einen raffinierten Angreifer, der den Command-Guard umgeht. Verwende serverseitigen Branch-Schutz
• Netzwerkangriffe auf erlaubte Domains. Wenn github.com erlaubt ist, kann der Agent dort lesen und schreiben
• macOS-Keychain-Zugriff für Agenten, die dort Auth speichern. Die Inhalte sind passwortgeschützt, und sandbox.keychain_substitute kann die Gewährung aufgeben, wo ein Agent eine andere Anmeldedatenquelle hat

Unsere Prioritäten, in dieser Reihenfolge: korrekt (jede Behauptung ist getestet, jeder Edge Case hat eine CVE- oder Forschungsreferenz), transparent (SECURITY.md verbirgt nichts), einfach (ein Binary, keine Konfiguration erforderlich, vernünftige Standardwerte) und nützlich (aus dem Weg gehen und den Agenten sicher arbeiten lassen).

Mehr: docs/security.md · SECURITY.md

Netzwerk und Proxy

Der Proxy ist standardmäßig aktiviert. Der gesamte ausgehende Datenverkehr von Copilot CLI, gh und curl läuft über einen localhost-CONNECT-Proxy via HTTP_PROXY/HTTPS_PROXY und NODE_USE_ENV_PROXY=1. Er lauscht auf einem vom Betriebssystem zugewiesenen ephemeren Port, sodass nichts kollidiert. Du erhältst Verbindungsprotokollierung in Echtzeit, Domain-Blockierung, Domain-Allowlisting, ein persistentes Audit-Log und dieselbe Port-Richtlinie, die die Sandbox durchsetzt (443 plus alles in 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>` schreibt die beobachtete Menge, eine Domain pro Zeile, und
`--proxy-upstream-no-proxy <HOST>` listet Hosts auf, die direkt statt über
das Upstream erreicht werden sollen.```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"

Der Proxy-erzwungene Modus ist Opt-in. Er beschränkt den Kernel-Egress auf den Proxy-Port, sodass ein direkt geöffneter Socket oder ein env -u HTTPS_PROXY nicht vorbeischlüpfen kann. Die Durchsetzung ist auf macOS vollständig, wo auf localhost:<proxy_port> festgelegt wird. Unter Linux blockiert er direktes TCP :443, und eine seccomp-Regel erlaubt nur SOCK_STREAM mit Protokoll 0 oder IPPROTO_TCP für AF_INET/AF_INET6, sodass auch UDP, Raw, SCTP und DCCP geschlossen sind — auf Kosten von allem, was einen solchen Socket öffnet, nicht nur von Code, der UDP sendet. Was bleibt, ist ein portbasierter Rest, evil.com:<proxy_port>, bis #114.

Außerhalb des Proxy-erzwungenen Modus schränkt Linux UDP nicht ein. Landlocks Netzwerkrechte sind bis ABI v10 nur TCP, cplt behandelt AccessNet::ConnectTcp allein, und die obige seccomp-Regel wird bewusst nicht angewendet — SOCK_DGRAM dort zu verweigern würde getaddrinfo(3) und damit alles DNS für jedes nicht über den Proxy laufende Tool brechen. Ausgehendes UDP zu jedem Host, eingehender UDP-Bind, DNS-Tunneling und QUIC/HTTP-3 sind daher im Standardmodus unvermittelt, und der CONNECT-Proxy überträgt nur TCP, sodass nichts davon im Proxy-Log erscheint. macOS schränkt UDP im Standardmodus ein, leitet es aber auch nicht weiter: remote ip "*:443" deckt UDP ab, sodass QUIC/HTTP-3 auf 443 auch dort den Proxy nicht berührt. Unter proxy.forced ist das Proxy-Log auf macOS eine vollständige Aufzeichnung des Egress. Unter Linux ist es vollständig, außer für den obigen Rest evil.com:<proxy_port>, der den Proxy nicht durchläuft und daher nicht in seinem Log erscheint.

Beide Listen stimmen auf dieselbe Weise überein: example.com deckt die exakte Domain und jede Subdomain ab, der Abgleich ist case-insensitive, und abschließende Punkte werden entfernt. Blocklist- und Allowlist-Dateien werden alle fünf Sekunden neu eingelesen, sodass du sie live bearbeiten kannst. Localhost-Verkehr umgeht den Proxy über NO_PROXY und erscheint nie im Audit-Log. --proxy-timeout <SECONDS> begrenzt Anfrage- und Header-Lesevorgänge (Standard 60) und baut keine etablierten CONNECT-Tunnel ab, die bis zu einer Stunde im Leerlauf bleiben können.

Jedes Proxy-Flag, jedes Detail zur Domain-Filterung, Upstream-Corporate-Proxy-Verkettung und das Format des Verbindungslogs: docs/proxy.md.

Command guards

Aktiviere sie, und cplt fängt gh und git über Wrapper-Skripte in $PATH ab:

Dies ist Layer 3, eine weiche Barriere. Sie hält einen regelkonformen Agenten davon ab, versehentlich etwas Destruktives zu tun. Für eine harte Grenze stütze dich auf die Kernel-Sandbox und den serverseitigen Branch-Schutz.

Mit aktiviertem gh-Guard cached cplt außerdem das GitHub-Token beim Start und liefert es einmal über den gh auth token-Callback aus, dann löscht es den Cache. Das reduziert versehentliches und umgebungsbedingtes Leaken. Es ist keine Grenze gegen einen feindseligen Agenten, denn der Cache liegt im eigenen TMPDIR des Agenten, und ein Agent, der ihn vor dem legitimen Konsumenten liest, bekommt das Token trotzdem. SECURITY.md enthält die vollständige Erklärung zu block_auth_token.

Vollständiges Verhalten: docs/gh-guard.md · docs/git-guard.md

Known impacts

Die Sandbox blockiert einige Workflows absichtlich. Die häufigen und ihre Fixes:

Playwright Chromium benötigt cplt config set sandbox.allow_cache_exec ms-playwright, und Chromium muss ohne seine eigene verschachtelte Sandbox laufen. Auf macOS können seine Helper keine zweite Seatbelt-Sandbox innerhalb von cplt initialisieren (forbidden-sandbox-reinit); unter Linux blockiert cplts seccomp-Filter die Namespace-Syscalls, die diese Sandbox benötigt. Playwright als Bibliothek startet bereits mit --no-sandbox, und dasselbe Opt-in setzt PLAYWRIGHT_MCP_SANDBOX=false für Playwright MCP, das es sonst wieder einschalten würde. Jeder andere Chromium-Launcher benötigt selbst --no-sandbox. cplt bleibt die durchsetzende Kernel-Grenze, aber ein kompromittierter Renderer erhält dann das vollständige cplt-Playwright-Profil statt Chromiums engerem Child-Profil. Siehe Cache exec und SECURITY.md.

Git commit funktioniert für jeden Agenten; ob git push über HTTPS funktioniert, hängt vom Agenten ab. Drei Voraussetzungen: HTTPS-Remotes statt SSH verwenden (git remote set-url origin https://github.com/org/repo.git, oder global umschreiben mit git config --global url."https://github.com/".insteadOf "[email protected]:"), einmal gh auth login außerhalb der Sandbox ausführen und gh auth setup-git ausführen, falls der Credential-Helper noch nicht konfiguriert ist. Push führt dann gh auth git-credential aus, was ein Token benötigt, das gh von innerhalb der Sandbox erreichen kann — das unterscheidet sich je nach Agent, siehe Git workflow. Pushes auf den Default-Branch und alle Force-Pushes werden standardmäßig vom git-Guard verweigert; pushe einen Feature-Branch. Der SSH-Agent-Socket ist blockiert, weil er jeden geladenen Key entsperrt und sich bei jedem Host authentifizieren kann, während der gh-Credential-Helper auf GitHub beschränkt ist.

Die JVM ist proxy-aware, daher muss ein internes Maven-Repository auf einer privaten IP jetzt erlaubt werden. cplt injiziert http(s).proxyHost/proxyPort in JAVA_TOOL_OPTIONS, sodass die Gradle- und Maven-Abhängigkeitsauflösung über den CONNECT-Proxy läuft und im Proxy-Log erscheint, statt ihn zu umgehen. Der SSRF-Guard des Proxys verweigert dann ein internes Nexus oder Artifactory, das in den privaten Adressraum auflöst, genau wie er es bereits für curl, npm und pip tut. Füge seinen DNS-Namen zu proxy.allow_private_domains hinzu. Eine Repository-URL, die als bloßes IP-Literal geschrieben ist (https://10.20.30.40/repository/maven-public/), kann durch keinen Key erlaubt werden — diese Prüfung läuft, bevor die Allow-List konsultiert wird —, daher benötigt ein solches Repository einen DNS-Namen. WorkerExecutor-Plugin-Forks und ein Gradle-Daemon, der außerhalb von cplt gestartet und innerhalb wiederverwendet wird, laufen nicht über den Proxy. Siehe Internal Maven/Gradle repositories on private IPs.

Gradle 9+ führt seine eigene verschachtelte Sandbox aus, und cplt schaltet sie ab. Seit Gradle 8.8 hüllt sich der Daemon in sandbox-exec (gesteuert durch GRADLE_MACOS_SANDBOX, früher die Property org.gradle.daemon.sandbox). macOS unterstützt keine verschachtelten sandbox-exec-Aufrufe, daher schlägt die innere Sandbox bei Socket-Operationen mit "Operation not permitted" fehl. cplt injiziert GRADLE_MACOS_SANDBOX=off, da es bereits Sandboxing auf Kernel-Ebene bereitstellt. Dies ist ein bekanntes Upstream-Problem, das jedes Tool trifft, das Gradle in eine äußere Sandbox einhüllt. Überschreibe mit --pass-env GRADLE_MACOS_SANDBOX, wenn du wirklich Gradles eigene Sandbox willst.

Copilot CLI 1.0.83 führt seine eigene verschachtelte Sandbox aus, und cplt schaltet sie ab. Unter Linux baut diese Sandbox einen Netzwerk-Namespace auf — slirp4netns, iptables, /dev/net/tun — und cplts seccomp-Filter verweigert das dafür benötigte unshare. cplt setzt außerdem HTTP_PROXY/HTTPS_PROXY, was in 1.0.83 eine Linux-Sandbox auf den Proxy-Egress-Pfad bringt, ob du es wolltest oder nicht, sodass die beiden bei jedem Start kollidieren. Symptom: [cplt] Starting Copilot in sandbox... und dann nichts. cplt injiziert Copilots eigenes Opt-out, COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE=unsupported; Copilot tritt für die Sitzung zurück, sagt es, und lässt dein gespeichertes sandbox.enabled unangetastet. cplt ist die Grenze, wie bei Gradle und Chromium. Überschreibe mit --pass-env COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE. Eine unternehmensverwaltete Richtlinie, die die Sandbox erfordert, überschreibt all dies — siehe Copilot CLI's own command sandbox.

Jede Auswirkung, mit den Pro-Tool-Tabellen, JVM- und Kotlin-Daemon-Hinweisen, GPG-Fehlerbehebung und den Plattformunterschieden bei privaten Registries: docs/known-impacts.md.

Limitations

macOS

• sandbox-exec ist veraltet. Apple hat es nicht entfernt, könnte es aber in einer zukünftigen macOS-Version tun.
• SBPL hat keine domainbasierte Filterung. Der optionale CONNECT-Proxy bietet stattdessen Domain-Blocking.
• SBPLs lsopen hat ebenfalls keinen Filter, daher ist --allow-browser alles von Launch Services oder nichts davon. Mit aktiviertem Flag kann der Agent jede Anwendung außerhalb der Sandbox starten, und kein Wrapper kann das einschränken — siehe docs/security.md.

Linux

• Kernel 5.13+ erforderlich, mit aktiviertem Landlock LSM.
• TCP-Port-Filterung benötigt Kernel 6.7+. Ältere Kernel erhalten nur Dateisystem-Durchsetzung.
• Landlock kann keine Unterpfade innerhalb erlaubter Pfade verweigern, daher wird .env-Lesen/Schreiben/Löschen innerhalb des Projektverzeichnisses nicht vom Kernel durchgesetzt. .git/hooks-Schreibvorgänge werden blockiert, wenn Bubblewrap aktiv ist.
• --deny-path erfordert Bubblewrap. Es wird über Mount-Masken durchgesetzt, wenn bwrap aktiv ist. Ohne es ist Landlock nur eine Allowlist und cplt warnt über das Deny, statt es anzuwenden.

Mehr: docs/security.md

Contributing

Beiträge sind willkommen.```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

Öffne ein Issue, bevor du eine große Änderung beginnst. Jeder PR muss CI bestehen (fmt, clippy, Tests).

## Referenzen

- [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md), das vollständige Sicherheitsmodell, die Bedrohungsanalyse, die Teststrategie und frühere Arbeiten
- [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)

## Lizenz

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