@kokorolx/ai-sandbox-wrapper 2.1.0 → 2.2.0

package/README.md

@@ -10,6 +10,14 @@ AI coding tools like Claude, Gemini, and Aider have full access to your filesyst
 
 *Last updated: Tuesday, February 3, 2026*
 
+## ✨ New in v2.2.0: Clipboard Fixes & Screenshot Detection
+
+The **v2.2.0 release** solves the "air-gap" problem for text copying and streamlines screenshot workflows.
+
+-   ✅ **OSC 52 Clipboard Support**: Copy text from inside Linux containers directly to your macOS clipboard (works over SSH too!).
+-   ✅ **Auto-Detect Screenshot Folder**: Automatically finds where your Mac saves screenshots and offers to whitelist it. No more permission errors when dragging images into AI tools.
+-   ✅ **Seamless Drag & Drop**: Just drag screenshots into the terminal window.
+
 ## ✨ New in v2.1.0: Stability & Native Persistence
 
 The **v2.1.0 release** focuses on architectural stability and a more intuitive persistence model.

package/bin/ai-run

@@ -334,6 +334,52 @@ fi
 # Set AI_IMAGE_SOURCE=registry in ~/.ai-env to use pre-built images
 AI_IMAGE_SOURCE="${AI_IMAGE_SOURCE:-local}"
 
