container

container: Isolated Docker environments for your autonomous coding harnesses.

Simple. Lightweight. Secure.

Quickstart

Prerequisites

• Docker or Podman — Docker Desktop/Engine or Podman
• A POSIX-Compatible System — Linux, macOS, WSL

Installation

1. container is available as an NPM package. Install with:

   npm uninstall -g code-container      # Uninstall V2 if present
   npm install -g @aerovato/container   # Install container V3
   

2. Run container init (interactive onboarding). It will:

   • Detect installed harnesses (Claude Code, OpenCode, etc.)
   • Migrate your existing configs
   • Let you choose Docker or Podman
   • Configure SSH and git mounts

   Accept the prompt to build the image (first build can take 5+ minutes).

You're done. container is ready to use.

Shameless Self-Promotion

Try Nitro, a simple and efficient Bash harness. 11x cheaper, 75x more efficient than Claude Code for simple Bash tasks.

npm install -g @aerovato/nitro

Usage

Navigate to any project and run container:

cd /path/to/your/project
container

Inside the container: Start your harness and develop like normal.

opencode                     # Start OpenCode
npm install <package>        # Persists per container
# ...

Your project is mounted at /root/<project-name>. Changes persist across sessions. Harness configs are shared across all containers.

You may want to periodically rebuild the image to update harnesses and packages:

container build               # Trigger full rebuild
container build harness       # Rebuild harnesses and user packages
container build user          # Rebuild user packages

Common Commands

container                           # Enter container for current directory
container run /path/to/project      # Enter for a specific project
container run /path -- -p 8080:80   # Pass extra runtime flags
container list                      # List all containers
container stop                      # Stop container
container remove                    # Remove container
container init                      # Re-run onboarding

Customization

Customization is done through two places:

1. ~/.code-container/Dockerfile.User

Add packages and setup steps here. Example:

FROM localhost/aerovato/container-v3-harness:latest

RUN npm install -g bun typescript
RUN pip install requests

RUN npx opencode plugin opencode-quotes-plugin -g

After editing, run container build user to rebuild the image

2. ~/.code-container/settings.json

Primary configuration file. See docs/Settings.md for more details.

Common settings:

• enabledHarnesses — which harnesses to install
• runtime — "docker" or "podman"
• dockerfileCore — advanced control over the base image
• systemMounts — gitconfig and SSH mounts
• dockerRunFlags / dockerExecFlags — extra runtime flags

Hint: Clone this repo and ask your agent to configure for you.

For V2 Users

After upgrading to V3, all configurations will be archived to ~/.code-container/archive. To migrate configurations over, ask your agent to read and perform the steps in docs/Migration.md.

Features

• Isolation — Destructive actions stay inside the container
• 3-Stage Builds — Core → Harness → User (rebuild only what changed)
• Configurable Runtime — Docker or Podman
• Harness Packs — Choose exactly which tools to enable
• Persistent State — Workspaces and configs survive across sessions
• Simultaneous Work — Multiple agents can safely work on the same project

Security

• container protects your host filesystem from rm -rfs
• Packages and configurations inside containers stay localized
• Isolation prevents cross-contamination across containers

Important limitations:

• container does not protect against prompt injection or agent misalignment
• Network access is available inside the container
• Harness configs will be mounted inside container

Uninstall

npm uninstall -g @aerovato/container
rm -rf ~/.code-container

Consider backing up the harness configurations in ~/.code-container/configs before removing.