sandboxbox 2.0.4 → 2.0.7

package/CLAUDE.md

@@ -0,0 +1,138 @@
+# SandboxBox Technical Documentation
+
+## Architecture Overview
+SandboxBox provides portable containerized development environments using Podman with automatic WSL machine management and Claude Code integration.
+
+## Core Components
+
+### CLI (cli.js)
+- Main entry point with automatic Podman machine management
+- Commands: build, run, shell, version, help
+- Auto-detects and starts Podman machine when needed
+- Shell execution with Windows compatibility (`shell: process.platform === 'win32'`)
+
+### Podman Downloader (scripts/download-podman.js)
+- Cross-platform binary downloads from GitHub releases
+- PowerShell ZIP extraction on Windows (no external dependencies)
+- Automatic version detection and binary path resolution
+
+### Container Images
+- **sandboxbox-auth**: Full development environment with Claude Code
+- **sandboxbox-local**: Local repository workspace (symlink approach)
+
+## Windows Compatibility Fixes
+
+### Critical PowerShell ZIP Extraction
+```javascript
+// scripts/download-podman.js:81
+execSync(`powershell -Command "${psCommand}"`, {
+  stdio: 'pipe',
+  cwd: __dirname,
+  shell: true  // REQUIRED for PowerShell commands
+});
+```
+
+### Shell Execution Pattern
+All `execSync()` calls must include:
+```javascript
+{
+  stdio: 'pipe',
+  shell: process.platform === 'win32'  // Windows compatibility
+}
+```
+
+### Auto Podman Machine Management
+```javascript
+// cli.js checkPodman() function
+if (process.platform === 'win32' && isBundled) {
+  try {
+    execSync(`"${podmanPath}" info`, { ...execOptions, stdio: 'pipe' });
+  } catch (infoError) {
+    if (infoError.message.includes('Cannot connect to Podman')) {
+      // Auto-start existing machine
+      execSync(`"${podmanPath}" machine start`, { stdio: 'inherit' });
+    }
+  }
+}
+```
+
+## Claude Code Integration
+
+### Authentication Transfer
+Mount complete Claude session data:
+```bash
+-v "$HOME/.claude:/root/.claude"
+```
+
+### Environment Variables
+Key variables to transfer:
+```bash
+ANTHROPIC_AUTH_TOKEN
+CLAUDECODE=1
+ANTHROPIC_BASE_URL
+```
+
+### Git Identity Transfer
+```bash
+-v "$HOME/.gitconfig:/root/.gitconfig:ro"
+-v "$HOME/.ssh:/root/.ssh:ro"
+```
+
+## Local Repository Workflow
+
+### Architecture
+- Container mounts local repo as `/project:rw`
+- Creates symlink `/workspace/project` → `/project`
+- Works directly with local repository (no cloning needed)
+- Changes persist to host folder automatically
+
+### Container Command
+```bash
+podman run --rm \
+  -v "/path/to/repo:/project:rw" \
+  -v "$HOME/.claude:/root/.claude" \
+  -v "$HOME/.gitconfig:/root/.gitconfig:ro" \
+  -v "$HOME/.ssh:/root/.ssh" \
+  -e "ANTHROPIC_AUTH_TOKEN=..." \
+  -e "CLAUDECODE=1" \
+  sandboxbox-local:latest
+```
+
+### Dockerfile.local-workspace
+```dockerfile
+# Creates symlink to mounted repository
+ln -sf "$REPO_PATH" "$WORKSPACE_DIR"
+cd "$WORKSPACE_DIR"
+exec claude  # Changes save directly to local repo
+```
+
+## Complete Workflow Example
+
+1. **Setup**: Build sandboxbox-local image
+2. **Mount**: Local repository as `/project:rw`
+3. **Auth Transfer**: Mount `.claude`, `.gitconfig`, `.ssh`
+4. **Edit**: Claude Code modifies files in `/workspace/project` (symlink to `/project`)
+5. **Commit**: Changes made directly to local repository
+6. **Persist**: No additional push/pull needed - changes already in host folder
+
+## Troubleshooting
+
+### "unzip command not found"
+**Solution**: Use PowerShell ZIP extraction with `shell: true`
+
+### "Cannot connect to Podman"
+**Solution**: Automatic machine start in checkPodman() function
+
+### Build context issues
+**Solution**: Use direct Podman build, then tag for SandboxBox
+
+### Git identity errors
+**Solution**: Mount `.gitconfig:ro` for user identity transfer
+
+### Path resolution issues
+**Solution**: Use explicit REPO_PATH environment variable
+
+## Version Management
+- Publish new version when fixing critical Windows issues
+- Clear npm cache: `npm cache clean --force`
+- Use specific version: `npx sandboxbox@latest`

package/Dockerfile

