sandboxbox 1.2.1 → 2.0.0

package/Dockerfile

@@ -1,39 +1,95 @@
-FROM ubuntu:24.04
+FROM node:20
 
-# Set up code user
-RUN useradd code
+ARG TZ
+ENV TZ="$TZ"
 
-RUN chsh -s /bin/bash code
+ARG CLAUDE_CODE_VERSION=latest
 
-RUN mkdir /home/code
-RUN chown code:code /home/code
+# 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/*
 
-# Install deps
+# 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
 
-ENV USE_BUILTIN_RIPGREP=0
-RUN apt-get update && apt-get install -y \
-    postgresql-client nodejs npm curl sudo neovim direnv supervisor
+ARG USERNAME=node
 
-# Install playwright deps
-RUN npx --yes playwright install-deps
+# 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
 
-RUN npm i -g @playwright/mcp
+# 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
 
-# Install pnpm and configure it to be global
+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"
 
-RUN npm i -g pnpm
+# Set up non-root user
+USER node
 
-RUN mkdir -p /usr/local/share/pnpm/global/bin
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
 
-RUN pnpm config set global-bin-dir /usr/local/share/pnpm/global/bin
-RUN pnpm config set global-dir /usr/local/share/pnpm
-RUN echo 'export PATH="/usr/local/share/pnpm/global/bin:$PATH"' | tee -a /etc/bash.bashrc
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
 
-RUN bash -c 'PATH="/usr/local/share/pnpm/global/bin:$PATH" && pnpm i -g @anthropic-ai/claude-code'
+# Set the default editor and visual
+ENV EDITOR=nano
+ENV VISUAL=nano
 
-USER code
+# 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 chromium. Has to be done using the playwright MCP version for proper pathing etc
-RUN node /usr/local/lib/node_modules/@playwright/mcp/node_modules/playwright/cli.js install chromium
+# 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
 
-CMD ["/bin/bash"]
+# 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/README.md

@@ -1,150 +1,231 @@
 # SandboxBox
 
-**Zero-privilege container runner with Playwright support**
+**Cross-platform container runner with Claude Code and Playwright support**
 
-Run containers without Docker, root privileges, or external dependencies. Just bubblewrap and Node.js.
+Run your projects in isolated containers using Podman. Works on **Windows, macOS, and Linux**.
 
-## 🚀 Quick Start
+## Installation
+
+No installation required! Use with `npx`:
 
-### One-Time Setup
 ```bash
-# Install bubblewrap (requires sudo ONCE)
-sudo apt-get install bubblewrap  # Ubuntu/Debian
-sudo apk add bubblewrap          # Alpine
+npx sandboxbox build
+npx sandboxbox run ./my-project
+```
+
+## Quick Start
 
-# Setup Alpine environment
-npx sandboxbox setup
+### 1. Install Podman (One-time)
+
+**Windows:**
+```powershell
+winget install RedHat.Podman
 ```
 
-### Run Playwright Tests
+**macOS:**
 ```bash
-# Test any project
-npx sandboxbox run ./my-project
+brew install podman
+podman machine init
+podman machine start
+```
 
-# Quick test with sample Dockerfile
-npx sandboxbox quick-test ./my-app
+**Linux:**
+```bash
+sudo apt-get install podman     # Ubuntu/Debian
+sudo dnf install podman          # Fedora
+sudo apk add podman              # Alpine
+```
 
-# Interactive shell
-npx sandboxbox shell ./my-project
+### 2. Build Container
+
+```bash
+npx sandboxbox build
 ```
 
-### Build from Dockerfile
+This builds a container with:
+- Node.js v22
+- Claude Code CLI
+- Playwright with all browser dependencies
+- Git, npm, and essential build tools
+
+### 3. Run Your Project
+
 ```bash
-# Build container
-npx sandboxbox build ./Dockerfile
+# Run with default shell
+npx sandboxbox run ./my-project
 
-# Run the built container
-npx sandboxbox run ./project-directory
-```
+# Run custom command
+npx sandboxbox run ./my-project "npm test"
+
+# Run Claude Code
+npx sandboxbox run ./my-project "claude --help"
 
-## 📋 Commands
+# Run Playwright tests
+npx sandboxbox run ./my-project "npx playwright test"
+```
 
-| Command | Description |
-|---------|-------------|
-| `setup` | Set up Alpine Linux environment (one-time) |
-| `build <dockerfile>` | Build container from Dockerfile |
-| `run <project>` | Run Playwright tests in isolation |
-| `shell <project>` | Interactive shell in container |
-| `quick-test <project>` | Quick test with sample Dockerfile |
-| `version` | Show version information |
+### 4. Interactive Shell
 
-## ⚡ Performance
+```bash
+npx sandboxbox shell ./my-project
+```
 
-- **8ms startup** (37x faster than Docker)
-- **1MB memory overhead** (50x less than Docker)
-- **True isolation** with Linux namespaces
-- **Zero privileges** after bubblewrap installation
+## Features
 
-## 🎯 What Works
+### 🌍 Cross-Platform
+- **Windows** - Full support with Podman Desktop
+- **macOS** - Works with Podman machine
+- **Linux** - Native Podman support
 
-✅ **Chromium testing** - Full Playwright support
-✅ **Node.js projects** - Complete npm ecosystem
-✅ **Filesystem isolation** - Separate container environment
-✅ **Network access** - Full connectivity
-✅ **Process isolation** - Separate PID namespace
+### 🔒 Isolation
+- Complete container isolation
+- Your host system stays clean
+- Workspace mounted at `/workspace`
 
-## ⚠️ Limitations
+### 🚀 Pre-installed Tools
+- **Node.js v22**
+- **Claude Code CLI** - AI-powered development
+- **Playwright** - Browser automation with all dependencies
+- **Git** - Version control
+- **npm** - Package management
 
-❌ **Firefox/WebKit** - Need glibc (use Ubuntu for these)
-❌ **GPU acceleration** - Limited support
-❌ **System packages** - Can't install with apt/yum
+### 📦 NPX-First Design
+- No global installation needed
+- Single command execution
+- Works with any project directory
 
-## 🔧 Alternative Usage
+## Commands
 
-### Local Script
 ```bash