+# ============================================================================
+# SCREENSHOT DIRECTORY DETECTION (macOS Only)
+# ============================================================================
+if [[ "$(uname)" == "Darwin" ]] && [[ -t 0 ]]; then
+  # 1. Detect location (default to Desktop if key missing)
+  SCREENSHOT_DIR=$(defaults read com.apple.screencapture location 2>/dev/null || echo "$HOME/Desktop")
+  # Expand tilde if present
+  SCREENSHOT_DIR="${SCREENSHOT_DIR/#\~/$HOME}"
+
+  # 2. Check if valid directory
+  if [[ -d "$SCREENSHOT_DIR" ]]; then
+    
+    # 3. Check if ALREADY whitelisted (exact match or parent)
+    IS_WHITELISTED=false
+    while IFS= read -r ws; do
+      # Check if screenshot dir IS a workspace, or IS INSIDE a workspace
+      if [[ "$SCREENSHOT_DIR" == "$ws" ]] || [[ "$SCREENSHOT_DIR" == "$ws"/* ]]; then
+        IS_WHITELISTED=true
+        break
+      fi
+    done < <(read_workspaces)
+
+    # 4. Prompt if not whitelisted
+    if [[ "$IS_WHITELISTED" == "false" ]]; then
+      echo ""
+      echo "📸 Screenshot Directory Detected"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo "Location: $SCREENSHOT_DIR"
+      echo "Status:   Not whitelisted"
+      echo ""
+      echo "Whitelisting this folder allows you to drag & drop screenshots into AI tools."
+      echo ""
+      # Use /dev/tty to ensure we read from user even if stdin is redirected
+      read -p "Whitelist screenshots folder? [y/N]: " CONFIRM_SS < /dev/tty
+      
+      if [[ "$CONFIRM_SS" =~ ^[Yy]$ ]]; then
+        add_workspace "$SCREENSHOT_DIR"
+        echo "✅ Added to whitelist."
+      else
+        echo "❌ Skipped."
+      fi
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    fi
+  fi
+fi
+
 if [[ "$AI_IMAGE_SOURCE" == "registry" ]]; then
   IMAGE="registry.gitlab.com/kokorolee/ai-sandbox-wrapper/ai-${TOOL}:latest"
 else
@@ -1067,6 +1113,58 @@ else
   fi
 fi
 
+# ============================================================================
+# DISPLAY & CLIPBOARD CONFIGURATION
+# ============================================================================
+detect_display_config() {
+  local detected_flags=""
+  local has_display=false
+
+  # 1. X11 Detection
+  if [[ -n "$DISPLAY" ]]; then
+    has_display=true
+    detected_flags="$detected_flags -e DISPLAY=$DISPLAY"
+
+    # Mount X11 socket (common on Linux/macOS with XQuartz)
+    if [[ -d "/tmp/.X11-unix" ]]; then
+      detected_flags="$detected_flags -v /tmp/.X11-unix:/tmp/.X11-unix:rw"
+    fi
+
+    # Handle XAuthority for authentication
+    if [[ -f "$HOME/.Xauthority" ]]; then
+      # Mount read-only for security
+      # Mount to /tmp/.Xauthority to avoid conflict with /home/agent bind mount
+      detected_flags="$detected_flags -e XAUTHORITY=/tmp/.Xauthority -v $HOME/.Xauthority:/tmp/.Xauthority:ro"
+    fi
+
+    # Since we have X11, prefer it over Wayland to avoid clipboard issues in mixed environments
+    # (Many Go apps like atotto/clipboard work better with xclip/X11 than wl-copy/Wayland in Docker)
+    echo "$detected_flags"
+    return
+  fi
+
+  # 2. Wayland Detection
+  if [[ -n "$WAYLAND_DISPLAY" ]]; then
+    has_display=true
+    detected_flags="$detected_flags -e WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
+
+    # Handle XDG_RUNTIME_DIR (needed for Wayland sockets)
+    if [[ -n "$XDG_RUNTIME_DIR" ]]; then
+      # Map host runtime dir to container's /run/user/1001 (agent UID)
+      # ensuring the container can access the socket
+      local container_runtime_dir="/run/user/1001"
+      detected_flags="$detected_flags -e XDG_RUNTIME_DIR=$container_runtime_dir -v $XDG_RUNTIME_DIR:$container_runtime_dir:rw"
+    fi
+  fi
+
+  # Debug log if no display detected (only if debug enabled)
+  if [[ "$has_display" == "false" && "${AI_RUN_DEBUG:-}" == "1" ]]; then
+    echo "🔧 Debug: No display server detected (DISPLAY/WAYLAND_DISPLAY unset). Clipboard integration disabled." >&2
+  fi
+
+  echo "$detected_flags"
+}
+
 # Generate container name based on tool and folder
 # Format: {tool}-{sanitized_folder_name}-{random_suffix}
 generate_container_name() {
@@ -1208,6 +1306,9 @@ if [[ "$TOOL" == "opencode" ]]; then
   CACHE_MOUNTS="-v /home/agent/.npm -v /home/agent/.cache -v /home/agent/.opencode/node_modules"
 fi
 
+# Detect display configuration (clipboard integration)
+DISPLAY_FLAGS=$(detect_display_config)
+
 docker run $CONTAINER_NAME --rm $TTY_FLAGS \
   --init \
   --platform "$PLATFORM" \
@@ -1218,6 +1319,7 @@ docker run $CONTAINER_NAME --rm $TTY_FLAGS \
   $GIT_MOUNTS \
   $NETWORK_OPTIONS \
   $CACHE_MOUNTS \
+  $DISPLAY_FLAGS \
   $HOST_ACCESS_ARGS \
   $PORT_MAPPINGS \
   -v "$HOME_DIR":/home/agent \

package/dockerfiles/amp/Dockerfile

@@ -0,0 +1,17 @@
+FROM ai-base:latest
+
+# Switch to root only for installing bun globally (needed for the system)
+USER root
+RUN npm install -g bun
+USER agent
+
+# Install Amp into user directory
+RUN mkdir -p /home/agent/lib/amp && \
+    cd /home/agent/lib/amp && \
+    bun init -y && \
+    bun add @sourcegraph/amp
+
+# Add the node_modules .bin to PATH
+ENV PATH="/home/agent/lib/amp/node_modules/.bin:${PATH}"
+
+ENTRYPOINT ["amp"]

package/dockerfiles/base/Dockerfile

@@ -0,0 +1,47 @@
+FROM node:22-bookworm-slim
+
+ARG AGENT_UID=1001
+
+# Install common dependencies
+# Note: python3-venv is needed for many tools, unzip for some installers
+RUN apt-get update && apt-get install -y --no-install-recommends     git     curl     ssh     ca-certificates     jq     python3     python3-pip     python3-venv     python3-dev     python3-setuptools     build-essential     libopenblas-dev     pipx     unzip     xclip     wl-clipboard     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh     && rm -rf /var/lib/apt/lists/*     && pipx ensurepath
+
+# Install pnpm globally using npm (not bun, for stability)
+RUN npm install -g pnpm
+
+# Install TypeScript and LSP tools using npm
+RUN npm install -g typescript typescript-language-server
+
+# Verify installations
+RUN node --version && npm --version && pnpm --version && tsc --version
+
+# Install additional tools (if selected)
+RUN PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install specify-cli --pip-args="git+https://github.com/github/spec-kit.git" && \
+    chmod +x /usr/local/bin/specify && \
+    ln -sf /usr/local/bin/specify /usr/local/bin/specify-cli
+RUN mkdir -p /usr/local/lib/uipro-cli && \
+    cd /usr/local/lib/uipro-cli && \
+    npm init -y && \
+    npm install uipro-cli && \
+    ln -sf /usr/local/lib/uipro-cli/node_modules/.bin/uipro /usr/local/bin/uipro && \
+    ln -sf /usr/local/bin/uipro /usr/local/bin/uipro-cli && \
+    chmod -R 755 /usr/local/lib/uipro-cli && \
+    chmod +x /usr/local/bin/uipro
+RUN mkdir -p /usr/local/lib/openspec && \
+    cd /usr/local/lib/openspec && \
+    npm init -y && \
+    npm install @fission-ai/openspec && \
+    ln -sf /usr/local/lib/openspec/node_modules/.bin/openspec /usr/local/bin/openspec && \
+    chmod -R 755 /usr/local/lib/openspec && \
+    chmod +x /usr/local/bin/openspec
+
+# Create workspace
+WORKDIR /workspace
+
+# Non-root user for security
+# Non-root user for security (match host UID)
+RUN useradd -m -u ${AGENT_UID} -d /home/agent agent && \
+    mkdir -p /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config && \
+    chown -R agent:agent /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config /workspace
+USER agent
+ENV HOME=/home/agent

package/dockerfiles/opencode/Dockerfile

@@ -0,0 +1,10 @@
+FROM ai-base:latest
+
+USER root
+# Install OpenCode using official native installer
+RUN curl -fsSL https://opencode.ai/install | bash && \
+    mv /home/agent/.opencode/bin/opencode /usr/local/bin/opencode && \
+    rm -rf /home/agent/.opencode
+
+USER agent
+ENTRYPOINT ["opencode"]

package/lib/install-amp.sh

@@ -14,14 +14,21 @@ mkdir -p "$HOME/.ai-sandbox/tools/$TOOL/home"
 # Create Dockerfile (extends base image for faster builds)
 cat <<'EOF' > "dockerfiles/$TOOL/Dockerfile"
 FROM ai-base:latest
+
+# Switch to root only for installing bun globally (needed for the system)
 USER root
-# Install Amp globally into a persistent directory (not shadowed by home)
-RUN mkdir -p /usr/local/lib/amp && \
-    cd /usr/local/lib/amp && \
-    bun init -y && \
-    bun add @sourcegraph/amp && \
-    ln -s /usr/local/lib/amp/node_modules/.bin/amp /usr/local/bin/amp
+RUN npm install -g bun
 USER agent
+
+# Install Amp into user directory
+RUN mkdir -p /home/agent/lib/amp && \
+    cd /home/agent/lib/amp && \
+    bun init -y && \
+    bun add @sourcegraph/amp
+
+# Add the node_modules .bin to PATH
+ENV PATH="/home/agent/lib/amp/node_modules/.bin:${PATH}"
+
 ENTRYPOINT ["amp"]
 EOF
 

package/lib/install-base.sh

@@ -126,6 +126,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libopenblas-dev \
     pipx \
     unzip \
+    xclip \
+    wl-clipboard \
     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh \
     && rm -rf /var/lib/apt/lists/* \
     && pipx ensurepath

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokorolx/ai-sandbox-wrapper",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Docker-based security sandbox for AI coding agents. Isolate Claude, Gemini, Aider, and other AI tools from your host system.",
   "keywords": [
     "ai",