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

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

  • Built-in agent examples:

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

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>

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>
    • 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:
  • 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:
  • Add custom tools/agents/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

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. Extensions can install tools and request additional host mounts.

After adding or changing custom definitions, restart aicage.

If your project is already configured for an agent, rerun aicage <agent> to review or change that saved config. Use aicage --config remove only to reset the whole project config, or aicage --config remove <agent> to reset a single agent entry. Use aicage --config to inspect the current config.

Image updates are handled automatically; see Updates.

aicage options

  • --dry-run prints the composed docker run command without executing it.
  • --menu textual|simple|none selects the Textual menu, the simple line-based menu, or no menu.
  • --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.
  • Extensions can also request grouped host mounts during setup.
  • --config 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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.4.19)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Wuodan from gravatar.com Wuodan

Credits

Author: Stefan Kuhn

License

Apache License

Requires

Python >=3.10

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aicage-1.4.1.tar.gz (79.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

aicage-1.4.1-py3-none-any.whl (161.8 kB view details)

Uploaded Python 3

File details

Details for the file aicage-1.4.1.tar.gz.

File metadata

  • Download URL: aicage-1.4.1.tar.gz
  • Upload date:
  • Size: 79.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for aicage-1.4.1.tar.gz
Algorithm Hash digest
SHA256 e483385d707df6e8a851582cc4d9eae28eb9014737078468bb0842adbca3f54f
MD5 836ab31424cb76ceb8d6d653cff53e1b
BLAKE2b-256 47adde9d1b65fba86fab2435eb1ceceb0c2da24969a49b5fa86307154c93d9aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for aicage-1.4.1.tar.gz:

Publisher: release.yml on aicage/aicage

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file aicage-1.4.1-py3-none-any.whl.

File metadata

  • Download URL: aicage-1.4.1-py3-none-any.whl
  • Upload date:
  • Size: 161.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for aicage-1.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 599d0b43cdfed99a72c40bb9f539359acffffff20f97485f64fbcc943e8cc10e
MD5 18d7d26f992efff79ec688ea828ac108
BLAKE2b-256 22028f70ad5d0b824338f99b9fb4ef7bc9028eabce00da85d5f535837ef5714c

See more details on using hashes here.

Provenance

The following attestation bundles were made for aicage-1.4.1-py3-none-any.whl:

Publisher: release.yml on aicage/aicage

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.4.19

2 files

1.4.18

2 files

1.4.17

2 files

1.4.16

2 files

1.4.15

2 files

1.4.14

2 files

1.4.13

2 files

1.4.12

2 files

1.4.11

2 files

1.4.10

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

This release

1.4.1 This release

2 files

1.4.0

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.2.5

2 files

1.1.10

2 files

1.1.8

2 files

1.1.1

2 files

1.1.0

2 files

1.0.11

2 files

1.0.10

2 files

1.0.9

2 files

1.0.3

2 files

1.0.1

2 files

1.0.0

2 files

0.9.48

2 files

0.9.42

2 files

0.9.41

2 files

0.9.40

2 files

0.9.29

2 files

0.9.28

2 files

0.9.27

2 files

0.9.26

2 files

0.9.25

2 files

0.9.24

2 files

0.9.22

2 files

0.9.21

2 files

0.9.20

2 files

0.9.19

2 files

0.9.18

2 files

0.9.16

2 files

0.9.15

2 files

0.9.14

2 files

0.9.11

2 files

0.9.10

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.27

2 files

0.8.22

2 files

0.8.21

2 files

0.8.20

2 files

0.8.18

2 files

0.8.17

2 files

0.8.16

2 files

0.8.12

2 files

0.8.8

2 files

0.8.7

2 files

0.8.1

2 files

0.8.0

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.5.14

2 files

0.5.13

2 files

0.5.12

2 files

0.5.11

2 files

0.5.10

2 files

0.5.9

2 files

0.5.8

2 files

0.5.7

2 files

0.5.0

2 files

0.4.10

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.3

2 files

0.4.2

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.9

2 files

0.0.3

2 files

0.0.2

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page