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
• Host networking
• Customization entry point
• Known hiccups
• Security and trust
• 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.

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

2. Remove config if needed:

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

3. Run again without --yes:

   aicage <agent>

Example output of full setup

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>
  • Extensions can also define extra shares (host mounts).
• 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://goose-docs.ai
opencode	OpenCode	https://opencode.ai
qwen	Qwen Code	https://qwenlm.github.io/qwen-code-docs