@kokorolx/ai-sandbox-wrapper 1.3.0 → 2.1.0

package/README.md

@@ -8,7 +8,26 @@ AI coding tools like Claude, Gemini, and Aider have full access to your filesyst
 
 **What you get:** Peace of mind using AI coding tools without risking your personal and system data.
 
-*Last updated: Thursday, January 22, 2026*
+*Last updated: Tuesday, February 3, 2026*
+
+## ✨ New in v2.1.0: Stability & Native Persistence
+
+The **v2.1.0 release** focuses on architectural stability and a more intuitive persistence model.
+
+-   ✅ **Stable Node 22 LTS**: Switched to a robust Node 22 base image for maximum compatibility and performance.
+-   ✅ **Direct Mount Persistence**: Changes made *inside* the container (logins, settings, sessions) now save directly to your host's native folders.
+-   ✅ **Cache Isolation**: Heavy caches (`node_modules`, `.npm`, `.cache`) are isolated using anonymous volumes to prevent "cache poisoning" and runtime conflicts.
+
+### Native Config Mapping
+Your tool configurations are now directly linked from your Mac/PC:
+- Host: `~/.config/opencode` ↔ Container: `/home/agent/.config/opencode`
+- Host: `~/.local/share/opencode` ↔ Container: `/home/agent/.local/share/opencode`
+
+---
+
+## ⚠️ Breaking Change: v2.0.0 - Config Directory Reorganization
+
+**Version 2.0.0** reorganized the directory structure to a tool-centric layout and introduced a unified `config.json`.
 
 ## 🛡️ Why Use This?
 
@@ -53,8 +72,15 @@ cd ai-sandbox-wrapper
 ./setup.sh
 ```
 
+**Fresh build (no Docker cache):**
+```bash
+npx @kokorolx/ai-sandbox-wrapper setup --no-cache
+# or
+./setup.sh --no-cache
+```
+
 ### Step 3: Follow the Interactive Prompts
-1. **Whitelist workspaces** - Enter the directories where you want AI tools to access (e.g., `~/projects,~/code`)
+1. **Whitelist workspaces (Optional)** - Enter directories AI tools can access, or just hit **Enter** to whitelist on-demand later.
 2. **Select tools** - Use arrow keys to move, space to select, Enter to confirm
 3. **Choose image source** - Select registry (faster) or build locally
 
@@ -64,7 +90,7 @@ cd ai-sandbox-wrapper
 source ~/.zshrc
 
 # Add your API keys (only if using tools that require them)
-nano ~/.ai-env  # Add ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.
+nano ~/.ai-sandbox/env  # Add ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.
 ```
 
 ### Step 5: Run Your First Tool
@@ -105,16 +131,16 @@ claude --version
 If you want to give AI access to more project directories later:
 ```bash
 # Add a new workspace
-echo '/path/to/new/project' >> ~/.ai-workspaces
+echo '/path/to/new/project' >> ~/.ai-sandbox/workspaces
 
 # View current allowed directories
-cat ~/.ai-workspaces
+cat ~/.ai-sandbox/workspaces
 ```
 
 ### Configure API Keys (If Needed)
 Some tools require API keys to work properly:
 ```bash
-nano ~/.ai-env
+nano ~/.ai-sandbox/env
 ```
 Then add your keys in the format: `KEY_NAME=your_actual_key_here`
 Examples:
