A fast, reliable container environment optimized for AI agent execution in cloud platforms. Provides a solid foundation with agent tooling and mise version manager, designed to be extended with exactly the languages and tools your agents need.

Optimized for cloud providers offering agentic experiences like Cursor Background Agents, Replit AI, and similar platforms:

• Fast startup time: Pre-installed agent toolchain for quick execution
• Headless execution: No interactive prompts, reliable automation
• Code analysis ready: ast-grep and ripgrep pre-installed, Python/Node.js standard
• MCP server ready: uv/uvx and npx universal package runners available
• Extension-friendly: Easy to customize for specific agent workflows

All AI coding agents are pre-installed and ready to use! Just run the container and start with your preferred agent:

# Start Claude Code directly - authenticate when prompted
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest claude

# Or start with a specific prompt
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest claude "explain this codebase"

# Start Codex CLI - authenticate when prompted
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest codex

# Or start with a specific task
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest codex "fix the CI failure"

# Authenticate with GitHub first, then use Copilot
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest bash -c "gh auth login && gh copilot suggest 'install dependencies'"

# Or use for code explanation
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest gh copilot explain "git rebase -i HEAD~3"

# Start Goose session - configure provider when prompted
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest goose session

# Or use Goose CLI for quick tasks
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest goose exec "analyze code quality"

# Start OpenCode with terminal UI
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest opencode

# Use specific model provider
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:latest opencode --provider anthropic

# Use the dev environment for quick experimentation
docker run -it --rm -v $(pwd):/workspace ghcr.io/technicalpickles/agentic-container:dev bash
# Then run: claude, codex, gh copilot, goose, or opencode

• Python + Node.js (latest stable versions) - Standard runtime environments for agents
• AI Coding Agents - All pre-installed and ready to use:
  • Claude Code (claude command) - Anthropic's AI coding assistant
  • OpenAI Codex CLI (codex command) - OpenAI's coding agent
  • GitHub Copilot CLI (gh copilot command) - GitHub's AI pair programmer
  • Goose (goose command) - Block's AI coding assistant
  • OpenCode.ai (opencode command) - Terminal-based AI coding agent
• ast-grep - Structural code search and analysis tool (installed via mise)
• uv/uvx - Fast Python package installer and universal script runner for MCP servers (installed via mise)
• mise - Universal version manager for additional languages and tools
• Docker CLI + Docker Compose - Container orchestration capabilities
• Git + GitHub CLI - Version control and GitHub integration with agent workflows
• Essential CLI tools - vim, nano, jq, curl, tree, htop, ripgrep for agent scripting
• Non-root user - Security-conscious execution environment
• Optimized shell - Configured bash environment for headless operations

The dev image includes pre-installed language runtimes for quick agent experimentation:

• Ruby + Node.js + Python + Go (all latest stable versions)
• Lefthook - Git hooks manager

Note: For production agent deployment, extend latest with only the languages your agents need rather than using the large dev image. Pin specific versions using mise use or .mise.toml files.

The recommended approach is to extend the latest image with exactly the languages and tools your application stack needs. All AI agents are pre-installed and ready to work with any stack you configure. Focus on the runtime environment for your specific application type.

For examples, see docs/cookbooks

Your agentic-container provides development environments that work seamlessly with Cursor Background Agents, Claude Code, Codex CLI, and other AI coding tools.

Create .cursor/environment.json for containerized agent development:

{
  "name": "Agentic Container Development",
  "dockerComposeFile": "docker-compose.yml",
  "service": "dev",
  "install": "mise install && pip install fastapi sqlalchemy pytest",
  "terminals": [
    {
      "name": "FastAPI Development",
      "command": "python -c 'import fastapi; print(\"FastAPI development environment ready\")'"
    },
    {
      "name": "Code Analysis",
      "command": "sg --version && echo 'ast-grep ready for structural code search'"
    },
    {
      "name": "Package Tools",
      "command": "uvx --version && npm --version && echo 'Package runners ready'"
    }
  ]
}

