aicage 0.8.0

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 codex
  aicage copilot
  aicage gemini
  aicage goose
  aicage opencode
  aicage qwen
  

Base images

The first run asks which base image to use; pick Ubuntu or whatever matches your Linux distro.

Base	Distro	Notes
ubuntu	Ubuntu	Good default for most users
debian	Debian	For Debian users
fedora	Fedora	For RedHat/Fedora users
alpine	Alpine	Minimal footprint; experimental
node	Ubuntu	Official Node image (all base images have Node)
act	Ubuntu	Default runner image from act (act runs GitHub Actions locally)

All base images have the same stack of tools installed.

Agents

CLI	Agent	Homepage
codex	Codex CLI	https://developers.openai.com/codex/cli
copilot	GitHub Copilot CLI	https://github.com/features/copilot/cli
gemini	Gemini CLI	https://geminicli.com
goose	Goose CLI	https://block.github.io/goose
opencode	OpenCode	https://qwenlm.github.io/qwen-code-docs
qwen	Qwen Code	https://opencode.ai

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

aicage options

• --dry-run prints the composed docker run command without executing it.
• --aicage-entrypoint PATH mounts a custom entrypoint script to /usr/local/bin/entrypoint.sh.
• --docker mounts /run/docker.sock into the container to enable Docker-in-Docker workflows.
• --config print prints the project config path and its contents.

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.

Development info

More details are in DEVELOPMENT.md.