@@ -136,7 +162,7 @@ docker pull registry.gitlab.com/kokorolee/ai-sandbox-wrapper/ai-aider:latest
 ```
 
 **Available pre-built images:**
-- `ai-base:latest` - Base image with Bun runtime
+- `ai-base:latest` - Base image with Node.js 22 LTS runtime
 - `ai-amp:latest` - Sourcegraph Amp
 - `ai-claude:latest` - Claude Code CLI
 - `ai-droid:latest` - Factory CLI
@@ -165,22 +191,34 @@ docker pull registry.gitlab.com/kokorolee/ai-sandbox-wrapper/ai-aider:latest
 |------|--------|--------------|-------------|
 | **claude** | ✅ | Native binary | Anthropic Claude Code |
 | **opencode** | ✅ | Native Go | Open-source AI coding |
-| **gemini** | ✅ | npm/Bun | Google Gemini CLI (free tier) |
+| **gemini** | ✅ | npm/Node | Google Gemini CLI (free tier) |
 | **aider** | ✅ | Python | AI pair programmer (Git-native) |
-| **kilo** | ✅ | npm/Bun | Kilo Code (500+ models) |
-| **codex** | ✅ | npm/Bun | OpenAI Codex agent |
-| **amp** | ✅ | npm/Bun | Sourcegraph Amp |
-| **qwen** | ✅ | npm/Bun | Alibaba Qwen CLI (1M context) |
+| **kilo** | ✅ | npm/Node | Kilo Code (500+ models) |
+| **codex** | ✅ | npm/Node | OpenAI Codex agent |
+| **amp** | ✅ | npm/Node | Sourcegraph Amp |
+| **qwen** | ✅ | npm/Node | Alibaba Qwen CLI (1M context) |
 | **droid** | ✅ | Custom | Factory CLI |
 
-### GUI Tools (IDE/Editor)
+> **Note:** GUI tools (VSCode, codeserver) have been removed in v2.0.1. Use your native IDE with AI tools running in the sandbox.
+
+## ⚠️ Known Issues
+
+### Native Tool Config Compatibility
+
+In v2.1.0+, tool configurations are **directly bind-mounted** from your host. This ensures 100% compatibility with your native tool settings and authentications.
+
+1. **Host Config**: `~/.config/<tool>/` or `~/.<tool>/`
+2. **Container Mount**: `/home/agent/.config/<tool>` (Automatic)
 
-| Tool | Status | Description |
-|------|--------|-------------|
-| **codeserver** | ✅ | VSCode in browser (localhost:8080) |
-| **vscode** | ⚠️ Experimental | VSCode Desktop via X11 |
-| **cursor** | 🔜 Planned | Cursor IDE sandbox |
-| **antigravity** | 🔜 Planned | Antigravity IDE sandbox |
+**Currently Supported for Direct Mount:**
+- ✅ `claude`
+- ✅ `opencode`
+- ✅ `amp`
+- ✅ `gemini`
+- ✅ `aider`
+- ... and all other supported tools.
+
+Please [open an issue](https://github.com/kokorolx/ai-sandbox-wrapper/issues) if you encounter problems with specific tools.
 
 ## 🖥️ Platform Support
 
@@ -194,62 +232,82 @@ docker pull registry.gitlab.com/kokorolee/ai-sandbox-wrapper/ai-aider:latest
 
 ## 📁 Directory Structure
 
-AI Sandbox Wrapper creates and manages the following directories in your home folder:
+AI Sandbox Wrapper creates and manages a single consolidated directory in your home folder:
 
 | Directory | Purpose | Contents |
 |-----------|---------|----------|
 | `~/bin/` | Executables | `ai-run` wrapper and symlinks to tool scripts |
-| `~/.ai-env` | API keys | Environment variables passed to containers (API keys) |
-| `~/.ai-workspaces` | Security | List of whitelisted directories AI can access |
-| `~/.ai-git-allowed` | Security | Workspaces where Git credentials are allowed |
-| `~/.ai-cache/` | Caching | Tool-specific cache directories (e.g., `~/.ai-cache/claude/`) |
-| `~/.ai-home/` | Config | Tool home directories with persistent configs |
+| `~/.ai-sandbox/` | All config | Consolidated configuration directory (see structure below) |
 | `~/.ai-images/` | Local images | Locally built Docker images (if not using registry) |
 
+### Sandbox Structure
+
+```
+~/.ai-sandbox/
+├── config.json      # Unified config (workspaces, git, networks)
+├── tools/           # Isolated sandbox environments
+│   └── <tool>/
+│       └── home/    # Sandbox home directory (excludes native configs)
+├── shared/          # Shared assets
+│   └── git/         # Shared git config and keys
+└── env              # API keys (format: KEY=value)
+```
+
+**Note:** Tools also bind-mount your **native** `~/.config/<tool>` directories for persistence.
+
 ### Key Files
 
 | File | Purpose |
 |------|---------|
-| `~/.ai-env` | API keys (format: `KEY=value`, one per line) |
-| `~/.ai-git-allowed` | Workspaces with persistent Git access (one path per line) |
-| `~/.ai-git-keys-*` | Saved SSH key selections for each workspace (md5-hashed) |
+| `~/.ai-sandbox/config.json` | Unified config (workspaces, git access, networks) |
+| `~/.ai-sandbox/env` | API keys (format: `KEY=value`, one per line) |
+| `~/.ai-sandbox/workspaces` | Legacy workspace file (fallback) |
+| `~/.ai-sandbox/git-allowed` | Legacy git-allowed file (fallback) |
 
-### Cache Structure
+## ⚙️ Configuration
 
-```
-~/.ai-cache/
-├── claude/          # Claude Code cache
-├── gemini/          # Gemini CLI cache
-├── aider/           # Aider cache
-├── git/             # Git credentials cache (when enabled)
-│   └── ssh/         # SSH keys and config for allowed workspace
-```
+### Tool-Specific Configuration
 
-### Home Structure
+Each tool has its own persistent home directory inside `~/.ai-sandbox/tools/<tool>/home/`.
 
-```
-~/.ai-home/
-├── claude/          # .claude.json and settings
-├── gemini/          # Gemini configuration
-├── aider/           # Aider config and history
-└── .gitconfig       # Git configuration (when Git access enabled)
-```
+```bash
+# View configuration paths for a specific tool (Recommended)
+npx @kokorolx/ai-sandbox-wrapper config tool claude
 
