code-container

[!Note] Are you still on the shell script version of container? Migrate to the NPM package by running the following:

# Exit all containers & save important work...
npm install -g code-container
bash scripts/migrate.sh     # Migrate configs over to ~/.code-container/configs
bash scripts/cleanup.sh     # Optional: Cleanup config files
container build

Note: Ensure that all work is saved and the container is ready for deletion. Containers from the previous version are not compatible with containers from the current version.

Try Nitro

Psst: Try my newest project: Nitro, a simple and efficient Bash harness. 11x cheaper; 75x more efficient vs Claude Code for Bash tasks.

npm install -g @aerovato/nitro

Usage

Navigate to any project and run container to mount project and enter container.

cd /path/to/your/project
container                    # Enter container

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

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

Container state is saved. Next invocation resumes where you left off. AI conversations and settings persist across all projects.

Common Commands

container                  # Enter the container
container run /path/to     # Enter container for specific project
container list             # List all containers
container stop             # Stop current project's container
container remove            # Remove current project's container
container build            # Build Docker image
container clean            # Remove all stopped containers
container init             # Copy/recopy config files

Features

Unhindered Agents

Don't want to configure manually? Clone this repo and ask your harness to configure for you.

Please configure all my container harnesses to run without permissions.

Destructive actions are localized inside containers.

• You can let your harness run with full permissions
• To configure your harness to run without permissions, see Permissions.md.

Customization

Don't want to customize manually? Clone this repo and ask your harness to customize for you.

Add the following packages to the container environment: ...
Add the following Docker flags to the container environment: ...
Add a custom mount point to the container environment: ...

Easily add your own tooling & mount points.

Adding tools/packages: Edit ~/.code-container/Dockerfile.User and rebuild:

FROM code-container-base:latest

RUN apt-get update && apt-get install -y postgresql-client redis-tools

Deprecation Notice: ~/.code-container/Dockerfile is deprecated and no longer used. If you previously customized this file, migrate your custom RUN commands to ~/.code-container/Dockerfile.User.

Adding mount points: Edit ~/.code-container/MOUNTS.txt and reinitialize containers:

/absolute/path/on/host:/path/in/container
/absolute/path/on/host:/path/in/container:ro

Adding Docker flags:

Edit ~/.code-container/DOCKER_FLAGS.txt to pass additional flags to both docker run and docker exec:

# Environment variables
-e MY_VAR=value

For flags that only apply to docker run (e.g. port forwarding, network, GPU), use ~/.code-container/DOCKER_RUN_FLAGS.txt:

# Port forwarding
-p 4040:4040
-p 3000:3000

# GPU support
--gpus all

Each line is parsed like a shell command. Empty lines and lines starting with # are ignored.

Security

• Host filesystem protected; destructive operations will only affect the container
• Project isolation prevents cross-contamination across containers
• Note: Git config and SSH keys are mounted read-only from host to support Git operations.
• Caution: Project files can still be deleted by harness; always use upstream version control
• Caution: Network access is still available; information may still be exfiltrated over network

⚠️ Security Advisory:

• The main purpose of container is to protect commands like rm or apt from unintentionally affecting your system.
  • container assumes that your agent is acting in good faith.
• container does not protect from prompt injections or network exfiltration in the event that an agent becomes malaligned.
  • Users are advised to not download or work with unverified software even within the container.
  • Sensitive information inside the container may still be exfiltrated by an attacker just as with your regular system. This includes:
    • OAuth credentials inside harness configs
    • API keys inside harness configs
    • SSH keys for git functionality

Simultaneous Work

You and multiple agents can work on the same project simultaneously.

• Safe: Reading files, editing files, most development operations
• Avoid: Simultaneous Git operations from both sides, installing conflicting node_modules
• Recommended Workflow: Let your harness run autonomously in the container while you work; review changes and commit.

Persistence

• Changes within a container persists across sessions.
• Harness configurations and configuration histories are shared across containers.

Uninstalling

To uninstall container, uninstall the NPM package and remove ~/.code-container:

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

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