Home

aicage wiki

Run AI coding agents in Docker with a clean separation between your host and the agent runtime.

Start here

• How it works
• CLI options
• Docker run pass-through args
• Images and layers
• Base image tooling
• Known hiccups
• Host networking
• Customization entry point
• Update behavior
• How to debug

First-time quick start

• Prerequisites:
  • Docker
  • Python 3.10+ and pipx
• Install:

pipx install aicage

• Navigate to your project directory and run:

cd /path/to/project
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

aicage mounts your project and your agent config into a container that already has a full dev toolchain and the agent.

You can also add your own custom agents. See Customization.

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>

4. Screenshot placeholder: full setup prompt flow

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