-## ⚙️ Configuration
+# View configuration content
+npx @kokorolx/ai-sandbox-wrapper config tool claude --show
+```
 
 ### API Keys
 ```bash
 # Edit environment file
-nano ~/.ai-env
+nano ~/.ai-sandbox/env
 ```
 
 ### Workspace Management
 ```bash
-# Add workspace
-echo '/path/to/project' >> ~/.ai-workspaces
+# CLI commands (recommended)
+npx @kokorolx/ai-sandbox-wrapper workspace list
+npx @kokorolx/ai-sandbox-wrapper workspace add ~/projects/my-new-app
+npx @kokorolx/ai-sandbox-wrapper workspace remove ~/old-project
+
+# Interactive menu
+npx @kokorolx/ai-sandbox-wrapper update
 
-# List workspaces
-cat ~/.ai-workspaces
+# Legacy (still works)
+echo '/path/to/project' >> ~/.ai-sandbox/workspaces
+cat ~/.ai-sandbox/workspaces
+```
+
+### Git Access Management
+```bash
+# CLI commands
+npx @kokorolx/ai-sandbox-wrapper git status
+npx @kokorolx/ai-sandbox-wrapper git enable ~/projects/myrepo
+npx @kokorolx/ai-sandbox-wrapper git disable ~/projects/myrepo
+
+# Interactive menu
+npx @kokorolx/ai-sandbox-wrapper update
 ```
 
 ### Network Configuration
@@ -274,12 +332,24 @@ Network selections are saved to `~/.ai-sandbox/config.json`:
 - **Global**: Default for all workspaces
 
 ```bash
+# CLI commands
+npx @kokorolx/ai-sandbox-wrapper network list
+npx @kokorolx/ai-sandbox-wrapper network add mynetwork --global
+npx @kokorolx/ai-sandbox-wrapper network add dev-network --workspace ~/projects/myapp
+npx @kokorolx/ai-sandbox-wrapper network remove mynetwork --global
+
 # View current config
-cat ~/.ai-sandbox/config.json
+npx @kokorolx/ai-sandbox-wrapper config show
+npx @kokorolx/ai-sandbox-wrapper config show --json
 
