Skip to content

Home

Jump to bottom
Stefan Kuhn edited this page Jul 27, 2026 · 24 revisions

aicage wiki

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

Quick start

Install:

pipx install aicage

In your project directory, run:

aicage <agent>

For a first useful run, you can usually just press Enter or select OK when prompted.

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.

What you see first

After aicage <agent> starts, you will see this setup overview:

Overview screen

The overview brings the most common choices together in one place:

  • Agent: the built-in or custom agent you want to run.
  • Bind Mounts: extra host files and directories the container should be able to access.
  • Base: the base image used for the agent image. The suggested default is best for most users.
  • Extensions: optional local additions that install tools or request extra host shares.
  • Docker Args: extra docker run arguments such as -e, -p, or --network.
  • Docker socket: lets the agent use Docker on the host when you explicitly enable it.
  • Clipboard sharing: lets agents write to clipboard.
  • OK: saves the current project config for that agent and starts the container.

Common next steps

Bind mounts

Use Bind Mounts when the agent needs access to files or directories outside the project.

Docker args

If something about the container startup needs adjusting, open Docker Args in the setup screen.

Docker args

Use it for normal docker run arguments such as:

-e FOO=bar
-p 3000:3000
--network my-net

See Docker run pass-through args.

Extensions

Extensions let you add tools on top of an existing agent image. Quick start:

Extensions

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

Then rerun aicage <agent> and select the extension in the setup screen. See Extensions.

Docker socket access

If you want the agent to run Docker commands, enable Docker socket in the setup screen.

Clipboard sharing

Use Clipboard sharing in the setup screen when agents should be able to copy text out.

Common scenarios

  • The agent itself needs arguments:
    • Run aicage <agent> ... with the agent arguments after the agent name, for example aicage codex resume <session-id>.
  • Software or tools are missing inside the container:
    • Add an extension to install tools on top of the agent image.
  • The container needs extra environment variables, ports, or network settings:
    • Set them in Docker Args in the setup screen.
  • The agent should be able to run Docker commands:
    • Enable Docker socket in the setup screen.
  • The container needs access to more host files:
    • Add shares in the setup screen, or use extension-provided shares.
  • Networking or proxy behavior needs special handling:
  • On Windows:
    • Set git config --global core.autocrlf true on the Windows host to avoid line-ending diffs.
  • On macOS with native Docker:
  • Run into first-use setup issues:
  • Add custom tools, agents, or 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

More reading

Clone this wiki locally