Use a claude and gemini compatible agentic sandbox

CLAUDE.md

@@ -0,0 +1 @@
+GEMINI.md

CONTRIBUTING.md

@@ -154,32 +154,25 @@ This library is an active proof of concept and is subject to change.
 
 ## AI Coding Sandboxes
 
-The repository includes Docker-based sandbox scripts for AI coding assistants.
-These mount the project into a container with all build dependencies
+The repository includes a Docker-based sandbox script for AI coding
+assistants. It mounts the project into a container with all build dependencies
 pre-installed, providing an isolated environment for AI-assisted development.
 
-### Claude Code
+### Usage
 
 ```bash
-export ANTHROPIC_API_KEY='your_key_here'
-./scripts/claude-sandbox.sh
+./scripts/agentic-sandbox.sh <agent> [options]
 ```
 
-Use `--rebuild-docker` to rebuild the container image and `--update-claude` to
-update the Claude Code CLI inside the container.
+where `<agent>` is either `claude` or `gemini`.
 
-### Gemini CLI
+### Options
 
-```bash
-export GEMINI_API_KEY='your_key_here'
-./scripts/gemini-sandbox.sh
-```
-
-Use `--rebuild-docker` to rebuild the container image and `--update-gemini` to
-update the Gemini CLI inside the container.
-
-Both scripts accept `-v` for verbose output. The Docker image is defined in
-`docker/Dockerfile`.
+| Flag | Description |
+|------|-------------|
+| `--rebuild-docker` | Rebuild the Docker image before starting. |
+| `--update` | Update the agent CLI to the latest version before running. |
+| `-v`, `--verbose` | Enable verbose logging. |
 
 ### Using pre-commit Locally to run Github Workflow checks
 

docker/Dockerfile

@@ -1,7 +1,6 @@
-# Dockerfile for Ubuntu 24.04 with C++ development tools.
 FROM ubuntu:24.04
 
-# Install gcc, clang and some supporting tools for downloading/installing later tools.
+# Install base tools and C++ development tools.
 RUN apt-get update && apt-get install -y --no-install-recommends \
     cmake \
     curl \
@@ -33,41 +32,33 @@ RUN ARCH=$(dpkg --print-architecture) && \
     && chmod +x /usr/local/bin/bazelisk \
     && ln -s /usr/local/bin/bazelisk /usr/local/bin/bazel
 
-# Create non-root user
+# Create non-root user.
 RUN useradd -m -s /bin/bash vscode \
     && mkdir -p /workspace \
     && chown vscode:vscode /workspace
 
