rafal-k/clavinculis

Was macht clavinculis?

Sandbox-Wrapper für Claude Code und OpenCode mit bubblewrap (bwrap) unter Linux, der über das Betriebssystem erzwungenen Dateisystemzugriff nur auf das Repository ermöglicht.

Beschreibung

clavinculis ist ein Wrapper-Skript, das einen KI-Assistenten (Claude Code oder OpenCode) in einer Bubblewrap-Sandbox ausführt. Es schränkt den Dateisystemzugriff des Assistenten auf das aktuelle Repository ein – mit anderen Worten: Der Assistent kann nur Dateien innerhalb des aktuellen Arbeitsverzeichnisses lesen, schreiben und ausführen.

Repository-Info

• GitHub: rafal-k/clavinculis
• Lizenz: MIT

Voraussetzungen

• Linux-Betriebssystem (getestet auf Ubuntu, Fedora, Arch)
• bubblewrap (Paketname: bubblewrap unter Ubuntu/Debian, bubblewrap unter Fedora, bubblewrap unter Arch)
• bash
• Installation von Claude Code (npm install -g @anthropic-ai/claude-code) oder OpenCode (siehe deren Installationsanleitung)

Verwendung

Schnellstart

git clone https://github.com/rafal-k/clavinculis.git
cd clavinculis

# Claude Code ausführen
./claude-code.sh

# OpenCode ausführen
./opencode.sh

Das Ausführen eines dieser Skripte startet den entsprechenden KI-Assistenten in einer Bubblewrap-Sandbox mit Zugriff nur auf das aktuelle Verzeichnis.

Beispiel-Workflow

1. Repository klonen:

   git clone <repo-url>
   cd <repo>
   

2. Wrapper ausführen:

   /path/to/clavinculis/claude-code.sh
   

3. KI-Assistent nutzen: Der Assistent kann Dateien sehen, lesen und schreiben – aber nur, wenn sie innerhalb des geklonten Repositorys liegen.

Funktionsweise

Die Wrapper-Skripte (claude-code.sh und opencode.sh) verwenden bwrap, um einen Befehl auszuführen:

bwrap
  --ro-bind / / \
  --tmpfs /home \
  --tmpfs /tmp \
  --tmpfs /var \
  --tmpfs /run \
  --proc /proc \
  --dev /dev \
  --bind $PWD $PWD \
  --chdir $PWD \
  --unshare-net \
  $COMMAND --noninteractive

Erklärung:

• --ro-bind / / mountet die gesamte Root-Dateisystem-Hierarchie schreibgeschützt.
• --tmpfs /home, --tmpfs /tmp, --tmpfs /var und --tmpfs /run überschreiben diese Verzeichnisse mit leeren, temporären Dateisystemen.
• --proc /proc und --dev /dev stellen /proc und /dev bereit.
• --bind $PWD $PWD – dies ist der wichtigste Teil: Das aktuelle Arbeitsverzeichnis wird beschreibbar gebunden. Der Assistent kann Dateien darin lesen, schreiben und ausführen.
• --chdir $PWD setzt das Arbeitsverzeichnis auf das aktuelle Verzeichnis.
• --unshare-net deaktiviert den Netzwerkzugriff (optional, aber um weitere Sicherheit zu erhöhen).
• $COMMAND --noninteractive führt den KI-Assistenten im nicht-interaktiven Modus aus (erforderlich für Claude Code).

Dies bedeutet, dass der KI-Assistent nur im aktuellen Repository lesen und schreiben kann. Er kann nicht auf /home, /tmp oder andere Teile des Systems zugreifen.

Sicherheitshinweise

• Der Netzwerkzugriff ist standardmäßig deaktiviert (--unshare-net). Wenn der KI-Assistent Internetzugriff benötigt (z.B. um Pakete zu installieren), entfernen Sie --unshare-net aus den Skripten.
• Die Sandbox verlässt sich auf bubblewrap, ein SUID-Binary. Um sicherzugehen, überprüfen Sie, ob bwrap auf Ihrem System installiert und richtig konfiguriert ist.
• Obwohl die Sandbox den Dateisystemzugriff erheblich einschränkt, ist sie nicht narrensicher. Stellen Sie sicher, dass Sie vertrauenswürdigen KI-Assistenten in der Sandbox ausführen.

Deinstallation

Löschen Sie einfach das clavinculis-Repository:

rm -rf /path/to/clavinculis

Es werden keine systemweiten Änderungen vorgenommen.

Lizenz

MIT

---

Erstellt mit ❤️ für sichere KI-gestützte Entwicklung.