{"id":43703207,"url":"https://github.com/technicalpickles/agentic-container","last_synced_at":"2026-02-05T05:10:58.857Z","repository":{"id":314988723,"uuid":"1057439108","full_name":"technicalpickles/agentic-container","owner":"technicalpickles","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-26T09:13:56.000Z","size":813,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T23:46:06.292Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/technicalpickles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-15T18:16:17.000Z","updated_at":"2026-01-26T09:13:59.000Z","dependencies_parsed_at":"2025-09-16T04:22:48.062Z","dependency_job_id":"4fe48dcf-320f-4bfd-943a-14ae85a6ff76","html_url":"https://github.com/technicalpickles/agentic-container","commit_stats":null,"previous_names":["technicalpickles/agentic-container"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/technicalpickles/agentic-container","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fagentic-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fagentic-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fagentic-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fagentic-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/technicalpickles","download_url":"https://codeload.github.com/technicalpickles/agentic-container/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fagentic-container/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29113202,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T03:44:17.043Z","status":"ssl_error","status_checked_at":"2026-02-05T03:44:12.077Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":[],"created_at":"2026-02-05T05:10:58.757Z","updated_at":"2026-02-05T05:10:58.848Z","avatar_url":"https://github.com/technicalpickles.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentic Container\n\nA fast, reliable container environment optimized for AI agent execution in cloud\nplatforms. Provides a solid foundation with agent tooling and mise version\nmanager, designed to be extended with exactly the languages and tools your\nagents need.\n\n## 🤖 Built for AI Agents\n\nOptimized for cloud providers offering agentic experiences like Cursor\nBackground Agents, Replit AI, and similar platforms:\n\n- **Fast startup time**: Pre-installed agent toolchain for quick execution\n- **Headless execution**: No interactive prompts, reliable automation\n- **Code analysis ready**: ast-grep and ripgrep pre-installed, Python/Node.js\n  standard\n- **MCP server ready**: uv/uvx and npx universal package runners available\n- **Extension-friendly**: Easy to customize for specific agent workflows\n\n## 🚀 Quick Start with AI Coding Agents\n\nAll AI coding agents are pre-installed and ready to use! Just run the container\nand start with your preferred agent:\n\n### Claude Code ([docs](https://docs.anthropic.com/en/docs/claude-code/setup))\n\n```bash\n# Start Claude Code directly - authenticate when prompted\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest claude\n\n# Or start with a specific prompt\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest claude \"explain this codebase\"\n```\n\n### OpenAI Codex CLI ([docs](https://developers.openai.com/codex/cli/))\n\n```bash\n# Start Codex CLI - authenticate when prompted\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest codex\n\n# Or start with a specific task\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest codex \"fix the CI failure\"\n```\n\n### GitHub Copilot CLI ([docs](https://docs.github.com/en/copilot/how-tos/use-copilot-for-common-tasks/use-copilot-in-the-cli))\n\n```bash\n# Authenticate with GitHub first, then use Copilot\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest bash -c \"gh auth login \u0026\u0026 gh copilot suggest 'install dependencies'\"\n\n# Or use for code explanation\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest gh copilot explain \"git rebase -i HEAD~3\"\n```\n\n### Goose ([docs](https://block.github.io/goose/docs/getting-started/installation))\n\n```bash\n# Start Goose session - configure provider when prompted\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest goose session\n\n# Or use Goose CLI for quick tasks\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest goose exec \"analyze code quality\"\n```\n\n### OpenCode.ai ([docs](https://opencode.ai/))\n\n```bash\n# Start OpenCode with terminal UI\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest opencode\n\n# Use specific model provider\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest opencode --provider anthropic\n```\n\n### Experimenting with the container\n\n```bash\n# Use the dev environment for quick experimentation\ndocker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:dev bash\n# Then run: claude, codex, gh copilot, goose, or opencode\n```\n\n## 📦 Available Images\n\n| Image Tag | Description                                          | Size   | Maintenance Level       | Use Case                                   |\n| --------- | ---------------------------------------------------- | ------ | ----------------------- | ------------------------------------------ |\n| `latest`  | Ubuntu + mise + Python + Node.js + ast-grep + uv/uvx | ~950MB | **Actively maintained** | Production-ready base for agent deployment |\n| `dev`     | Latest + all languages                               | ~2.2GB | **Example only**        | Agent prototyping and experimentation      |\n\n### 🤔 When to Use Which Image?\n\n| Scenario                        | Recommended Image                       | Why?                                                |\n| ------------------------------- | --------------------------------------- | --------------------------------------------------- |\n| **Production agent deployment** | `latest` + extensions                   | Smaller, controlled dependencies, maintained        |\n| **Cloud agent platforms**       | `latest` + extensions                   | Predictable, minimal, fast startup                  |\n| **Background agent processing** | `latest` + extensions                   | Consistent environment, documented requirements     |\n| **Agent prototyping**           | `dev`                                   | All languages ready, fastest to start experimenting |\n| **Development environments**    | `latest` + project tools                | Optimized for the languages your projects use       |\n| **Unknown agent requirements**  | Start with `dev`, then create extension | Explore needs, then optimize                        |\n\n## 🔧 What's Included\n\n### Core Tools (`latest` image)\n\n- **Python** + **Node.js** (latest stable versions) - Standard runtime\n  environments for agents\n- **AI Coding Agents** - All pre-installed and ready to use:\n  - **Claude Code** (`claude` command) - Anthropic's AI coding assistant\n  - **OpenAI Codex CLI** (`codex` command) - OpenAI's coding agent\n  - **GitHub Copilot CLI** (`gh copilot` command) - GitHub's AI pair programmer\n  - **Goose** (`goose` command) - Block's AI coding assistant\n  - **OpenCode.ai** (`opencode` command) - Terminal-based AI coding agent\n- **ast-grep** - Structural code search and analysis tool (installed via mise)\n- **uv/uvx** - Fast Python package installer and universal script runner for MCP\n  servers (installed via mise)\n- **mise** - Universal version manager for additional languages and tools\n- **Docker CLI** + Docker Compose - Container orchestration capabilities\n- **Git** + **GitHub CLI** - Version control and GitHub integration with agent\n  workflows\n- **Essential CLI tools** - vim, nano, jq, curl, tree, htop, ripgrep for agent\n  scripting\n- **Non-root user** - Security-conscious execution environment\n- **Optimized shell** - Configured bash environment for headless operations\n\n### Additional Languages (`dev` image only)\n\nThe `dev` image includes pre-installed language runtimes for quick agent\nexperimentation:\n\n- **Ruby** + **Node.js** + **Python** + **Go** (all latest stable versions)\n- **Lefthook** - Git hooks manager\n\n\u003e **Note**: For production agent deployment, extend `latest` with only the\n\u003e languages your agents need rather than using the large `dev` image. Pin\n\u003e specific versions using `mise use` or `.mise.toml` files.\n\n## 🏗️ Extending for Different Technology Stacks\n\nThe recommended approach is to extend the `latest` image with exactly the\nlanguages and tools your **application stack needs**. All AI agents are\npre-installed and ready to work with any stack you configure. Focus on the\nruntime environment for your specific application type.\n\nFor examples, see [docs/cookbooks](docs/cookbooks/README.md)\n\n## 🔄 Cursor Background Agent Integration\n\nYour agentic-container provides development environments that work seamlessly\nwith Cursor Background Agents, Claude Code, Codex CLI, and other AI coding\ntools.\n\n### Environment Configuration\n\nCreate `.cursor/environment.json` for containerized agent development:\n\n```json\n{\n  \"name\": \"Agentic Container Development\",\n  \"dockerComposeFile\": \"docker-compose.yml\",\n  \"service\": \"dev\",\n  \"install\": \"mise install \u0026\u0026 pip install fastapi sqlalchemy pytest\",\n  \"terminals\": [\n    {\n      \"name\": \"FastAPI Development\",\n      \"command\": \"python -c 'import fastapi; print(\\\"FastAPI development environment ready\\\")'\"\n    },\n    {\n      \"name\": \"Code Analysis\",\n      \"command\": \"sg --version \u0026\u0026 echo 'ast-grep ready for structural code search'\"\n    },\n    {\n      \"name\": \"Package Tools\",\n      \"command\": \"uvx --version \u0026\u0026 npm --version \u0026\u0026 echo 'Package runners ready'\"\n    }\n  ]\n}\n```\n\n### Best Practices for Background Agents\n\n- **Use `standard` + extensions** for Background Agent environments (not `dev` -\n  it's too large)\n- **Mount code as volume** to enable agent file modifications\n- **Include `.dockerignore`** to optimize build context for faster agent startup\n- **Set non-interactive environment** for reliable automation\n- **Pre-install agent dependencies** in your extended image for faster execution\n\n### Example Extended Image for Background Agents\n\n```dockerfile\nFROM ghcr.io/technicalpickles/agentic-container:standard\n\n# Set up development environment for the project agents will work on\nRUN mise use -g python@3.13.7 node@22.12.0 \u0026\u0026 \\\n    pip install fastapi sqlalchemy alembic pytest \u0026\u0026 \\\n    npm install -g typescript @types/node vitest\n\n# Verify development environment is ready for agent work\nRUN python3 -c \"import fastapi; print('FastAPI project environment ready')\" \u0026\u0026 \\\n    tsc --version\n\nWORKDIR /workspace\n```\n\n## 🔄 GitHub Actions Integration\n\nAutomate your custom image builds with GitHub Actions:\n\n1. Copy the template workflow:\n\n   ```bash\n   # GitHub Actions workflow templates are available in the cookbooks documentation\n   # See docs/cookbooks/ for extension examples and patterns\n   ```\n\n2. Customize for your needs:\n\n   ```yaml\n   - name: Build and push Docker image\n     uses: docker/build-push-action@v5\n     with:\n       context: .\n       file: ./path/to/your/Dockerfile # Optional\n       platforms: linux/amd64,linux/arm64\n       push: ${{ github.event_name != 'pull_request' }}\n       tags: ${{ steps.meta.outputs.tags }}\n   ```\n\n3. Enable GitHub Container Registry in your repository settings\n\n4. Push changes - your custom image will be built and published automatically!\n\n## 🧑‍💻 Container Usage\n\n### VS Code Dev Containers (for agent development)\n\nFor custom agent development environments, create a `Dockerfile` and reference\nit:\n\n```dockerfile\n# .devcontainer/Dockerfile\nFROM ghcr.io/technicalpickles/agentic-container:latest\n\nRUN mise use -g python@3.13.7 node@22.12.0 \u0026\u0026 \\\n    pip install anthropic pydantic python-dotenv \u0026\u0026 \\\n    npm install -g typescript\n```\n\n```json\n{\n  \"name\": \"My Agent Development Environment\",\n  \"build\": {\n    \"dockerfile\": \"Dockerfile\"\n  },\n  \"customizations\": {\n    \"vscode\": {\n      \"extensions\": [\"ms-python.python\", \"ms-vscode.vscode-typescript-next\"]\n    }\n  },\n  \"mounts\": [\n    \"source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind\"\n  ],\n  \"privileged\": true\n}\n```\n\n### Quick Claude Agent Prototyping with Pre-built Dev Image\n\nFor quick Claude agent experimentation, you can use the `dev` image directly:\n\n```json\n{\n  \"name\": \"Quick Claude Agent Prototyping Environment\",\n  \"image\": \"ghcr.io/technicalpickles/agentic-container:dev\",\n  \"postCreateCommand\": \"pip install anthropic pydantic python-dotenv\",\n  \"mounts\": [\n    \"source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind\"\n  ],\n  \"privileged\": true\n}\n```\n\n### Docker Compose\n\n```yaml\nservices:\n  dev:\n    build:\n      context: .\n      dockerfile: Dockerfile.dev # Your custom extension\n    volumes:\n      - .:/workspace\n      - /var/run/docker.sock:/var/run/docker.sock\n    working_dir: /workspace\n    tty: true\n    stdin_open: true\n\n  # Or for quick prototyping:\n  prototype:\n    image: ghcr.io/technicalpickles/agentic-container:dev\n    volumes:\n      - .:/workspace\n      - /var/run/docker.sock:/var/run/docker.sock\n    working_dir: /workspace\n    tty: true\n    stdin_open: true\n```\n\n## 🔍 Architecture\n\nThe simplified architecture focuses on maintainability and flexibility:\n\n```\nubuntu:24.04 (base OS)\n├── standard (latest) → Ubuntu + mise + starship + dev tools (~750MB)\n│   └── [Your Extensions] → Add languages via mise as needed\n└── dev → Standard + all languages pre-installed (~2.2GB, example only)\n```\n\n### Design Principles\n\n- **Single Maintained Base**: Focus on one solid foundation (`latest`)\n- **Extension Pattern**: Add only what you need via mise\n- **Predictable Structure**: Clear path from base to custom environment\n- **Layer Optimization**: Minimize layers in your extensions\n\n### Why This Approach?\n\n- **Maintainable**: One image to keep updated instead of many variants\n- **Flexible**: Get exactly the languages and tools you need\n- **Predictable**: Consistent base across all use cases\n- **Efficient**: Shared base layer, custom extension layers\n\n### Extension Best Practices\n\n```dockerfile\nFROM ghcr.io/technicalpickles/agentic-container:latest\n\n# ✅ Good: Python and Node.js already available - just add packages\nRUN pip install fastapi anthropic \u0026\u0026 \\\n    npm install -g typescript\n\n# ✅ Good: Install additional languages efficiently with specific versions\nRUN mise use -g go@1.23.5 ruby@3.3.6 \u0026\u0026 \\\n    go install example.com/tool@latest \u0026\u0026 \\\n    gem install rails rake\n\n# ❌ Avoid: Multiple RUN commands create unnecessary layers\n# RUN mise use -g go@1.23.5\n# RUN go install example.com/tool@latest\n# RUN gem install rails rake\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/my-new-feature`\n3. Test your changes with different base images\n4. Commit your changes: `git commit -am 'Add some feature'`\n5. Push to the branch: `git push origin feature/my-new-feature`\n6. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file\nfor details.\n\n## 🆘 Support\n\n- **Documentation**: Check the `docs/` directory for detailed guides\n- **Issues**: Open an issue on GitHub for bugs or feature requests\n- **Discussions**: Use GitHub Discussions for questions and community support\n\n---\n\n**Built with ❤️ for the AI agent community**\n\n\u003c!-- AUTO-GENERATED-CONTENT-START --\u003e\n    \u003c!-- This section is automatically updated by GitHub Actions --\u003e\n    *Last documentation update: 2025-11-25T18:31:38+00:00*\n\u003c!-- AUTO-GENERATED-CONTENT-END --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicalpickles%2Fagentic-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnicalpickles%2Fagentic-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicalpickles%2Fagentic-container/lists"}