• Use standard + extensions for Background Agent environments (not dev - it's too large)
• Mount code as volume to enable agent file modifications
• Include .dockerignore to optimize build context for faster agent startup
• Set non-interactive environment for reliable automation
• Pre-install agent dependencies in your extended image for faster execution

FROM ghcr.io/technicalpickles/agentic-container:standard

# Set up development environment for the project agents will work on
RUN mise use -g python@3.13.7 node@22.12.0 && \
    pip install fastapi sqlalchemy alembic pytest && \
    npm install -g typescript @types/node vitest

# Verify development environment is ready for agent work
RUN python3 -c "import fastapi; print('FastAPI project environment ready')" && \
    tsc --version

WORKDIR /workspace

Automate your custom image builds with GitHub Actions:

1. Copy the template workflow:

   # GitHub Actions workflow templates are available in the cookbooks documentation
   # See docs/cookbooks/ for extension examples and patterns

2. Customize for your needs:

   - name: Build and push Docker image
     uses: docker/build-push-action@v5
     with:
       context: .
       file: ./path/to/your/Dockerfile # Optional
       platforms: linux/amd64,linux/arm64
       push: ${{ github.event_name != 'pull_request' }}
       tags: ${{ steps.meta.outputs.tags }}

3. Enable GitHub Container Registry in your repository settings

4. Push changes - your custom image will be built and published automatically!

For custom agent development environments, create a Dockerfile and reference it:

# .devcontainer/Dockerfile
FROM ghcr.io/technicalpickles/agentic-container:latest

RUN mise use -g python@3.13.7 node@22.12.0 && \
    pip install anthropic pydantic python-dotenv && \
    npm install -g typescript

{
  "name": "My Agent Development Environment",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python", "ms-vscode.vscode-typescript-next"]
    }
  },
  "mounts": [
    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
  ],
  "privileged": true
}

For quick Claude agent experimentation, you can use the dev image directly:

{
  "name": "Quick Claude Agent Prototyping Environment",
  "image": "ghcr.io/technicalpickles/agentic-container:dev",
  "postCreateCommand": "pip install anthropic pydantic python-dotenv",
  "mounts": [
    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
  ],
  "privileged": true
}

services:
  dev:
    build:
      context: .
      dockerfile: Dockerfile.dev # Your custom extension
    volumes:
      - .:/workspace
      - /var/run/docker.sock:/var/run/docker.sock
    working_dir: /workspace
    tty: true
    stdin_open: true

  # Or for quick prototyping:
  prototype:
    image: ghcr.io/technicalpickles/agentic-container:dev
    volumes:
      - .:/workspace
      - /var/run/docker.sock:/var/run/docker.sock
    working_dir: /workspace
    tty: true
    stdin_open: true

The simplified architecture focuses on maintainability and flexibility:

ubuntu:24.04 (base OS)
├── standard (latest) → Ubuntu + mise + starship + dev tools (~750MB)
│   └── [Your Extensions] → Add languages via mise as needed
└── dev → Standard + all languages pre-installed (~2.2GB, example only)

• Single Maintained Base: Focus on one solid foundation (latest)
• Extension Pattern: Add only what you need via mise
• Predictable Structure: Clear path from base to custom environment
• Layer Optimization: Minimize layers in your extensions

• Maintainable: One image to keep updated instead of many variants
• Flexible: Get exactly the languages and tools you need
• Predictable: Consistent base across all use cases
• Efficient: Shared base layer, custom extension layers

FROM ghcr.io/technicalpickles/agentic-container:latest

# ✅ Good: Python and Node.js already available - just add packages
RUN pip install fastapi anthropic && \
    npm install -g typescript

# ✅ Good: Install additional languages efficiently with specific versions
RUN mise use -g go@1.23.5 ruby@3.3.6 && \
    go install example.com/tool@latest && \
    gem install rails rake

# ❌ Avoid: Multiple RUN commands create unnecessary layers
# RUN mise use -g go@1.23.5
# RUN go install example.com/tool@latest
# RUN gem install rails rake

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-new-feature
3. Test your changes with different base images
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin feature/my-new-feature
6. Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

• Documentation: Check the docs/ directory for detailed guides
• Issues: Open an issue on GitHub for bugs or feature requests
• Discussions: Use GitHub Discussions for questions and community support

Built with ❤️ for the AI agent community

<!-- This section is automatically updated by GitHub Actions -->
*Last documentation update: 2025-11-25T18:31:38+00:00*