Contagent: A Containerized Development Environment for AI Programming Assistants

A lightweight, provider-agnostic Docker environment designed to run AI programming agents (Claude Code, Codex, Gemini CLI, etc.) in Node.js 24 Alpine containers, addressing development environment consistency and permission management issues.

With the widespread adoption of Large Language Models (LLMs) in software development, an increasing number of developers are leveraging AI programming assistants to enhance productivity. Tools like Claude Code, OpenAI Codex, and Google Gemini CLI have emerged, offering developers robust capabilities for code generation, refactoring, and debugging. However, in practice, developers often encounter a challenging issue: how to maintain a consistent development experience across different machines and environments?

The complexity of local environment setup, dependency conflicts, permission problems, and differences between operating systems can all hinder AI tools from reaching their full potential. This is especially true for developers who switch between multiple devices or teams looking to quickly establish a unified development environment for new members.

Contagent is an open-source project aimed at addressing the above pain points through containerization technology. It provides a lightweight, provider-agnostic Docker environment specifically designed to run various AI programming agents in isolated containers. Built on the Node.js 24 Alpine image, it ensures a minimal image size and excellent startup speed.

Unlike traditional development environment configuration solutions, Contagent employs a unique user permission mapping mechanism. When the container starts, it automatically matches the UID and GID of the user inside the container with those of the host machine. This means that project files mounted into the container via bind mount retain the correct file ownership. This design detail is crucial for AI programming tools that frequently perform file read and write operations.

Contagent is designed with provider agnosticism in mind. The project supports multiple mainstream AI programming tools, including:

• Claude Code: AI programming assistant by Anthropic
• OpenAI Codex: Command-line tool for OpenAI's code generation model
• Google Gemini CLI: Command-line interface for Google's Gemini model

Users can switch or add desired AI tools by simply modifying the Dockerfile. This flexibility allows developers to choose the most suitable AI assistant based on project requirements or personal preferences without reconfiguring the entire development environment.

File permission issues have always been a common pain point in containerized development. Contagent implements dynamic UID/GID matching at runtime through the entrypoint.sh script. When the container starts, the script automatically detects the host machine's user ID and group ID, and creates the corresponding user account inside the container.

This mechanism ensures:

• Files created inside the container have the correct ownership on the host machine
• Existing files on the host can be read and written normally inside the container
• Avoids common issues in traditional solutions such as permission denials or files owned by root

To further simplify the usage process, the project maintainers provide prebuilt Docker images hosted on Docker Hub. Currently available tags include:

Tag	Tool Version
claude-4.7	Claude Code 4.7
codex-5.5	OpenAI Codex 5.5

Using prebuilt images saves local compilation time, making it especially suitable for CI/CD scenarios or use cases that require quick setup of new environments.

Contagent supports deep customization via environment variables:

• PATH_TO_WORKSPACE: Specifies the host path to mount to the /workspace directory inside the container
• HOST_UID / HOST_GID: Customize the UID and GID of the container user
• AGENT_USER: Set the username inside the container

These configurations can be be passed via .env files or command-line parameters, providing sufficient flexibility for different scenarios.

For developers who frequently switch between home computers, office laptops, and cloud servers, Contagent provides a consistent development experience. Simply clone the project repository and start the container to get the same AI programming tool configuration in any Docker-supported environment.