{"id":28972743,"url":"https://github.com/textcortex/claude-code-sandbox","last_synced_at":"2025-06-24T11:08:29.233Z","repository":{"id":295508983,"uuid":"990296721","full_name":"textcortex/claude-code-sandbox","owner":"textcortex","description":"Run Claude Code safely in local Docker containers without having to approve every permission","archived":false,"fork":false,"pushed_at":"2025-06-12T15:10:19.000Z","size":646,"stargazers_count":29,"open_issues_count":2,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-12T16:27:19.713Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/textcortex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-05-25T22:25:38.000Z","updated_at":"2025-06-12T15:09:57.000Z","dependencies_parsed_at":"2025-05-27T12:26:06.677Z","dependency_job_id":"732404bf-fe06-420b-83cd-6f9b97d790d1","html_url":"https://github.com/textcortex/claude-code-sandbox","commit_stats":null,"previous_names":["osolmaz/claude-code-sandbox","textcortex/claude-code-sandbox"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/textcortex/claude-code-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textcortex%2Fclaude-code-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textcortex%2Fclaude-code-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textcortex%2Fclaude-code-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textcortex%2Fclaude-code-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/textcortex","download_url":"https://codeload.github.com/textcortex/claude-code-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textcortex%2Fclaude-code-sandbox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261658590,"owners_count":23191089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-06-24T11:08:27.211Z","updated_at":"2025-06-24T11:08:29.219Z","avatar_url":"https://github.com/textcortex.png","language":"TypeScript","readme":"# Claude Code Sandbox\n\n\u003e [!WARNING]\n\u003e\n\u003e - This work is alpha and might have security issues, use at your own risk.\n\u003e - Check [TODO.md](./TODO.md) for the roadmap.\n\u003e - Email [dev@textcortex.com](mailto:dev@textcortex.com) for inquiries.\n\nRun Claude Code as an autonomous agent inside Docker containers with automatic GitHub integration. Bypass all permissions safely.\n\n\u003cimg width=\"1485\" alt=\"Screenshot 2025-05-27 at 14 48 25\" src=\"https://github.com/user-attachments/assets/c014b8f5-7f14-43fd-bf8e-bf41787f8ec8\" /\u003e\n\n## Why Claude Code Sandbox?\n\nThe primary goal of Claude Code Sandbox is to enable **full async agentic workflows** by allowing Claude Code to execute without permission prompts. By running Claude in an isolated Docker container with the `--dangerously-skip-permissions` flag, Claude can:\n\n- Execute any command instantly without asking for permission\n- Make code changes autonomously\n- Run build tools, tests, and development servers\n- Create commits and manage git operations\n- Work continuously without interrupting the user\n\nAccess Claude through a **browser-based terminal** that lets you monitor and interact with the AI assistant while you work on other tasks. This creates a truly autonomous development assistant, similar to [OpenAI Codex](https://chatgpt.com/codex) or [Google Jules](https://jules.dev), but running locally on your machine with full control.\n\n## Overview\n\nClaude Code Sandbox allows you to run Claude Code in isolated Docker containers, providing a safe environment for AI-assisted development. It automatically:\n\n- Creates a new git branch for each session\n- Monitors for commits made by Claude\n- Provides interactive review of changes\n- Handles credential forwarding securely\n- Enables push/PR creation workflows\n- Runs custom setup commands for environment initialization\n\n## Installation\n\nInstall Claude Code Sandbox globally from npm:\n\n```bash\nnpm install -g @textcortex/claude-code-sandbox\n```\n\n### Prerequisites\n\n- Node.js \u003e= 18.0.0\n- Docker or Podman\n- Git\n- Claude Code (`npm install -g @anthropic-ai/claude-code@latest`)\n\n## Usage\n\n### Quick Start\n\nSimply run in any git repository:\n\n```bash\nclaude-sandbox\n```\n\nThis will:\n\n1. Create a new branch (`claude/[timestamp]`)\n2. Start a Docker container with Claude Code\n3. Launch a web UI at `http://localhost:3456`\n4. Open your browser automatically\n\n### Commands\n\n#### `claude-sandbox` (default)\n\nStart a new container with web UI (recommended):\n\n```bash\nclaude-sandbox\n```\n\n#### `claude-sandbox start`\n\nExplicitly start a new container with options:\n\n```bash\nclaude-sandbox start [options]\n\nOptions:\n  -c, --config \u003cpath\u003e    Configuration file (default: ./claude-sandbox.config.json)\n  -n, --name \u003cname\u003e      Container name prefix\n  --no-web               Disable web UI (use terminal attach)\n  --no-push              Disable automatic branch pushing\n  --no-pr                Disable automatic PR creation\n```\n\n#### `claude-sandbox attach [container-id]`\n\nAttach to an existing container:\n\n```bash\n# Interactive selection\nclaude-sandbox attach\n\n# Specific container\nclaude-sandbox attach abc123def456\n\nOptions:\n  --no-web               Use terminal attach instead of web UI\n```\n\n#### `claude-sandbox list`\n\nList all Claude Sandbox containers:\n\n```bash\nclaude-sandbox list\nclaude-sandbox ls        # alias\n\nOptions:\n  -a, --all              Show all containers (including stopped)\n```\n\n#### `claude-sandbox stop [container-id]`\n\nStop containers:\n\n```bash\n# Interactive selection\nclaude-sandbox stop\n\n# Specific container\nclaude-sandbox stop abc123def456\n\n# Stop all\nclaude-sandbox stop --all\n```\n\n#### `claude-sandbox logs [container-id]`\n\nView container logs:\n\n```bash\nclaude-sandbox logs\nclaude-sandbox logs abc123def456\n\nOptions:\n  -f, --follow           Follow log output\n  -n, --tail \u003clines\u003e     Number of lines to show (default: 50)\n```\n\n#### `claude-sandbox clean`\n\nRemove stopped containers:\n\n```bash\nclaude-sandbox clean\nclaude-sandbox clean --force  # Remove all containers\n```\n\n#### `claude-sandbox config`\n\nShow current configuration:\n\n```bash\nclaude-sandbox config\n```\n\n### Configuration\n\nCreate a `claude-sandbox.config.json` file (see `claude-sandbox.config.example.json` for reference):\n\n```json\n{\n  \"dockerImage\": \"claude-code-sandbox:latest\",\n  \"dockerfile\": \"./custom.Dockerfile\",\n  \"detached\": false,\n  \"autoPush\": true,\n  \"autoCreatePR\": true,\n  \"autoStartClaude\": true,\n  \"envFile\": \".env\",\n  \"environment\": {\n    \"NODE_ENV\": \"development\"\n  },\n  \"setupCommands\": [\"npm install\", \"npm run build\"],\n  \"volumes\": [\"/host/path:/container/path:ro\"],\n  \"mounts\": [\n    {\n      \"source\": \"./data\",\n      \"target\": \"/workspace/data\",\n      \"readonly\": false\n    },\n    {\n      \"source\": \"/home/user/configs\",\n      \"target\": \"/configs\",\n      \"readonly\": true\n    }\n  ],\n  \"allowedTools\": [\"*\"],\n  \"maxThinkingTokens\": 100000,\n  \"bashTimeout\": 600000,\n  \"containerPrefix\": \"my-project\",\n  \"claudeConfigPath\": \"~/.claude.json\"\n}\n```\n\n#### Configuration Options\n\n- `dockerImage`: Base Docker image to use (default: `claude-code-sandbox:latest`)\n- `dockerfile`: Path to custom Dockerfile (optional)\n- `detached`: Run container in detached mode\n- `autoPush`: Automatically push branches after commits\n- `autoCreatePR`: Automatically create pull requests\n- `autoStartClaude`: Start Claude Code automatically (default: true)\n- `envFile`: Load environment variables from file (e.g., `.env`)\n- `environment`: Additional environment variables\n- `setupCommands`: Commands to run after container starts (e.g., install dependencies)\n- `volumes`: Legacy volume mounts (string format)\n- `mounts`: Modern mount configuration (object format)\n- `allowedTools`: Claude tool permissions (default: all)\n- `maxThinkingTokens`: Maximum thinking tokens for Claude\n- `bashTimeout`: Timeout for bash commands in milliseconds\n- `containerPrefix`: Custom prefix for container names\n- `claudeConfigPath`: Path to Claude configuration file\n- `dockerSocketPath`: Custom Docker/Podman socket path (auto-detected by default)\n\n#### Mount Configuration\n\nThe `mounts` array allows you to mount files or directories into the container:\n\n- `source`: Path on the host (relative paths are resolved from current directory)\n- `target`: Path in the container (relative paths are resolved from /workspace)\n- `readonly`: Optional boolean to make the mount read-only (default: false)\n\nExample use cases:\n\n- Mount data directories that shouldn't be in git\n- Share configuration files between host and container\n- Mount build artifacts or dependencies\n- Access host system resources (use with caution)\n\n## Features\n\n### Podman Support\n\nClaude Code Sandbox now supports Podman as an alternative to Docker. The tool automatically detects whether you're using Docker or Podman by checking for available socket paths:\n\n- **Automatic detection**: The tool checks for Docker and Podman sockets in standard locations\n- **Custom socket paths**: Use the `dockerSocketPath` configuration option to specify a custom socket\n- **Environment variable**: Set `DOCKER_HOST` to override socket detection\n\nExample configuration for Podman:\n\n```json\n{\n  \"dockerSocketPath\": \"/run/user/1000/podman/podman.sock\"\n}\n```\n\nThe tool will automatically detect and use Podman if:\n\n- Docker socket is not available\n- Podman socket is found at standard locations (`/run/podman/podman.sock` or `$XDG_RUNTIME_DIR/podman/podman.sock`)\n\n### Web UI Terminal\n\nLaunch a browser-based terminal interface to interact with Claude Code:\n\n```bash\nclaude-sandbox --web\n```\n\nThis will:\n\n- Start the container in detached mode\n- Launch a web server on `http://localhost:3456`\n- Open your browser automatically\n- Provide a full terminal interface with:\n  - Real-time terminal streaming\n  - Copy/paste support\n  - Terminal resizing\n  - Reconnection capabilities\n\nPerfect for when you want to monitor Claude's work while doing other tasks.\n\n### Automatic Credential Discovery\n\nClaude Code Sandbox automatically discovers and forwards:\n\n**Claude Credentials:**\n\n- Anthropic API keys (`ANTHROPIC_API_KEY`)\n- macOS Keychain credentials (Claude Code)\n- AWS Bedrock credentials\n- Google Vertex credentials\n- Claude configuration files (`.claude.json`, `.claude/`)\n\n**GitHub Credentials:**\n\n- GitHub CLI authentication (`gh auth`)\n- GitHub tokens (`GITHUB_TOKEN`, `GH_TOKEN`)\n- Git configuration (`.gitconfig`)\n\n### Sandboxed Execution\n\n- Claude runs with `--dangerously-skip-permissions` flag (safe in container)\n- Creates isolated branch for each session\n- Full access to run any command within the container\n- Files are copied into container (not mounted) for true isolation\n- Git history preserved for proper version control\n\n### Commit Monitoring\n\nWhen Claude makes a commit:\n\n1. Real-time notification appears\n2. Full diff is displayed with syntax highlighting\n3. Interactive menu offers options:\n   - Continue working\n   - Push branch to remote\n   - Push branch and create PR\n   - Exit\n\n### Working with Multiple Containers\n\nRun multiple Claude instances simultaneously:\n\n```bash\n# Terminal 1: Start main development\nclaude-sandbox start --name main-dev\n\n# Terminal 2: Start feature branch work\nclaude-sandbox start --name feature-auth\n\n# Terminal 3: List all running containers\nclaude-sandbox list\n\n# Terminal 4: Attach to any container\nclaude-sandbox attach\n```\n\n## Docker Environment\n\n### Default Image\n\nThe default Docker image includes:\n\n- Ubuntu 22.04\n- Git, GitHub CLI\n- Node.js, npm\n- Python 3\n- Claude Code (latest)\n- Build essentials\n\n### Custom Dockerfile\n\nCreate a custom environment:\n\n```dockerfile\nFROM claude-code-sandbox:latest\n\n# Add your tools\nRUN apt-get update \u0026\u0026 apt-get install -y \\\n    rust \\\n    cargo \\\n    postgresql-client\n\n# Install project dependencies\nCOPY package.json /tmp/\nRUN cd /tmp \u0026\u0026 npm install\n\n# Custom configuration\nENV CUSTOM_VAR=value\n```\n\nReference in config:\n\n```json\n{\n  \"dockerfile\": \"./my-custom.Dockerfile\"\n}\n```\n\n## Workflow Example\n\n1. **Start Claude Sandbox:**\n\n   ```bash\n   cd my-project\n   claude-sandbox\n   ```\n\n2. **Interact with Claude:**\n\n   ```\n   \u003e Help me refactor the authentication module to use JWT tokens\n   ```\n\n3. **Claude works autonomously:**\n\n   - Explores codebase\n   - Makes changes\n   - Runs tests\n   - Commits changes\n\n4. **Review and push:**\n   - See commit notification\n   - Review syntax-highlighted diff\n   - Choose to push and create PR\n\n## Security Considerations\n\n- Credentials are mounted read-only\n- Containers are isolated from host\n- Branch restrictions prevent accidental main branch modifications\n- All changes require explicit user approval before pushing\n\n## Troubleshooting\n\n### Claude Code not found\n\nEnsure Claude Code is installed globally:\n\n```bash\nnpm install -g @anthropic-ai/claude-code@latest\n```\n\n### Docker permission issues\n\nAdd your user to the docker group:\n\n```bash\nsudo usermod -aG docker $USER\n# Log out and back in for changes to take effect\n```\n\n### Container cleanup\n\nRemove all Claude Sandbox containers and images:\n\n```bash\nnpm run purge-containers\n```\n\n### Credential discovery fails\n\nSet credentials explicitly:\n\n```bash\nexport ANTHROPIC_API_KEY=your-key\nexport GITHUB_TOKEN=your-token\n```\n\nOr use an `.env` file with `envFile` config option.\n\n### Build errors\n\nEnsure you're using Node.js \u003e= 18.0.0:\n\n```bash\nnode --version\n```\n\n## Development\n\n### Building from Source\n\nTo build and develop Claude Code Sandbox from source:\n\n```bash\ngit clone https://github.com/textcortex/claude-code-sandbox.git\ncd claude-code-sandbox\nnpm install\nnpm run build\nnpm link  # Creates global 'claude-sandbox' command\n```\n\n### Available Scripts\n\n- `npm run build` - Build TypeScript to JavaScript\n- `npm run dev` - Watch mode for development\n- `npm start` - Run the CLI\n- `npm run lint` - Run ESLint\n- `npm test` - Run tests\n- `npm run purge-containers` - Clean up all containers\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `npm test`\n5. Run linter: `npm run lint`\n6. Submit a pull request\n\n## License\n\nMIT\n","funding_links":[],"categories":["SDK与开发工具","Tools \u0026 Utilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftextcortex%2Fclaude-code-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftextcortex%2Fclaude-code-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftextcortex%2Fclaude-code-sandbox/lists"}