{"id":31012075,"url":"https://github.com/tthew/cc-devbox","last_synced_at":"2026-06-23T15:33:10.122Z","repository":{"id":306282945,"uuid":"1018692780","full_name":"tthew/cc-devbox","owner":"tthew","description":"A streamlined, secure containerized development environment optimized for Claude Code with DNS-based domain filtering and comprehensive development tools.","archived":false,"fork":false,"pushed_at":"2026-04-18T14:13:36.000Z","size":114,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T16:21:25.480Z","etag":null,"topics":["agentic-ai-development","claude","containerization","docker","gemini","llms","security","vibe-coding"],"latest_commit_sha":null,"homepage":"","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/tthew.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2025-07-12T20:25:56.000Z","updated_at":"2026-04-18T14:13:40.000Z","dependencies_parsed_at":"2025-07-24T20:37:43.522Z","dependency_job_id":"fb577a50-c6e8-41b0-9441-45fb70b52b4e","html_url":"https://github.com/tthew/cc-devbox","commit_stats":null,"previous_names":["tthew/cc-devbox"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tthew/cc-devbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tthew%2Fcc-devbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tthew%2Fcc-devbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tthew%2Fcc-devbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tthew%2Fcc-devbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tthew","download_url":"https://codeload.github.com/tthew/cc-devbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tthew%2Fcc-devbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34696897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agentic-ai-development","claude","containerization","docker","gemini","llms","security","vibe-coding"],"created_at":"2025-09-13T05:56:28.653Z","updated_at":"2026-06-23T15:33:10.102Z","avatar_url":"https://github.com/tthew.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cpre\u003e\n ████████╗████████╗██╗  ██╗███████╗██╗    ██╗    ██████╗ ███████╗██╗   ██╗\n ╚══██╔══╝╚══██╔══╝██║  ██║██╔════╝██║    ██║    ██╔══██╗██╔════╝██║   ██║\n    ██║      ██║   ███████║█████╗  ██║ █╗ ██║    ██║  ██║█████╗  ██║   ██║\n    ██║      ██║   ██╔══██║██╔══╝  ██║███╗██║    ██║  ██║██╔══╝  ╚██╗ ██╔╝\n    ██║      ██║   ██║  ██║███████╗╚███╔███╔╝    ██████╔╝███████╗ ╚████╔╝ \n    ╚═╝      ╚═╝   ╚═╝  ╚═╝╚══════╝ ╚══╝╚══╝     ╚═════╝ ╚══════╝  ╚═══╝  \n\u003c/pre\u003e\n\nA streamlined, secure containerized development environment optimized for Claude Code with DNS-based domain filtering and comprehensive development tools.\n\n## Features\n\n### 🔒 Security \u0026 Network Filtering\n- **DNS-based Domain Filtering**: Whitelist-only network access using dnsmasq\n- **Real-time Monitoring**: Track blocked/allowed requests with `monitor-blocks.sh`\n- **Secure Container**: Isolated environment with minimal attack surface\n\n### 🚀 Development Experience  \n- **Claude Code Integration**: Pre-configured with launcher scripts and proper permissions\n- **Enhanced Shell**: ZSH with autocompletion, persistent history, and development aliases\n- **Development Tools**: Node.js 20 LTS, Python 3 with uv, GitHub CLI, AWS CLI, Supabase CLI\n- **Persistent Environment**: Home directory and configurations survive container restarts\n\n### 🛠️ Management \u0026 Automation\n- **Make-based Commands**: 20+ commands for container lifecycle management\n- **Whitelist Management**: Simple commands to add/remove domains (`whitelist add domain.com`)\n- **Environment Validation**: Automated setup and configuration validation\n- **Performance Optimized**: M4 Pro specific optimizations with 8GB memory allocation\n\n## Quick Start\n\n### 1. Clone and Setup\n```bash\ngit clone git@github.com:tthew/cc-devbox.git\ncd cc-devbox\n\n# Build and start the development environment\nmake first-run\n```\n\n### 2. Start Development\n```bash\n# Start the container\nmake start\n```\n\n### 3. Access Development Environment\n```bash\n# SSH into the environment  \nmake shell\n\n# Launch Claude Code (inside container)\nclaude\n```\n\n## Core Commands\n\n### Container Management\n- `make start` - Start the development environment\n- `make stop` - Stop the development environment\n- `make restart` - Restart the environment\n- `make shell` - SSH into the container\n- `make claude` - Launch Claude Code directly\n- `make status` - Show container and port status\n- `make logs` - View container logs\n- `make clean` - Clean up containers and volumes\n\n### Environment Management\n- `make first-run` - Complete first-time setup\n- `make check-env` - Validate environment variables\n- `make rebuild` - Full rebuild with no cache\n\n## Domain Whitelist Management\n\n### Inside the Container\n```bash\n# Add domains to whitelist\nwhitelist add github.com\nwhitelist add anthropic.com\n\n# Remove domains\nwhitelist remove domain.com\n\n# List whitelisted domains\nwhitelist list\n\n# Monitor blocked/allowed requests\nmonitor-blocks.sh summary    # Show stats and recent activity\nmonitor-blocks.sh monitor    # Real-time monitoring\nmonitor-blocks.sh blocked    # Show only blocked requests\nmonitor-blocks.sh allowed    # Show only allowed requests\n```\n\n## Configuration\n\n### Git Configuration\n\nThe container requires git user configuration to function properly. You have two options:\n\n#### Option 1: Environment Variables (Recommended)\nCreate a `.env.host` file in the project root:\n```bash\n# .env.host (git-ignored)\nGIT_USER_NAME=\"Your Name\"\nGIT_USER_EMAIL=\"your.email@example.com\"\n```\n\nThen source it before starting the container:\n```bash\nsource .env.host\nmake start\n```\n\n#### Option 2: Container Environment\nSet environment variables when starting:\n```bash\ndocker-compose run -e GIT_USER_NAME=\"Your Name\" -e GIT_USER_EMAIL=\"your.email@example.com\" claude-dev\n```\n\nIf no configuration is provided, defaults will be used that remind you to configure properly.\n\n## Architecture\n\n### Core Components\n- **Dockerfile**: Ubuntu 24.04 with development tools and Claude Code\n- **docker-compose.yml**: Container orchestration with resource limits\n- **entrypoint.sh**: Container initialization and DNS filtering setup\n- **Makefile**: Comprehensive command interface\n\n### Network Security\n- **DNS Filtering**: `whitelist.conf` configures dnsmasq for domain filtering\n- **Default Deny**: All domains blocked by default, only whitelisted domains allowed\n- **Real-time Monitoring**: DNS queries logged to `/workspace/logs/dnsmasq.log`\n\n### Development Tools\n- **Shell Scripts**: \n  - `scripts/claude-launcher.sh` - Claude Code management\n  - `scripts/dev-helper.sh` - Development task automation\n  - `manage-whitelist.sh` - Advanced domain and IP management\n  - `monitor-blocks.sh` - Network activity monitoring\n\n### Persistent Storage\n- `/workspace` - Main project directory (mounted from host)\n- `dev-home/` - Persistent user configuration and Claude Code data\n- Environment configurations and SSH keys persist across rebuilds\n\n## Security Model\n\n### Network Isolation\n- Only whitelisted domains can be accessed\n- DNS queries are filtered through dnsmasq\n- All blocked requests are logged and can be monitored\n\n### Container Security\n- Runs as non-root `dev` user for development work\n- Limited capabilities (NET_ADMIN, NET_RAW for network management only)\n- Isolated file system with controlled volume mounts\n\n### Secret Management\n- SSH keys and authentication data in persistent `dev-home/`\n- No hardcoded credentials in the codebase\n- All secrets managed through secure container access\n\n## Troubleshooting\n\n### Container Issues\n```bash\n# Check container status\nmake status\n\n# View logs\nmake logs\n\n# Restart container\nmake restart\n```\n\n### Network/DNS Issues\n```bash\n# Inside container - test DNS resolution\nnslookup domain.com\n\n# Monitor DNS activity\nmonitor-blocks.sh monitor\n\n# Check whitelist\nwhitelist list\n```\n\n### Environment Issues\n```bash\n# Validate environment\nmake check-env\n\n# Show environment status\nmake env-status\n\n# Rebuild if needed\nmake rebuild\n```\n\n## File Structure\n\n```\ncc-devbox/\n├── Dockerfile                 # Container definition\n├── docker-compose.yml         # Container orchestration  \n├── Makefile                   # Command interface\n├── entrypoint.sh             # Container initialization\n├── whitelist.conf            # DNS filtering configuration\n├── CLAUDE.md                 # Claude Code specific documentation\n├── scripts/\n│   ├── claude-launcher.sh    # Claude Code management\n│   └── dev-helper.sh         # Development helpers\n├── monitor-blocks.sh         # Network monitoring tool\n├── manage-whitelist.sh       # Advanced whitelist management\n└── dev-home/                 # Persistent user configuration\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Test changes thoroughly with `make rebuild`\n4. Ensure security and documentation are updated\n5. Submit a pull request\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftthew%2Fcc-devbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftthew%2Fcc-devbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftthew%2Fcc-devbox/lists"}