@kokorolx/ai-sandbox-wrapper 2.4.0 → 2.7.0

package/README.md

@@ -4,25 +4,57 @@
 
 Protect your SSH keys, API tokens, and system files while using AI tools that need filesystem access.
 
-*Last updated: February 6, 2026*
+*Last updated: February 25, 2026*
 
-## ✨ New in v2.3.0-beta: Web Mode & Port Exposure
+---
 
-- **Web Auto-Detection**: `opencode web` automatically exposes port 4096 and injects `--hostname 0.0.0.0`
-- **`--expose` Flag**: New way to expose ports (replaces deprecated `PORT` env var)
-- **Port Conflict Detection**: Fails fast if port is already in use
+## 📑 Table of Contents
+
+- [What's New](#-whats-new)
+- [Why Use This?](#️-why-use-this)
+- [Quick Start](#-quick-start)
+- [Configuration](#️-configuration)
+  - [API Keys](#api-keys)
+  - [Workspaces](#workspaces)
+  - [Port Exposure](#port-exposure)
+  - [Server Authentication](#server-authentication)
+  - [Network Access](#network-access)
+  - [Git Access](#git-access)
+  - [Clipboard](#clipboard)
+- [Directory Structure](#-directory-structure)
+- [Security Model](#-security-model)
+- [Quick Reference](#-quick-reference)
+- [Troubleshooting](#-troubleshooting)
+- [Other Tools](#-other-tools)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+---
+
+## ✨ What's New
+
+### v2.7.0: Git Fetch-Only Mode & Bundled Skills
+
+- **Git Fetch-Only**: Allow git fetch/pull but block push — perfect for AI agents that should read but not write
+- **Bundled Skills**: RTK token optimizer skills auto-installed for OpenCode users
+- **SSH Config Fix**: Resolved crash during git credential setup
 
 ```bash
-# Web mode - automatic port exposure
-opencode web
+# Fetch-only mode (no push allowed)
+opencode --git-fetch
 
-# Custom port
-opencode web --port 8080
+# Or select from interactive menu:
+#   4) Fetch only - allow once (no push, this session)
+#   5) Fetch only - always for this workspace (no push)
 
-# Expose additional ports
-opencode --expose 3000,5555 web
+# Manage via CLI
+npx @kokorolx/ai-sandbox-wrapper git fetch-only ~/projects/myrepo
+npx @kokorolx/ai-sandbox-wrapper git full ~/projects/myrepo
+npx @kokorolx/ai-sandbox-wrapper git status
 ```
 
+---
+
 ## 🛡️ Why Use This?
 
 | Without Sandbox | With AI Sandbox |
@@ -32,6 +64,8 @@ opencode --expose 3000,5555 web
 | Host environment exposed | ✅ API keys passed explicitly |
 | Runs with your permissions | ✅ Non-root, CAP_DROP=ALL |
 
+---
+
 ## 🚀 Quick Start
 
 **Prerequisites:** Docker Desktop (macOS/Windows) or Docker Engine (Linux)
@@ -49,9 +83,12 @@ opencode
 
 During setup: select **opencode**, choose registry images (faster), whitelist your project directories.
 
+---
+
 ## ⚙️ Configuration
 
 ### API Keys
+
 ```bash
 nano ~/.ai-sandbox/env
 ```
@@ -61,6 +98,7 @@ OPENAI_API_KEY=sk-...
 ```
 
 ### Workspaces
+
 ```bash
 npx @kokorolx/ai-sandbox-wrapper workspace add ~/projects/my-app
 # Or: echo '/path/to/project' >> ~/.ai-sandbox/workspaces
@@ -94,7 +132,7 @@ Output:
 🌐 Web UI available at http://localhost:4096
 ```
 
-### Server Authentication (OpenCode web/serve)
+### Server Authentication
 
 Control authentication for OpenCode web server:
 
@@ -137,10 +175,93 @@ Git credentials are **not** shared by default. When you run a tool, you'll be pr
 ```
 🔐 Git Access Control
   1) Yes, allow once
-  2) Yes, always allow for this workspace  
+  2) Yes, always allow for this workspace
   3) No, keep Git disabled (secure default)
+  4) Fetch only - allow once (no push, this session)
+  5) Fetch only - always for this workspace (no push)
 ```
 
+**Fetch-only mode** allows `git fetch`, `git pull`, `git clone` but blocks `git push`. Uses git's `pushInsteadOf` config — no network restrictions needed.
+
+```bash
+# Force fetch-only via flag
+opencode --git-fetch
+
+# Manage via CLI
+npx @kokorolx/ai-sandbox-wrapper git fetch-only ~/projects/myrepo
+npx @kokorolx/ai-sandbox-wrapper git full ~/projects/myrepo
+```
+
+### Clipboard
+
+Clipboard access in containers requires a terminal that supports **OSC52** protocol.
+
+**Supported terminals:** iTerm2, Warp, Kitty, Alacritty, WezTerm, Windows Terminal, Ghostty
+
+**Not supported:** GNOME Terminal, VS Code Terminal, Tilix, Terminator
+
+Test if your terminal supports clipboard:
+```bash
+printf "\033]52;c;$(printf "test" | base64)\a"
+# Press Cmd+V / Ctrl+V - if you see "test", it works
+```
+
+📖 **Full details:** [CLIPBOARD_SUPPORT.md](CLIPBOARD_SUPPORT.md)
+
+### MCP Tools (Browser Automation)
+
+During setup, you can optionally install MCP servers for AI agent browser automation:
+
+| Tool | Maintainer | Features | Size |
+|------|------------|----------|------|
+| **Chrome DevTools MCP** | Google | Performance profiling, Core Web Vitals, detailed console/network inspection | ~400MB |
+| **Playwright MCP** | Microsoft | Multi-browser (Chromium), TypeScript code generation, vision mode | ~300MB |
+
+After installation, configure your MCP client (e.g., OpenCode) to use them:
+
+**`~/.config/opencode/opencode.json`:**
+```json
+{
+  "mcp": {
+    "chrome-devtools": {
+      "type": "local",
+      "command": [
+        "chrome-devtools-mcp",
+        "--headless",
+        "--isolated",
+        "--executablePath", "/opt/chromium",
+        "--chromeArg=--no-sandbox",
+        "--chromeArg=--disable-setuid-sandbox"
+      ]
+    },
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx", "@playwright/mcp@latest",
+        "--headless",
+        "--browser", "chromium",
+        "--no-sandbox"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** The `--no-sandbox` flags are required when running in Docker containers. This is safe because the container itself provides isolation.
+
+### Bundled Skills (OpenCode)
+
+OpenCode containers auto-install these skills on first run (existing skills are never overwritten):
+
+| Skill | Description |
+|-------|-------------|
+| `rtk` | Command reference for RTK token optimizer (60-90% token savings) |
+| `rtk-setup` | Persistent RTK enforcement — updates AGENTS.md and propagates to subagents |
+
+Skills are copied to `~/.config/opencode/skills/` and available immediately.
+
+---
+
 ## 📁 Directory Structure
 
 ```
@@ -156,6 +277,8 @@ Native configs are bind-mounted:
 - `~/.config/opencode` ↔ `/home/agent/.config/opencode`
 - `~/.local/share/opencode` ↔ `/home/agent/.local/share/opencode`
 
+---
+
 ## 🔐 Security Model
 
 ```
@@ -177,6 +300,8 @@ Native configs are bind-mounted:
 └─────────────────────────────────────────────────┘
 ```
 
+---
+
 ## 📚 Quick Reference
 
 ```bash
@@ -192,11 +317,16 @@ opencode -e 3000,4000         # Multiple ports
 # Network
 opencode -n mynetwork         # Join Docker network
 
+# Git fetch-only
+opencode --git-fetch            # Fetch only (no push)
+
 # Management
 npx @kokorolx/ai-sandbox-wrapper workspace list
 npx @kokorolx/ai-sandbox-wrapper clean
 ```
 
+---
+
 ## ❓ Troubleshooting
 
 | Issue | Solution |
@@ -205,6 +335,9 @@ npx @kokorolx/ai-sandbox-wrapper clean
 | `Outside whitelisted workspace` | `echo "$(pwd)" >> ~/.ai-sandbox/workspaces` |
 | Port already in use | Stop the process or use different port |
 | Docker not found | Install and start Docker Desktop |
+| Clipboard not working | Use OSC52-compatible terminal. See [CLIPBOARD_SUPPORT.md](CLIPBOARD_SUPPORT.md) |
+
+---
 
 ## 📦 Other Tools
 
@@ -212,10 +345,14 @@ This sandbox also supports **Claude, Gemini, Aider, Kilo, Codex, Amp, Qwen**, an
 
 See [TOOLS.md](TOOLS.md) for the full list and tool-specific configuration.
 
+---
+
 ## 🤝 Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+---
+
 ## 📝 License
 
 MIT