@@ -1,95 +1,95 @@
-FROM node:20
-
-ARG TZ
-ENV TZ="$TZ"
-
-ARG CLAUDE_CODE_VERSION=latest
-
-# Install basic development tools and iptables/ipset
-RUN apt-get update && apt-get install -y --no-install-recommends \
-  less \
-  git \
-  procps \
-  sudo \
-  fzf \
-  zsh \
-  man-db \
-  unzip \
-  gnupg2 \
-  gh \
-  iptables \
-  ipset \
-  iproute2 \
-  dnsutils \
-  aggregate \
-  jq \
-  nano \
-  vim \
-  && apt-get clean && rm -rf /var/lib/apt/lists/*
-
-# Ensure default node user has access to /usr/local/share
-RUN mkdir -p /usr/local/share/npm-global && \
-  chown -R node:node /usr/local/share
-
-ARG USERNAME=node
-
-# Persist bash history.
-RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
-  && mkdir -p /commandhistory \
-  && touch /commandhistory/.bash_history \
-  && chown -R $USERNAME /commandhistory
-
-# Set `DEVCONTAINER` environment variable to help with orientation
-ENV DEVCONTAINER=true
-
-# Create workspace and config directories and set permissions
-RUN mkdir -p /workspace /home/node/.claude && \
-  chown -R node:node /workspace /home/node/.claude
-
-WORKDIR /workspace
-
-ARG GIT_DELTA_VERSION=0.18.2
-RUN ARCH=$(dpkg --print-architecture) && \
-  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
-  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
-  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
-
-# Set up non-root user
-USER node
-
-# Install global packages
-ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
-ENV PATH=$PATH:/usr/local/share/npm-global/bin
-
-# Set the default shell to zsh rather than sh
-ENV SHELL=/bin/zsh
-
-# Set the default editor and visual
-ENV EDITOR=nano
-ENV VISUAL=nano
-
-# Default powerline10k theme
-ARG ZSH_IN_DOCKER_VERSION=1.2.0
-RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
-  -p git \
-  -p fzf \
-  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
-  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
-  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
-  -x
-
-# Install Claude
-RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
-
-# Install playwright deps
-RUN npx --yes playwright install-deps
-
-RUN npm i -g @playwright/mcp
-
-# Copy and set up firewall script
-COPY init-firewall.sh /usr/local/bin/
-USER root
-RUN chmod +x /usr/local/bin/init-firewall.sh && \
-  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
-  chmod 0440 /etc/sudoers.d/node-firewall
+FROM node:20
+
+ARG TZ
+ENV TZ="$TZ"
+
+ARG CLAUDE_CODE_VERSION=latest
+
+# Install basic development tools and iptables/ipset
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  less \
+  git \
+  procps \
+  sudo \
+  fzf \
+  zsh \
+  man-db \
+  unzip \
+  gnupg2 \
+  gh \
+  iptables \
+  ipset \
+  iproute2 \
+  dnsutils \
+  aggregate \
+  jq \
+  nano \
+  vim \
+  && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Ensure default node user has access to /usr/local/share
+RUN mkdir -p /usr/local/share/npm-global && \
+  chown -R node:node /usr/local/share
+
+ARG USERNAME=node
+
+# Persist bash history.
+RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  && mkdir -p /commandhistory \
+  && touch /commandhistory/.bash_history \
+  && chown -R $USERNAME /commandhistory
+
+# Set `DEVCONTAINER` environment variable to help with orientation
+ENV DEVCONTAINER=true
+
+# Create workspace and config directories and set permissions
+RUN mkdir -p /workspace /home/node/.claude && \
+  chown -R node:node /workspace /home/node/.claude
+
+WORKDIR /workspace
+
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH=$(dpkg --print-architecture) && \
+  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+# Set up non-root user
+USER node
+
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
+
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
+
+# Set the default editor and visual
+ENV EDITOR=nano
+ENV VISUAL=nano
+
+# Default powerline10k theme
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
+  -p git \
+  -p fzf \
+  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
+  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
+  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  -x
+
+# Install Claude
+RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
+
+# Install playwright deps
+RUN npx --yes playwright install-deps
+
+RUN npm i -g @playwright/mcp
+
+# Copy and set up firewall script
+COPY init-firewall.sh /usr/local/bin/
+USER root
+RUN chmod +x /usr/local/bin/init-firewall.sh && \
+  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
+  chmod 0440 /etc/sudoers.d/node-firewall
 USER node

package/Dockerfile.local-workspace

@@ -0,0 +1,56 @@
+FROM node:20
+
+# Install basic development tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    bash \
+    sudo \
+    nano \
+    vim \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Create workspace directory
+WORKDIR /workspace
+
+# Install Claude Code globally
+RUN npm install -g @anthropic-ai/claude-code@latest
+
+# Create startup script for local workspace (no cloning needed)
+RUN echo '#!/bin/bash\n\
+set -e\n\
+\n\
+# Get repository path from environment or default\n\
+REPO_PATH=${REPO_PATH:-"/project"}\n\
+WORKSPACE_DIR="/workspace/project"\n\
+\n\
+echo "🚀 Starting SandboxBox with Claude Code..."\n\
+echo "📁 Working with local repository: $REPO_PATH"\n\
+echo "🎯 Workspace: $WORKSPACE_DIR"\n\
+\n\
+# Create symbolic link to the mounted repository\n\
+if [ -d "$REPO_PATH" ] && [ -d "$REPO_PATH/.git" ]; then\n\
+    echo "📂 Creating workspace symlink to local repository..."\n\
+    ln -sf "$REPO_PATH" "$WORKSPACE_DIR"\n\
+    cd "$WORKSPACE_DIR"\n\
+    echo "✅ Workspace linked successfully!"\n\
+    echo "📋 Current status:"\n\
+    git status\n\
+    echo "📁 Repository contents:"\n\
+    ls -la\n\
+    echo ""\n\
+    echo "🔧 Starting Claude Code..."\n\
+    echo "💡 Tip: Changes will be saved directly to the local repository"\n\
+    echo "💡 Use Ctrl+C to exit Claude Code"\n\
+    exec claude\n\
+else\n\
+    echo "❌ Error: $REPO_PATH is not a valid git repository"\n\
+    echo "Please ensure the path contains a .git directory"\n\
+    echo "Contents of $REPO_PATH:"\n\
+    ls -la "$REPO_PATH" 2>/dev/null || echo "Directory not accessible"\n\
+    exit 1\n\
+fi' > /usr/local/bin/start-local-sandbox.sh && \
+    chmod +x /usr/local/bin/start-local-sandbox.sh
+
+# Set default command
+CMD ["/usr/local/bin/start-local-sandbox.sh"]