-# Using the wrapper script
-./run.sh run ./my-project
+# Build container from Dockerfile
+npx sandboxbox build
+npx sandboxbox build ./Dockerfile.custom
+
+# Run project in container
+npx sandboxbox run <project-dir> [command]
 
-# Direct Node.js execution
-node cli.js run ./my-project
+# Interactive shell
+npx sandboxbox shell <project-dir>
+
+# Show version
+npx sandboxbox version
 ```
 
-### As npm dependency
-```bash
-# Install in your project
-npm install sandboxbox
+## How It Works
 
-# Use in package.json scripts
-{
-  "scripts": {
-    "test:isolated": "sandboxbox run .",
-    "test:container": "sandboxbox quick-test ."
-  }
-}
+1. **Builds** a container image from the Dockerfile using Podman
+2. **Mounts** your project directory to `/workspace` in the container
+3. **Runs** your command in the isolated container environment
+4. **Removes** the container automatically when done
+
+```
+Your Project              Container
+./my-project    ━━━━━>    /workspace
+(host)                    (isolated)
 ```
 
-## 📖 Examples
+## Use Cases
+
+### Run Claude Code
+```bash
+npx sandboxbox run ./my-app "claude --version"
+npx sandboxbox run ./my-app "claude code review lib/"
+```
+
+### Run Playwright Tests
+```bash
+npx sandboxbox run ./my-app "npx playwright test"
+npx sandboxbox run ./my-app "npx playwright test --headed"
+```
 
-### Basic Playwright Testing
+### Development Workflow
 ```bash
-# Create a simple project
-mkdir my-test && cd my-test
-npm init -y
-npm install playwright
+# Build once
+npx sandboxbox build
 
-# Create a test
-cat > test.spec.js << 'EOF'
-import { test, expect } from '@playwright/test';
+# Interactive development
+npx sandboxbox shell ./my-app
 
-test('basic test', async ({ page }) => {
-  await page.goto('https://example.com');
-  await expect(page).toHaveTitle(/Example/);
-});
-EOF
+# Inside container:
+npm install
+npm test
+git commit -am "Update"
+exit
+```
 
-# Run in isolated container
-npx sandboxbox quick-test .
+### Run npm Scripts
+```bash
+npx sandboxbox run ./my-app "npm run build"
+npx sandboxbox run ./my-app "npm run lint"
+npx sandboxbox run ./my-app "npm run test:e2e"
 ```
 
-### Custom Dockerfile
+## Custom Dockerfile
+
+Create your own `Dockerfile`:
+
 ```dockerfile
-# Dockerfile.custom
-FROM alpine
+FROM node:22-alpine
+
+# Install system dependencies
+RUN apk add --no-cache git bash curl
 
-RUN apk add --no-cache nodejs npm curl
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
+# Install global packages
+RUN npm install -g @anthropic-ai/claude-code @playwright/test
 
-CMD ["npm", "start"]
+# Install Playwright browsers
+RUN npx playwright install --with-deps chromium
+
+WORKDIR /workspace
+
+CMD ["/bin/bash"]
 ```
 
+Then build:
 ```bash
-# Build and run
-npx sandboxbox build Dockerfile.custom
-npx sandboxbox run .
+npx sandboxbox build ./Dockerfile
+```
+
+## Requirements
+
+- **Podman** (https://podman.io/getting-started/installation)
+- **Node.js 16+** (for running npx)
+
+## Project Structure
+
+```
+sandboxbox/
+├── cli.js              # Main CLI - Podman integration
+├── Dockerfile          # Container definition
+├── package.json        # NPM package config
+└── README.md           # This file
 ```
 
-## 🏗️ Architecture
+## Why Podman?
+
+- ✅ **Cross-platform** - Works on Windows, macOS, Linux
+- ✅ **Rootless** - No daemon, runs as regular user
+- ✅ **Docker-compatible** - Uses OCI standard containers
+- ✅ **Secure** - Better security model than Docker
+- ✅ **Fast** - Lightweight and efficient
+
+## Differences from v1.x
+
+**v1.x (bubblewrap):**
+- Linux-only
+- Required bubblewrap installation
+- Direct process isolation
+
+**v2.x (Podman):**
+- Cross-platform (Windows/macOS/Linux)
+- Uses Podman containers
+- OCI-standard container images
+- More portable and widely supported
+
+## License
 
-SandboxBox uses:
-- **Bubblewrap (bwrap)** - Linux namespace isolation
-- **Alpine Linux** - Lightweight base filesystem
-- **System Chromium** - Avoids glibc compatibility issues
-- **Xvfb** - Virtual display for headless testing
+MIT
 
-## 📄 License
+## Contributing
 
-MIT
+Contributions welcome! This project focuses on cross-platform container execution with Claude Code and Playwright support using Podman.