-# Install Node.js (required for Gemini CLI)
+# Install Node.js (required for both Gemini CLI and Claude Code).
 RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
     && apt-get install -y --no-install-recommends nodejs \
     && rm -rf /var/lib/apt/lists/*
 
-# Set up npm to install globally in vscode's home directory
-ENV NPM_CONFIG_PREFIX=/home/vscode/.npm-global
-ENV PATH="/home/vscode/.npm-global/bin:${PATH}"
-
-# Switch to non-root user
+# Switch to non-root user.
 USER vscode
 WORKDIR /workspace
 
-# Install Gemini CLI and Claude Code CLI
-RUN mkdir -p /home/vscode/.npm-global \
-    && npm install -g @google/gemini-cli \
-    && npm install -g @anthropic-ai/claude-code
+# Configure npm for user-local global installs.
+ENV NPM_CONFIG_PREFIX=/home/vscode/.npm-global
+ENV PATH="/home/vscode/.npm-global/bin:/home/vscode/.local/bin:/usr/local/bin:${PATH}"
+RUN mkdir -p /home/vscode/.npm-global
+
+# Install both AI agent CLIs for compatibility with existing tooling that
+# may invoke either `gemini` or `claude`.
+RUN npm install -g @google/gemini-cli @anthropic-ai/claude-code
 
-# Set up uv and Python environment
+# Set up uv and Python environment.
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# Set up environment variables
-ENV PATH="/home/vscode/.local/bin:/usr/local/bin:${PATH}"
 ENV UV_PROJECT_ENVIRONMENT="/home/vscode/.venv"
 
-# Pre-configure Gemini CLI
-RUN mkdir -p /home/vscode/.gemini \
-    && echo '{"/workspace": "TRUST_FOLDER"}' > /home/vscode/.gemini/trustedFolders.json \
-    && echo '{"security": {"auth": {"selectedType": "gemini-api-key"}}}' > /home/vscode/.gemini/settings.json
-
-# Pre-configure Claude Code CLI
-RUN mkdir -p /home/vscode/.claude \
-    && echo '{"permissions": {"allow": ["Bash(*)", "Read(*)", "Write(*)", "Edit(*)", "Glob(*)", "Grep(*)"]}}' > /home/vscode/.claude/settings.json
+# Agent config dirs (~/.gemini / ~/.claude) are mounted from the host at runtime
+# to persist auth state between sessions. Default config files are seeded by the launch
+# script before the mount, so image-side preconfiguration is not needed here.

scripts/agentic-sandbox.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Script to run an AI agent (Gemini CLI or Claude Code) in a Docker sandbox."""
+
+import argparse
+import os
+import subprocess
+import sys
+
+
+def _seed_config_file(path: str, content: bytes) -> None:
+    """Create path with content and mode 0o600, skipping silently if it already exists."""
+    try:
+        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return
+    try:
+        os.write(fd, content)
+    finally:
+        os.close(fd)
+
+
+def main() -> None:
+    """Provide the main entry point for the agentic sandbox script."""
+    parser = argparse.ArgumentParser(
+        description="Run an AI agent (gemini or claude) in a Docker sandbox."
+    )
+    parser.add_argument(
+        "agent",
+        choices=["gemini", "claude"],
+        help="AI agent to run inside the sandbox.",
+    )
+    parser.add_argument(
+        "--update",
+        action="store_true",
+        help="Update the agent CLI inside the container before running.",
+    )
+    parser.add_argument(
+        "--rebuild-docker", action="store_true", help="Rebuild the Docker image."
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose logging."
+    )
+
+    args = parser.parse_args()
+
+    def log(msg: str) -> None:
+        """Log a message if verbose mode is enabled."""
+        if args.verbose:
+            print(msg)
+
+    project_root = subprocess.check_output(
+        ["git", "rev-parse", "--show-toplevel"], text=True
+    ).strip()
+
+    image_name = "cc-protocol-sandbox"
+
+    image_exists = (
+        subprocess.run(
+            ["docker", "image", "inspect", image_name],
+            capture_output=True,
+        ).returncode
+        == 0
+    )
+
+    if args.rebuild_docker or not image_exists:
+        log(f"--- Building Docker Sandbox: {image_name} ---")
+        subprocess.check_call(
+            [
+                "docker",
+                "build",
+                "-t",
+                image_name,
+                "-f",
+                os.path.join(project_root, "docker/Dockerfile"),
+                project_root,
+            ]
+        )
+
+    log(f"--- Starting Sandboxed {args.agent.capitalize()} Session ---")
+    log(f"Note: Your current directory {project_root} is mounted to /workspace")
+
+    if args.agent == "gemini":
+        npm_package = "@google/gemini-cli"
+        agent_cmd = "gemini"
+    else:
+        npm_package = "@anthropic-ai/claude-code"
+        agent_cmd = "claude --dangerously-skip-permissions"
+
+    if args.update:
+        container_cmd = (
+            f"export NPM_CONFIG_PREFIX=~/.npm-global && "
+            f"export PATH=~/.npm-global/bin:$PATH && "
+            f"npm install -g {npm_package}@latest && {agent_cmd}"
+        )
+    else:
+        container_cmd = agent_cmd
+
+    run_args = [
+        "docker",
+        "run",
+        "-it",
+        "--rm",
+        "-v",
+        f"{project_root}:/workspace",
+    ]
+
+    if args.agent == "gemini":
+        gemini_config_dir = os.path.expanduser("~/.gemini")
+        os.makedirs(gemini_config_dir, mode=0o700, exist_ok=True)
+        # Seed default config files if missing so they are accessible inside the
+        # container.
+        # Use os.open with restrictive permissions to avoid exposing credentials to
+        # other local users on multi-user systems.
+        _seed_config_file(
+            os.path.join(gemini_config_dir, "trustedFolders.json"),
+            b'{"/workspace": "TRUST_FOLDER"}',
+        )
+        _seed_config_file(
+            os.path.join(gemini_config_dir, "settings.json"),
+            b'{"selectedAuthType": "oauth-personal"}',
+        )
+        run_args.extend(["-v", f"{gemini_config_dir}:/home/vscode/.gemini"])
+    else:
+        host_claude_dir = os.path.expanduser("~/.claude")
+        host_claude_json = os.path.expanduser("~/.claude.json")
+        os.makedirs(host_claude_dir, mode=0o700, exist_ok=True)
+        # Ensure the file exists on the host so Docker doesn't create it as a directory.
+        # Use os.open with restrictive permissions to avoid exposing credentials to
+        # other local users on multi-user systems.
+        if os.path.exists(host_claude_json):
+            if not os.path.isfile(host_claude_json):
+                sys.exit(
+                    f"Expected {host_claude_json} to be a regular file, but found a "
+                    "different filesystem object. Remove or rename it and rerun."
+                )
+        else:
+            _seed_config_file(host_claude_json, b"")
+        run_args.extend(["-v", f"{host_claude_dir}:/home/vscode/.claude"])
+        run_args.extend(["-v", f"{host_claude_json}:/home/vscode/.claude.json"])
+
+    if "TERM" in os.environ:
+        run_args.extend(["-e", f"TERM={os.environ['TERM']}"])
+    if "COLORTERM" in os.environ:
+        run_args.extend(["-e", f"COLORTERM={os.environ['COLORTERM']}"])
+
+    run_args.extend([image_name, "bash", "-c", container_cmd])
+
+    try:
+        subprocess.run(run_args, check=True)
+    except subprocess.CalledProcessError as e:
+        sys.exit(e.returncode)
+
+
+if __name__ == "__main__":
+    main()

scripts/claude-sandbox.sh → scripts/agentic-sandbox.sh

@@ -7,4 +7,4 @@ WORKSPACE_ROOT=$(git rev-parse --show-toplevel)
 
 # Change directory to the workspace root and run the python script
 cd "$WORKSPACE_ROOT"
-uv run scripts/claude-sandbox.py "$@"
+uv run scripts/agentic-sandbox.py "$@"