aicage 0.9.20

Runs agentic coding assistants in docker containers

aicage

Run your favorite AI coding agents comfortably in Docker.

Why use aicage?

Agents need deep access (read code, run shells, install deps). Their built-in safety checks are naturally limited.

Running agents in containers gives a hard boundary - while the experience stays the same. See Why cage agents? for the full rationale.

Quickstart

• Prerequisites:

  • Docker
  • Python 3.10+ and pipx

• Install:

  pipx install aicage
  

• Navigate to your project directory.

• Use one of these commands:

  aicage claude
  aicage codex
  aicage copilot
  aicage crush
  aicage droid
  aicage gemini
  aicage goose
  aicage opencode
  aicage qwen
  

Full documentation

The complete user documentation lives in the wiki: aicage.wiki

Base images

The first run asks which base image to use; pick Ubuntu or whatever matches your Linux distro.
All base images have the same stack of tools installed.

Agents

CLI	Agent	Homepage
claude	Claude Code	https://claude.com/product/claude-code
codex	Codex CLI	https://developers.openai.com/codex/cli
copilot	GitHub Copilot CLI	https://github.com/features/copilot/cli
crush	Crush	https://github.com/charmbracelet/crush
droid	Factory CLI	https://factory.ai/product/cli
gemini	Gemini CLI	https://geminicli.com
goose	Goose CLI	https://block.github.io/goose
opencode	OpenCode	https://opencode.ai
qwen	Qwen Code	https://qwenlm.github.io/qwen-code-docs

Your existing CLI config for each agent is mounted inside the container so you can keep using your preferences and credentials.

Customization

You can customize images at three levels: extensions, agents, and base images.

• Extensions: Customization-Extensions
• Custom agents: Customization-Agents
• Custom base images: Customization-Base-Images

Image updates are handled automatically; see Updates.

aicage options

• --dry-run prints the composed docker run command without executing it.
• --docker mounts /run/docker.sock into the container to enable Docker-in-Docker workflows.
• --share <path> mounts a host path into the container at the same path. Repeatable; add :ro for read-only.
• --config info prints the project config path and its contents.
• --config remove [<agent>] removes the full project config or only one agent entry.

Configuration file formats are documented in CONFIG.md. Extension authoring is documented in doc/extensions.md.

Why cage agents?

AI coding agents read your code, run shells, install packages, and edit files. That power is useful, but granting it directly on the host expands your risk surface.

Where built-in safety is limited:

• Allow/deny lists only cover known patterns; unexpected commands or attack paths can slip through.
• Some agents work fully only after relaxing their own safety modes, broadening what they can touch.
• “Read-only project” features are software rules. Other projects and files still sit alongside them on the same host.

How aicage mitigates this:

• Containers create a hard boundary: the agent can access only what you explicitly mount. Day-to-day use stays familiar—just with the host kept out of reach.