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.

First-time quick start

• Prerequisites:

  • Docker
  • Python 3.10+ and pipx

• Install:

  pipx install aicage

• Navigate to your project directory and run:

  aicage --yes <agent>

--yes accepts suggested defaults and skips setup prompts. This is the fastest first run.

• Built-in agent examples:

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

Example output of first run with agent codex:

Full setup (optional)

If you want full interactive setup instead of defaults:

1. Show project config path and contents:

   aicage --config info

2. Remove config if needed:

   aicage --config remove
   aicage --config remove <agent>

3. Run again without --yes:

   aicage <agent>

Example output of full setup prompt flow:

Full documentation

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

Common scenarios

• Pass arguments to the agent:
  • aicage <agent> resume <session-id>
• Share additional host folders:
  • aicage --share ~/.m2 <agent>
  • aicage --share /path/to/data:ro <agent>
• Let the agent use Docker:
  • aicage --docker <agent>
• Set environment variables:
  • aicage -e FOO=bar -- <agent>
• Use proxies:
  • aicage forwards HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY.
  • See CLI options.
• Use host networking or custom networks:
  • See Host networking.
• On Windows with a Linux container/WSL workspace:
  • set git config --global core.autocrlf true on the Windows host to avoid line-ending diffs.
• Run into first-use setup issues:
  • See Known hiccups.
• Add custom tools/agents/base images:
  • Extensions
  • Custom agents
  • Custom base images

Built-in 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

aicage lets you customize images at three levels: extensions, agents, and base images. The sample repo is a fast way to see working examples and copy a template.

Quick start:

git clone https://github.com/aicage/aicage-custom-samples.git $HOME/.aicage-custom

Then run any agent:

aicage <agent>

These are only samples. Use them to learn the structure, then replace or edit them with your own definitions. aicage detects whatever you place under ~/.aicage-custom and offers it during selection.

After adding or changing custom definitions, restart aicage.

If your project is already configured for an agent, aicage will keep using the saved config. To reconfigure (and see new bases/agents/extensions), run aicage --config remove and start aicage again. To reset only one agent entry, use aicage --config remove <agent>. Use aicage --config info to inspect the current config.

• 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.
• -y, --yes applies default answers for all prompts and suppresses prompt output.
• --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.