sandboxbox 1.2.2 → 2.0.1

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.