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 <agent>

This opens the default Textual configuration UI where you can review and adjust the setup before starting.

Built-in agent examples:

aicage agy
aicage claude
aicage codex
aicage copilot
aicage crush
aicage droid
aicage gemini
aicage goose
aicage opencode
aicage 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.

If you want the fastest no-menu first run, use:

aicage --menu none <agent>

--menu none accepts suggested defaults and skips interactive menus.

Menu modes

• aicage <agent> uses the default Textual configuration UI.
• aicage --menu simple <agent> uses the classic line-based prompt menu.
• aicage --menu none <agent> skips menus and uses defaults.

Run aicage <agent> again whenever you want to review or change the saved config for that agent in the current project.

Use --config remove only when you want to reset the saved config completely.

1. Show project config path and contents:

   aicage --config info

2. Remove config if needed:

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

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
agy	Antigravity CLI	https://antigravity.google/docs/cli-overview
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