-# Example config structure
+# Example config.json structure (v2)
 {
-  "version": 1,
+  "version": 2,
+  "workspaces": ["/Users/you/projects/my-app"],
+  "git": {
+    "allowedWorkspaces": ["/Users/you/projects/my-repo"],
+    "keySelections": {}
+  },
   "networks": {
     "global": ["shared-services"],
     "workspaces": {
@@ -298,13 +368,13 @@ When running without the flag, saved networks are used silently:
 
 ### Environment Variables
 
-All environment variables are configured in `~/.ai-env` or passed at runtime:
+All environment variables are configured in `~/.ai-sandbox/env` or passed at runtime:
 
 #### Image Source
 Choose between locally built images or pre-built GitLab registry images:
 
 ```bash
-# Add to ~/.ai-env
+# Add to ~/.ai-sandbox/env
 
 # Use locally built images (default)
 AI_IMAGE_SOURCE=local
@@ -373,7 +443,7 @@ rails server -b 0.0.0.0
 ```
 
 #### API Keys
-Configure in `~/.ai-env`:
+Configure in `~/.ai-sandbox/env`:
 
 ```bash
 # Required for Claude tools
@@ -391,19 +461,19 @@ GOOGLE_API_KEY=AIza...
 
 ### Per-Project Config
 
-Each tool supports project-specific config files that override global settings:
+Each tool supports project-specific config files that override global settings. These files are located in your workspace and are accessible to the tool:
 
-| Tool | Project Config | Global Config Location |
-|------|----------------|------------------------|
-| Claude | `.claude.json` | `~/.claude/` |
+| Tool | Project Config | Native Global Config |
+|------|----------------|----------------------|
+| Claude | `.claude.json` | `~/.config/claude/` |
 | Gemini | `.gemini.json` | `~/.config/gemini/` |
 | Aider | `.aider.conf` | `~/.config/aider/` |
 | Opencode | `.opencode.json` | `~/.config/opencode/` |
-| Kilo | `.kilo.json` | `~/.config/kilo/` |
-| Codex | `.codex.json` | `~/.config/codex/` |
 | Amp | `.amp.json` | `~/.config/amp/` |
 
-**Priority:** Project config > Global config > Container defaults
+**Persistence:** Since v2.1.0, changes to global settings *inside* the container are automatically saved back to your **Native Global Config** on the host.
+
+**Priority:** Project config > Native Global config > Container defaults
 
 ```bash
 # Example: Project-specific Claude config
@@ -418,14 +488,15 @@ EOF
 
 ### Tool-Specific Config Locations
 
-When using global configs (not project-specific), they're stored in:
+All tool configs are consolidated under `~/.ai-sandbox/home/{tool}/`:
 
 ```
-~/.ai-home/{tool}/
+~/.ai-sandbox/home/{tool}/
 ├── .config/          # Tool configuration
 │   └── {tool}/       # Per-tool config directory
 ├── .local/share/     # Tool data (cache, sessions)
-└── .cache/           # Runtime cache
+├── .cache/           # Runtime cache
+└── .claude/          # Claude-specific (for claude tool)
 ```
 
 Each tool's config is mounted to `/home/agent/` inside the container.
@@ -516,10 +587,10 @@ Allow AI tool to access Git credentials for this workspace?
 **Managing Git access:**
 ```bash
 # View allowed workspaces
-cat ~/.ai-git-allowed
+cat ~/.ai-sandbox/git-allowed
 
 # Remove a workspace from allowed list
-nano ~/.ai-git-allowed  # Delete the line
+nano ~/.ai-sandbox/git-allowed  # Delete the line
 ```
 
 **Why this is secure:**
@@ -562,20 +633,23 @@ nano ~/.ai-git-allowed  # Delete the line
 - Reload your shell: `source ~/.zshrc`
 - Verify setup completed: check if `~/bin/ai-run` exists
 
-**"Workspaces not configured"**
-- Run setup again: `./setup.sh`
-- Make sure you entered workspace directories during setup
+**"Workspaces not configured"** (Legacy)
+- Note: This error is resolved in v2.1.0+.
+- Run setup again: `./setup.sh` or simply run an AI tool in your project folder to trigger interactive whitelisting.
+
+**"BunInstallFailedError"** (Resolved in v2.1.0)
+- This was caused by stale caches. We now use **Cache Isolation** via anonymous volumes. If you still see this, run `./setup.sh --no-cache` to force a clean build.
 
 **Tool doesn't start**
 - Check if you selected the tool during setup
 - Look for the Docker image: `docker images | grep ai-`
 
 **"Outside whitelisted workspace" error**
-- Add your current directory: `echo "$(pwd)" >> ~/.ai-workspaces`
+- Add your current directory: `echo "$(pwd)" >> ~/.ai-sandbox/workspaces`
 - Or navigate to a directory you whitelisted during setup
 
 **API key errors**
-- Check your keys in: `cat ~/.ai-env`
+- Check your keys in: `cat ~/.ai-sandbox/env`
 - Make sure keys are in format: `KEY_NAME=actual_key_value`
 
 ### Getting Help
@@ -583,9 +657,9 @@ nano ~/.ai-git-allowed  # Delete the line
 If you're still having issues:
 1. Check that Docker is running
 2. Re-run `./setup.sh` to reinstall
-3. Look at the configuration files in your home directory:
-   - `~/.ai-workspaces` - should contain your project directories
-   - `~/.ai-env` - should contain your API keys (if needed)
+3. Look at the configuration files in `~/.ai-sandbox/`:
+   - `~/.ai-sandbox/workspaces` - should contain your project directories
+   - `~/.ai-sandbox/env` - should contain your API keys (if needed)
 4. View Docker images: `docker images` to see if tools built successfully
 
 ## 📚 Quick Reference
@@ -614,15 +688,15 @@ ai-run opencode --shell  # or -s
 See [SHELL-MODE-USAGE.md](SHELL-MODE-USAGE.md) for detailed examples and use cases.
 
 ### Configuration Files
-- `~/.ai-env` - Store API keys here
-- `~/.ai-workspaces` - Whitelisted project directories
-- `~/.ai-cache/` - Tool cache (persistent)
-- `~/.ai-home/` - Tool configurations (persistent)
+- `~/.ai-sandbox/env` - Store API keys here
+- `~/.ai-sandbox/workspaces` - Whitelisted project directories
+- `~/.ai-sandbox/cache/` - Tool cache (persistent)
+- `~/.ai-sandbox/home/` - Tool configurations (persistent)
 
 ### Common Tasks
 ```bash
 # Add a new project directory to AI access
-echo '/path/to/my/new/project' >> ~/.ai-workspaces
+echo '/path/to/my/new/project' >> ~/.ai-sandbox/workspaces
 
 # Check what tools are installed
 ls ~/bin/
@@ -654,23 +728,24 @@ npx @kokorolx/ai-sandbox-wrapper clean
 **Categories:**
 | Category | Contents | Risk |
 |----------|----------|------|
-| Tool caches | `~/.ai-cache/{tool}/` | 🟢 Safe to delete |
-| Tool configs | `~/.ai-home/{tool}/` | 🟡 Loses settings |
-| Global config | `~/.ai-sandbox/`, `~/.ai-workspaces`, `~/.ai-env`, etc. | 🟡🔴 Mixed |
+| Tool caches | `~/.ai-sandbox/cache/{tool}/` | 🟢 Safe to delete |
+| Tool configs | `~/.ai-sandbox/home/{tool}/` | 🟡 Loses settings |
+| Global config | `~/.ai-sandbox/workspaces`, `~/.ai-sandbox/env`, etc. | 🟡🔴 Mixed |
+| Everything | `~/.ai-sandbox/` | 🔴 Full reset |
 
 **Example:**
 ```
 🧹 AI Sandbox Cleanup
 
 What would you like to clean?
-  1. Tool caches (~/.ai-cache/) - Safe to delete
-  2. Tool configs (~/.ai-home/) - Loses settings
+  1. Tool caches (~/.ai-sandbox/cache/) - Safe to delete
+  2. Tool configs (~/.ai-sandbox/home/) - Loses settings
   3. Global config files - Loses preferences
-  4. All of the above
+  4. Everything (~/.ai-sandbox/) - Full reset
 
 Enter selection (or 'q' to quit): 1
 
-📁 Tool Caches (~/.ai-cache/)
+📁 Tool Caches (~/.ai-sandbox/cache/)
 
 Select tools to clear:
   1. claude/ (45.2 MB)
@@ -679,13 +754,13 @@ Select tools to clear:
 Enter selection (comma-separated, 'all', or 'b' to go back): 1
 
 You are about to delete:
-  - ~/.ai-cache/claude/ (45.2 MB)
+  - ~/.ai-sandbox/cache/claude/ (45.2 MB)
 
 Total: 45.2 MB
 
 Type 'yes' to confirm: yes
 
-✓ Deleted ~/.ai-cache/claude/
+✓ Deleted ~/.ai-sandbox/cache/claude/
 
 Deleted 1 items, freed 45.2 MB
 ```