{"id":39589644,"url":"https://github.com/wireless25/crush-sandbox","last_synced_at":"2026-01-27T22:24:38.187Z","repository":{"id":332579017,"uuid":"1134259591","full_name":"wireless25/crush-sandbox","owner":"wireless25","description":"Docker sandbox for the Crush CLI with per-workspace caching","archived":false,"fork":false,"pushed_at":"2026-01-23T10:22:12.000Z","size":185,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T03:35:15.945Z","etag":null,"topics":["agent-cli","agentic-ai","agentic-coding","ai","crush","crush-sandbox","docker","docker-sandbox","llms","sandbox"],"latest_commit_sha":null,"homepage":"https://wireless25.github.io/crush-sandbox/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wireless25.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-14T13:29:04.000Z","updated_at":"2026-01-23T10:22:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wireless25/crush-sandbox","commit_stats":null,"previous_names":["wireless25/crush-sandbox"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/wireless25/crush-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireless25%2Fcrush-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireless25%2Fcrush-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireless25%2Fcrush-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireless25%2Fcrush-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wireless25","download_url":"https://codeload.github.com/wireless25/crush-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireless25%2Fcrush-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28754155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T13:59:49.818Z","status":"ssl_error","status_checked_at":"2026-01-25T13:59:33.728Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-cli","agentic-ai","agentic-coding","ai","crush","crush-sandbox","docker","docker-sandbox","llms","sandbox"],"created_at":"2026-01-18T07:42:30.745Z","updated_at":"2026-01-25T14:07:48.443Z","avatar_url":"https://github.com/wireless25.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Crush Sandbox\n\nA lightweight bash wrapper that runs the [Crush CLI](https://github.com/charmbracelet/crush) in a Docker sandbox with **Git worktree support**. Perfect for AI-assisted development across multiple branches simultaneously, with per-workspace persistent caching for fast builds.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **macOS** (primary target)\n- **Docker Desktop** installed and running\n\n### Installation\n\n#### npm global install (recommended)\n\nThe recommended installation method uses npm to install crush-sandbox globally:\n\n```bash\nnpm install -g crush-sandbox\n```\n\n#### Direct script installation\n\n**Automatic installation:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/wireless25/crush-sandbox/main/docker-sandbox-crush | sudo tee /usr/local/bin/crush-sandbox \u003e /dev/null\nsudo chmod +x /usr/local/bin/crush-sandbox\nln -s /usr/local/bin/crush-sandbox /usr/local/bin/crushbox\n```\n\n**Manual installation:**\n\n1. Download the script:\n   ```bash\n   curl -fsSL https://raw.githubusercontent.com/wireless25/crush-sandbox/main/docker-sandbox-crush -o docker-sandbox-crush\n   ```\n\n2. Make it executable:\n   ```bash\n   chmod +x docker-sandbox-crush\n   ```\n\n3. Move it to your PATH:\n   ```bash\n   sudo mv docker-sandbox-crush /usr/local/bin/crush-sandbox\n   ```\n\n**Install using the script itself:**\n\nIf you've cloned the repository, you can use the built-in install command:\n\n```bash\n./docker-sandbox-crush install\n```\n\nThis will:\n- Validate Docker is available\n- Install the script to `/usr/local/bin/crush-sandbox`\n- Create a `crushbox` alias symlink\n- Display version information for installed tools\n\n**Note:** gitleaks Docker image will be pulled automatically on first use for credential scanning. No additional installation is required.\n\n## ✨ Features\n- **Git worktree support** - Work on multiple branches simultaneously without git conflicts\n- **Per-worktree container isolation**: Each worktree (main + each worktree) gets its own container for crash isolation\n- **Shared cache volumes**: All worktrees in same repository share a cache volume for fast installs\n- **Workspace path mounting**: Your workspace is mounted at same absolute path inside container, makes debugging easier\n- **Persistent caches**: npm and pnpm caches persist per repository for faster subsequent runs\n- **Automatic Crush CLI installation**: Crush CLI is installed automatically on first use\n- **Git config injection**: Your Git user.name and user.email are passed into the container\n- **Container reuse**: Containers are stopped but not removed, enabling fast restarts\n- **Container shell**: Use `--shell` flag to get an interactive shell instead of Crush CLI\n- **Configuration support**: Automatically mounts and merges Crush configuration from host\n- **Programmatic mode**: Send prompts directly via `-p` flag or piped input for automation and CI/CD\n\n## 🌳 Git Worktrees\n\nGit worktrees allow you to check out multiple branches simultaneously in different directories.\n\n### Why Worktrees Matter for AI Development\n\nTraditional git workflow forces you to switch branches (`git checkout`) to work on different features. This means:\n- You can only work on one feature at a time\n- Stashing or committing work-in-progress to switch contexts\n- Crush CLI can only work on the current branch\n- Slow context switching between features\n\nWith git worktrees:\n- **Work on multiple branches simultaneously** - Each worktree is an isolated directory on a different branch\n- **No context switching** - Jump between worktrees instantly, no stashing or committing needed\n- **Perfect for AI agents** - Crush can generate code in one worktree while you review in another\n- **Isolated environments** - Each worktree has its own docker container, sharing one cache volume with all containers in the same repository\n\n### Worktree Structure\n\n```\nmy-project/                    # Main workspace (e.g., main branch)\n├── src/\n├── .worktrees/               # Worktree directory\n│   ├── feature-login/        # Worktree 1 (feature/login branch)\n│   │   ├── src/\n│   │   └── package.json\n│   ├── fix-bug-123/         # Worktree 2 (bugfix/123 branch)\n│   │   ├── src/\n│   │   └── package.json\n│   └── experiment-api/       # Worktree 3 (experiment/api branch)\n│       ├── src/\n│       └── package.json\n└── package.json\n```\n\nEach worktree is a **separate Crush sandbox** with its own isolated container (crash-safe) but shares the npm/pnpm cache volume with other worktrees in the same repository.\n\n### Crush Sandbox + Worktrees Workflow\n\n1. **Create worktree**: `crush-sandbox run --worktree feature-login`\n2. **Work in isolation**: Crush CLI runs in `my-project/.worktrees/feature-login/` with its own container\n3. **Generate code**: AI creates feature code in worktree\n4. **Switch workspace**: `cd ../fix-bug-123` (instant, no git operations, each has its own container)\n5. **Review later**: Come back to worktree anytime, work is preserved\n6. **List containers**: `crush-sandbox list-containers` to see all workspace containers\n7. **Clean up**: `crush-sandbox remove-worktree feature-login` when done (also removes its container)\n8. **Restart**: Run a worktree sandbox later with `crush-sandbox run --worktree feature-login` (existing worktree name restarts the container) or `cd .worktrees/feature-login` and `crush-sandbox run`\n\n### Comparison: Traditional vs Worktree\n\n| Task | Traditional Git | With Worktrees |\n|------|-----------------|----------------|\n| Work on 2 features | Stash/commit, checkout branch | `cd .worktrees/feature2` |\n| AI code review | Push PR, review in same repo | Generate in worktree, review in main |\n| Context switch | 30-60 seconds | \u003c1 second |\n| Uncommitted changes | Must stash or commit | Stay in worktree |\n| Parallel testing | Difficult | Easy (each worktree has its own sandbox) |\n\n### Worktree Commands\n\n**Create a new worktree with auto-generated name:**\n```bash\ncrush-sandbox run --worktree\n```\n\n**Create worktree with custom name:**\n```bash\ncrush-sandbox run --worktree feature-login\n```\n\n**List all worktrees:**\n```bash\ncrush-sandbox list-worktrees\n```\n\n**List all containers:**\n```bash\ncrush-sandbox list-containers\n```\nThis shows all containers for the repository (main + all worktrees) with their status (running/stopped) and current workspace indicator.\n\n**Remove a worktree:**\n```bash\ncrush-sandbox remove-worktree feature-login\n```\n\n**Force remove (with uncommitted changes):**\n```bash\ncrush-sandbox remove-worktree feature-login --force\n```\n\n## ⚙️ Configuration\n\nThe Docker sandbox automatically provides Crush CLI configuration:\n\n### Configuration Sources\n\n**Host configuration** (global defaults):\n- `~/.config/crush/` - Global Crush config (read-only mount)\n- `~/.local/share/crush/` - Crush session data (read-only mount)\n\n**Workspace configuration** (workspace-specific):\n- `.crush.json` or `crush.json` (relative to workspace root)\n\nIf you maintain global Crush config with commands, skills, or settings, this will be mounted into the container. Any workspace-specific config will override these settings.\nConfig files in the workspace are mounted into the container with the rest of the code and take precedence over host config by default in Crush. Make sure to configure your skills\nand commands accordingly. If you want to use global configured skills, add the `/tmp/crush-config/merged/skills` path to the skills option in the config (global on host or in workspace) to make Crush pick them up.\n\n### Session Data Mounting\n\nCrush CLI session data (including authentication tokens, model preferences, and other runtime state) is mounted from your host machine into the container.\n\n**Important**: Session data is mounted **read-only** from `~/.local/share/crush/` on your host. This means:\n\n- **Configuration changes made inside the container are lost when the container stops**\n  - Tokens and authentication must be completed on the host machine\n  - Model preferences and settings should be configured on the host\n  - The container only reads pre-authenticated session data\n\n- **Recommended workflow**:\n  1. Run Crush CLI on the host machine first: `crush`\n  2. Complete authentication and configure your preferences\n  3. Run `crush-sandbox run` to use your pre-configured session\n  4. Use `--no-host-config` flag to skip host config/session mounting (requires re-authentication each session)\n\n- **Why read-only?**\n  - Prevents the AI agent from modifying your authentication tokens\n  - Ensures session integrity and security\n  - Keeps configuration changes persistent on your host machine\n\n**Example to include skills from global host in the config**:\n```json\n{\n  \"$schema\": \"https://charm.land/crush.json\",\n  \"options\": {\n    \"skills_paths\": [\n      \"~/.config/crush/skills\",\n      \"/tmp/crush-config/merged/skills\"\n    ]\n  }\n}\n```\n\nWith this configuration, you can still use `crush` on your host machine with the same setup.\n\n### Configuration Merge Behavior\n\n1. Host configuration is copied to the container\n2. Workspace configuration is mounted with the workspace, **overwriting** host config (Crush default behavior)\n3. Host configuration is available at `/tmp/crush-config/merged` inside the container\n4. `CRUSH_GLOBAL_CONFIG` environment variable is set to this location\n\nThis means workspace-specific settings always override global defaults.\n\n### Security\n\n- All configuration mounts are **read-only** (`:ro` flag)\n- The container cannot modify your host configuration files\n\n### Configuration Control Flags\n\nYou can control configuration behavior with these flags:\n\n| Flag | Description |\n|------|-------------|\n| `--no-host-config` | Skip mounting host Crush config directory |\n\n**Examples**:\n\n```bash\n# Skip host configuration\ncrush-sandbox run --no-host-config\n# Or use alias:\ncrushbox run --no-host-config\n```\n\n### Configuration Directory Structure Example\n\n```\n~/.config/crush/                    # Host configuration (global)\n├── crush.json                     # Main Crush config\n└── skills                         # Skills directory\n└── commands                       # Commands directory\n```\n\nIf you have a `crush.json` or `.crush.json` already in the workspace root, this will take precedence over the `.config/crush/` directory by Crush CLI's own behavior.\n\n## 📖 Usage\n\n### Start Crush CLI in a sandbox\n\nNavigate to your workspace directory and run:\n\n```bash\ncrush-sandbox run\n```\n\nOr use the alias:\n\n```bash\ncrushbox run\n```\n\nThis will:\n1. Create (or reuse) a sandbox container for your workspace\n2. Mount your workspace at the same absolute path\n3. Install Crush CLI if not already installed\n4. Install pnpm for package management\n5. Start the Crush CLI\n\n### Programmatic Mode\n\nFor automation and CI/CD pipelines, you can send prompts directly without interactive mode:\n\n**Using `-p` flag:**\n```bash\ncrush-sandbox run -p \"Create a REST API with authentication\"\n```\n\n**Using piped input:**\n```bash\ncat \"./ralph/prompt.md\" | crush-sandbox run\n```\n\n**Using heredocs:**\n```bash\ncrush-sandbox run -p \"$(cat \u003c\u003cEOF\nCreate a login form with:\n- Email field\n- Password field\n- Remember me checkbox\n- Login button\nEOF\n)\"\n```\n\n**With `--quiet` flag (suppresses container setup messages):**\n```bash\ncrush-sandbox run -p \"Refactor code\" --quiet\n```\n\n**With `--model` flag (select AI model):**\n```bash\ncrush-sandbox run -p \"Create a REST API\" --model \"openai/gpt-4\"\n```\n\n**With worktree:**\n```bash\ncrush-sandbox run --worktree feature-auth -p \"Add OAuth login\"\n```\n\n**With worktree and model:**\n```bash\ncrush-sandbox run --worktree feature-auth -p \"Add OAuth login\" --model \"claude-3.5\"\n```\n\n#### Programmatic Mode Details\n\n**Detection**: Programmatic mode is automatically enabled when:\n- `-p \"prompt\"` flag is provided (explicit prompt)\n- Stdin has piped input (e.g., `echo \"prompt\" | crush-sandbox run`)\n\n**Priority**: If both `-p` flag and piped input are present, the `-p` value is used (explicit wins).\n\n**Empty prompts**: Empty prompts pass through to Crush CLI without validation. Let Crush CLI handle the empty prompt.\n\n**Multi-line support**: Works with:\n- `-p` flag with quoted strings (preserves newlines)\n- Heredocs with `-p` flag\n- Piped multi-line input\n\n**Model selection**: `--model` flag allows specifying which AI model to use (e.g., `--model \"openai/gpt-4\"`, `--model \"claude-3.5\"`). See [AGENTS.md](AGENTS.md) for detailed examples.\n\n**Quiet mode**: `--quiet` flag suppresses container setup messages in programmatic mode:\n\nCrush CLI output is always visible. Error messages always appear even in quiet mode.\n\n**Flag conflicts**: The `--shell` flag cannot be used with programmatic mode (`-p` flag or piped input).\n\n**Exit codes**: Crush CLI exit codes propagate to script exit for automation scripts. Error messages are explicitly captured and reported, even when Crush CLI fails due to invalid model names. When `--model` is specified and Crush CLI fails, the script provides troubleshooting hints about potential model validation issues.\n\n### Start a debug shell\n\nIf you need to debug or run manual commands:\n\n```bash\ncrush-sandbox run --shell\n```\n\nOr with the alias:\n\n```bash\ncrushbox run --shell\n```\n\nThis gives you an interactive shell in the sandbox container instead of running Crush CLI.\n\n**Note:** The `--shell` flag cannot be used with `-p` flag or piped input (programmatic mode).\n\n### Clean up the sandbox\n\nTo remove the container and cache volume for the current workspace:\n\n```bash\ncrush-sandbox clean\n```\n\nOr with the alias:\n\n```bash\ncrushbox clean\n```\n\nAdd `--force` to skip prompts and clean all containers + cache:\n\n```bash\ncrush-sandbox clean --force\n```\n\n### Show version\n\n```bash\ncrush-sandbox --version\n```\n\n### Command Options\n\n| Option | Description |\n|--------|-------------|\n| `-p \"prompt\"` | Send prompt directly to Crush CLI (programmatic mode) |\n| `--model \"model\"` | Specify AI model for programmatic mode (e.g., `--model \"openai/gpt-4\"`) |\n| `--quiet` | Suppress container setup messages in programmatic mode |\n| `--shell` | Start interactive shell instead of Crush CLI (for debugging) |\n| `--worktree [name]` | Create a worktree with optional name |\n| `--branch-name [name]` | Specify branch name for worktree (requires --worktree) |\n| `--no-host-config` | Skip mounting host Crush config directory |\n| `--cred-scan` | Enable credential scanning before starting container |\n| `--force` | Skip confirmation prompts (use with clean and remove-worktree) |\n| `--version` | Show version information |\n\n### Update to latest version\n\n```bash\ncrush-sandbox update\n```\n\nThis will:\n- Check for the latest version on GitHub\n- Compare with your current version\n- Prompt for confirmation if a newer version is available\n- Download and replace the script automatically\n- Validate the downloaded script before installing\n\n### Get help\n\n```bash\ncrush-sandbox help\n```\n\n## 🔒 Security\n\n### Security Overview\n\nThe docker-sandbox-crush tool implements several security controls to make AI-assisted development safe(er). However, the tool requires you to follow certain security practices to ensure safe operation.\nCrush asks for your permission before performing any operation, but if you use `--yolo` mode or use it programmatically with `crush run` in a ralph loop, you must be aware of the security implications.\n\n### Read-Write Workspace Access\n\nThe Crush agent inside the container has **full read-write access** to your workspace files. This is intentional and necessary for the agent to:\n\n- Read and modify source code files\n- Run build commands and tests\n- Create new files and directories\n- Install packages and dependencies\n- Execute git operations\n\n**Security Implications:**\n\n1. **Trust the AI agent**: The agent can modify any file in your workspace\n2. **Credential exposure risk**: Never store secrets (API keys, passwords, tokens) in your workspace files\n3. **Review all changes**: Always review agent-generated changes\n4. **Use version control**: Git provides a safety net - you can revert any unwanted changes\n\n**Best Practices:**\n\n- Store credentials in:\n  - Environment variables\n  - Secret management tools\n  - CI/CD pipeline secrets (GitHub Actions Secrets, GitLab CI Variables)\n  - `.env` files that are gitignored\n- Never commit credentials to git\n- Use `.gitignore` to exclude files with secrets\n- Rotate credentials if they were ever committed accidentally\n\n### Git Branch Protection for Production\n\nWhen planning to use `--yolo` mode or use it programmatically with `crush run`, you should configure git branch protection to prevent direct pushes to production branches. This ensures:\n\n- All agent-generated code goes through a pull request process\n- Code review is required before merging\n- CI/CD checks must pass before merging\n- Unauthorized direct commits are blocked\n\n### What the Agent Can and Cannot Do\n\n#### Capabilities\n\nThe Crush agent inside the sandbox container can:\n\n✅ **Read and write workspace files**\n- Full access to all files in the mounted workspace\n- Can create, modify, delete any file\n- Can execute any command within the workspace\n\n✅ **Run commands and scripts**\n- Execute build commands (npm build, cargo build, etc.)\n- Run tests (npm test, pytest, etc.)\n- Install packages (npm install, pip install, etc.)\n\n✅ **Make git operations**\n- Create commits\n- Create branches\n- Stage files\n- Push to remote repositories\n\n✅ **Access network resources**\n- Download dependencies from npm, PyPI, etc.\n- Make HTTP requests (if in code)\n- Clone other git repositories\n\n#### Limitations\n\nThe Crush agent cannot:\n\n❌ **Access files outside the workspace**\n- Container is limited to mounted workspace directory\n- Cannot access your home directory (except workspace subdirectories)\n- Cannot access system files or other projects\n\n❌ **Run with elevated privileges**\n- Container runs as non-root user\n- Cannot install system packages globally\n- Cannot modify Docker host\n\n❌ **Escalate privileges**\n- Docker capabilities are dropped (except CHOWN and DAC_OVERRIDE)\n- Cannot gain root access\n- Cannot modify container configuration\n\n❌ **Access host resources directly**\n- No direct access to host network\n- No access to host filesystem beyond workspace\n- Cannot interact with other containers\n\n#### Security Controls in Place\n\nThe tool implements these security controls:\n\n1. **Resource limits** - Prevents resource exhaustion attacks:\n   - Memory limited to 4GB\n   - CPU limited to 2 cores\n   - Process count limited to 100 PIDs\n\n2. **Non-root user** - Limits attack surface:\n   - Container runs as your UID/GID\n   - Cannot perform privileged operations\n\n3. **Capability dropping** - Reduces Linux capabilities:\n   - All capabilities dropped by default\n   - CHOWN and DAC_OVERRIDE added back (required for cache and workspace access)\n\n4. **Credential scanning** - Warns about exposed secrets:\n   - Scans workspace with gitleaks before starting\n   - gitleaks is automatically installed when you run `crush-sandbox run --cred-scan`\n   - Prompts you to continue or abort if credentials detected\n   - Can be bypassed with `--no-cred-scan` flag (use with caution)\n\n5. **Workspace isolation** - Prevents cross-project contamination:\n   - Each workspace has its own container\n   - Caches are per-workspace\n   - No shared state between workspaces\n\n## 🔧 How It Works\n\n### Workspace Isolation\n\nEach workspace directory (main or worktree) gets its own:\n- **Container**: Named `crush-sandbox-\u003crepo-hash\u003e` (main) or `crush-sandbox-\u003crepo-hash\u003e-\u003cworktree-name\u003e` (worktree)\n- **Cache volume**: Named `crush-cache-\u003crepo-hash\u003e` for persistent package manager caches (shared across all worktrees in same repository)\n\nThis means:\n- Each worktree has crash isolation (stopping one doesn't affect others)\n- All worktrees in same repository share npm/pnpm cache for fast installs\n- Different repositories have completely isolated sandbox environments\n\n### Container Lifecycle\n\n1. **Create**: Container is created from `node:18-alpine` base image\n2. **Configure**: Workspace and cache volumes are mounted, environment variables are set\n3. **Start**: Container is started\n4. **Use**: Crush CLI or shell runs inside the container\n5. **Stop**: Container is stopped when you exit (kept for reuse)\n\nContainers are **not removed** automatically, so subsequent starts are instant.\n\n### Cache Persistence\n\nThe cache volume stores:\n- **npm cache**: `/workspace-cache/npm`\n- **pnpm store**: `/workspace-cache/pnpm/store`\n- **pnpm cache**: `/workspace-cache/pnpm/cache`\n\nThis means:\n- Packages downloaded once stay cached\n- Switching workspaces switches cache volumes\n- Faster installs after the first run\n\n### Automatic Tool Installation\n\nOn container startup:\n1. **Crush CLI**: Installed via `npm install -g @charmland/crush` (cached after first install)\n2. **pnpm**: Installed via `npm install -g pnpm` (uses npm cache)\n\nInstallation happens automatically and silently on every container start, with fast-path checks to skip re-installation.\n\n## 📋 Examples\n\n### Worktree Examples\n\n#### Example 1: Feature Development Workflow\n```bash\n# Navigate to your project\ncd ~/projects/my-app\n\n# Create worktree for new feature\ncrush-sandbox run --worktree feature-auth\n\n# Inside Crush CLI, generate authentication code\n\u003e Crush: Implement JWT authentication\n[AI generates auth system in .worktrees/feature-auth/]\n\n# Switch back to main workspace\ncd ~/projects/my-app\n\n# Continue working on main branch\ngit pull origin main\n\n# Later, review the worktree\ncd .worktrees/feature-auth\ngit diff main  # See all changes from worktree\n\n# When satisfied, merge to main\ngit checkout main\ngit merge feature-auth\ncrush-sandbox remove-worktree feature-auth\n```\n\n#### Example 2: Parallel Development\n```bash\n# Main workspace: stable branch\ncd ~/projects/my-app\n\n# Worktree 1: User profile feature\ncrush-sandbox run --worktree feature-profile\n# AI generates user profile code\n\n# Worktree 2: API refactoring\ncd ~/projects/my-app\ncrush-sandbox run --worktree refactor-api\n# AI refactors API endpoints\n\n# Worktree 3: Bugfix\ncd ~/projects/my-app\ncrush-sandbox run --worktree fix-auth-bug\n# AI fixes authentication bug\n\n# List all worktrees\ncrush-sandbox list-worktrees\n\n# Worktrees:\n#   - /Users/user/projects/my-app/.worktrees/feature-profile\n#     Branch: feature/profile\n#   - /Users/user/projects/my-app/.worktrees/refactor-api (current)\n#     Branch: refactor/api\n#   - /Users/user/projects/my-app/.worktrees/fix-auth-bug\n#     Branch: fix/auth-bug\n\n# Switch between worktrees instantly (no git checkout needed)\ncd ../feature-profile\ncd ../fix-auth-bug\n```\n\n#### Example 3: Bugfix vs Feature Isolation\n```bash\n# Main workspace on stable branch (production code)\ncd ~/projects/my-app\ngit checkout main\n\n# Worktree for urgent bugfix (isolated from feature work)\ncrush-sandbox run --worktree fix-critical-bug\n\u003e Crush: Fix the production authentication bug\n[AI generates bugfix in isolation]\n\n# Meanwhile, main workspace remains stable\n# No risk of accidentally including untested changes\n\n# Test bugfix in its own sandbox\ncd .worktrees/fix-critical-bug\nnpm test  # Run tests in bugfix environment\n\n# Merge only when ready\ngit checkout main\ngit merge fix-critical-bug\ncrush-sandbox remove-worktree fix-critical-bug\n```\n\n#### Example 4: AI-Assisted PR Workflow\n```bash\n# Worktree for Crush-generated PR\ncd ~/projects/my-app\ncrush-sandbox run --worktree pr-add-dashboard\n\n# Crush generates complete feature\n\u003e Crush: Add admin dashboard with charts and analytics\n[AI creates entire feature in worktree]\n\n# Stay in main workspace to review\ncd ~/projects/my-app\n\n# Compare worktree to main\ngit diff main .worktrees/pr-add-dashboard/\n\n# Test worktree changes\ncd .worktrees/pr-add-dashboard\ncrush-sandbox run --shell  # Debug in worktree sandbox\nnpm test                   # Run tests\n\n# Review and merge\ncd ~/projects/my-app\ngit checkout -b add-dashboard\ngit merge pr-add-dashboard\ngit push origin add-dashboard\ncrush-sandbox remove-worktree pr-add-dashboard\n```\n\n### Programmatic Mode Examples\n\n#### Simple one-liners\n```bash\n# Generate a component\ncrush-sandbox run -p \"Create a React button component with hover states\"\n\n# Add a feature\necho \"Add dark mode support\" | crush-sandbox run\n\n# Fix a bug\ncrush-sandbox run -p \"Fix the authentication redirect loop\"\n```\n\n#### CI/CD Pipeline Integration\n```bash\n#!/bin/bash\n# CI/CD pipeline script\n\n# Run automated code generation\ncrush-sandbox run -p \"Add unit tests for user authentication\" --quiet\n\n# Run tests\nnpm test\n\n# If tests pass, commit and push\ngit add .\ngit commit -m \"Add auth unit tests\"\ngit push origin main\n```\n\n#### Multi-command automation\n```bash\n# Generate multiple components in sequence\nfor component in Button Input Modal; do\n  crush-sandbox run -p \"Create a React ${component} component\" --quiet\ndone\n```\n\n#### Advanced piping examples\n```bash\n# Multi-line piped input\necho -e \"Fix login bug\\nAdd validation\\nUpdate tests\" | crush-sandbox run\n\n# Heredoc piped input\ncrush-sandbox run \u003c\u003cEOF\nCreate a login form with:\n- Email field\n- Password field\n- Remember me checkbox\n- Login button\nEOF\n\n# Quiet mode with piping\necho \"Refactor code\" | crush-sandbox run --quiet\n```\n\n#### With worktrees\n```bash\n# Generate code in worktree for review\ncrush-sandbox run --worktree feature-ui -p \"Redesign the user profile page\" --quiet\n\n# Review in main workspace\ncd ../\n# Compare changes\ngit diff main .worktrees/feature-ui/\n```\n\n#### Error handling\n```bash\n# --shell not allowed with -p\ncrush-sandbox run --shell -p \"test\"\n# Error: --shell flag cannot be used with -p or piped input\n\n# --shell not allowed with piped input\necho \"test\" | crush-sandbox run --shell\n# Error: --shell flag cannot be used with -p or piped input\n\n# Empty prompt passes through\necho \"\" | crush-sandbox run\n# Executes: crush run \"\" (Crush CLI handles empty prompt)\n```\n\n### Basic Usage Examples\n\n#### Typical workflow\n```bash\n# Navigate to your project\ncd ~/projects/my-app\n\n# Start Crush CLI in sandbox\ncrush-sandbox run\n# Or use alias:\n# crushbox run\n\n# ... work with Crush CLI ...\n\n# When done, Crush CLI exits and container stops\n# Next time, container is reused (instant start)\n```\n\n#### Using with different workspaces\n```bash\ncd ~/projects/project-a\ncrush-sandbox run  # Uses crush-sandbox-\u003chash-a\u003e\n\ncd ~/projects/project-b\ncrush-sandbox run  # Uses crush-sandbox-\u003chash-b\u003e\n```\n\nEach workspace has its own isolated environment.\n\n#### Debugging setup issues\n```bash\n# Get a shell to check installation\ncrush-sandbox run --shell\n# Or:\ncrushbox run --shell\n\n# Inside the container:\nwhich crush          # Check if Crush CLI is installed\npnpm --version       # Check pnpm version\nnpm --version        # Check npm version\n```\n\n## 🐛 Troubleshooting\n\n### \"docker daemon is not running or not accessible\"\n\n**Problem**: Docker Desktop is not running.\n\n**Solution**: Start Docker Desktop and wait for it to be ready. Verify with:\n```bash\ndocker info\n```\n\n### \"Git user.name and user.email not configured\"\n\n**Problem**: Git user configuration is missing.\n\n**Solution**: This is a warning, not an error. Add to `~/.gitconfig` if Crush CLI needs git operations:\n```bash\ngit config --global user.name \"Your Name\"\ngit config --global user.email \"your.email@example.com\"\n```\n\n### Crush CLI not working in container\n\n**Problem**: Crush CLI installation failed.\n\n**Solution**: Run with `--shell` flag to debug:\n```bash\ncrush-sandbox run --shell\n# Then manually install:\nnpm install -g @charmland/crush\n```\n\n### Cache not persisting\n\n**Problem**: Packages are re-downloaded every time.\n\n**Solution**: Verify cache volume exists:\n```bash\ndocker volume ls | grep crush-cache\n```\n\nCheck if volume is mounted:\n```bash\ndocker inspect \u003ccontainer-name\u003e | grep Mounts\n```\n\n### \"Cannot write to /usr/local/bin\" during install\n\n**Problem**: No write permissions to `/usr/local/bin`.\n\n**Solution**: Run with sudo:\n```bash\nsudo ./docker-sandbox-crush install\n```\n\nOr choose a different installation directory in your PATH.\n\n### Container name changes unexpectedly\n\n**Problem**: Different containers for the same project.\n\n**Solution**: Ensure you're in the same workspace directory. Container names are based on the current working directory (`pwd`).\n\n### \"Not in a git repository\" when using --worktree\n\n**Problem**: Tried to use worktree features outside a git repository.\n\n**Solution**: Worktrees only work in git repositories. Initialize git first:\n```bash\ngit init\n```\n\n### Worktree directory not found\n\n**Problem**: Container starts but worktree path doesn't exist.\n\n**Solution**: Check `.worktrees/` directory in git root:\n```bash\nls -la .worktrees/\n```\n\nIf missing, create a new worktree:\n```bash\ncrush-sandbox run --worktree my-feature\n```\n\n### Cannot remove worktree with uncommitted changes\n\n**Problem**: Worktree has uncommitted changes and `remove-worktree` fails.\n\n**Solution**: Use `--force` flag:\n```bash\ncrush-sandbox remove-worktree my-feature --force\n```\n\nOr commit/stash changes first:\n```bash\ncd .worktrees/my-feature\ngit add .\ngit commit -m \"Save work\"\ncd ..\ncrush-sandbox remove-worktree my-feature\n```\n\n### Container/volume mismatch with worktree\n\n**Problem**: Container uses root workspace name instead of worktree name.\n\n**Solution**: This is expected behavior! Containers and caches are named based on the **root git workspace**, not the current worktree path. All worktrees in the same project share the same container and cache. This is intentional - it allows fast switching between worktrees without recreating containers.\n\n### Branch conflicts when creating worktree\n\n**Problem**: Git error \"Branch already checked out elsewhere\" when creating worktree.\n\n**Solution**: The branch is already checked out in another worktree or the main workspace. Either:\n- Use a different branch: `crush-sandbox run --worktree feature2 other-branch`\n- Switch main workspace to a different branch first\n- Remove the worktree that has the branch: `crush-sandbox remove-worktree other-worktree`\n\n## 📝 License\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 🙋 Support\n\nIf you encounter issues or have questions:\n1. Check the [Troubleshooting](#-troubleshooting) section above\n2. Search existing [GitHub Issues](https://github.com/wireless25/crush-sandbox/issues)\n3. [Open a new issue](https://github.com/wireless25/crush-sandbox/issues/new) with details\n\n## 🔗 Related\n\n- [Crush CLI](https://github.com/charmbracelet/crush) - The AI-powered CLI assistant\n- [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop) - Container runtime\n\n---\n\nMade with ❤️ for developers who love isolated environments\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwireless25%2Fcrush-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwireless25%2Fcrush-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwireless25%2Fcrush-sandbox/lists"}