This project provides an isolated Docker environment for running autonomous coding harnesses, such as OpenCode, Codex, and Claude Code. It targets developers, researchers, and power users who need a secure sandbox to grant AI agents full permissions for coding tasks without risking their host system. The primary benefit is a lightweight, persistent, and secure environment that simplifies the setup and execution of complex AI development workflows.

How It Works

The core approach leverages Docker to create isolated environments. The code-container tool manages the build and execution of a multi-stage Docker image. This image is constructed in cascading stages: a base Core stage with system dependencies and Node/Python, a customizable Packages stage for large user-specified dependencies, a Harness stage containing pre-packaged AI models, and a User stage for custom tooling and setup scripts. Configuration files for AI harnesses are automatically mounted, and the container's state, including AI conversations and settings, persists across sessions, allowing users to resume work seamlessly.

Quick Start & Requirements

• Prerequisites: Docker (Desktop or Engine), a POSIX-compatible system (Linux, macOS, WSL).
• Installation: npm install -g code-container
• Setup:
  1. Run container init to copy AI harness configurations.
  2. Run container build to construct the Docker image (estimated 5 minutes).
• Usage: Navigate to your project directory and run container.
• Links: No official documentation or demo links are provided beyond the command-line interface.

Highlighted Details

• Isolation: Protects the host filesystem from destructive actions performed within the container.
• Persistence: Container state, AI conversations, and settings are saved and persist across sessions and projects.
• Customization: The Docker image build process is highly customizable via ~/.code-container/Dockerfile.Packages and ~/.code-container/Dockerfile.User, allowing addition of specific tools and dependencies. Mount points and Docker flags can also be configured.
• Simultaneous Work: Designed to support multiple agents and users working concurrently on the same project, with specific recommendations to avoid conflicts like simultaneous Git operations.

Maintenance & Community

No specific details regarding maintainers, sponsorships, or community channels (e.g., Discord, Slack) are present in the README. The project does mention a related tool, Nitro (@aerovato/nitro).

Licensing & Compatibility

The README does not explicitly state a software license. While the distribution method (NPM package) and technology stack (Docker) suggest an open-source nature, specific licensing terms and compatibility for commercial use or closed-source linking are not detailed.

Limitations & Caveats

The container does not inherently protect against prompt injection attacks or network exfiltration if an AI agent becomes compromised or misaligned; sensitive information can still be leaked over the network. While the container isolates destructive commands from the host, project files within the container are still susceptible to deletion by the harness, necessitating reliance on upstream version control. Simultaneous Git operations or installation of conflicting Node modules between the host and container, or between multiple containers, can lead to issues.