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.

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

Your existing CLI config for each agent is mounted inside the container so you can keep using your preferences and credentials.

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 you want to adjust how the container starts, 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 for agents which write to clipboard.

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:
    • Use Shares or extension-provided shares in the setup UI.
  • Use proxies:
    • aicage forwards HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY.
    • See CLI options.
  • Use host networking or custom networks:
  • 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/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

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.

Image updates are handled automatically; see Updates.

aicage options

  • --dry-run prints the composed docker run command without executing it.
  • --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.

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 practical boundary: the agent can access only what you explicitly mount or share. Day-to-day use stays familiar while files you do not mount stay 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.10.tar.gz (84.5 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.10-py3-none-any.whl (173.0 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: aicage-1.4.10.tar.gz
  • Upload date:
  • Size: 84.5 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.10.tar.gz
Algorithm Hash digest
SHA256 b1574df46f56ff6f906b80d494182193ad4156719b2dfdfb8a9b1d5d770957d8
MD5 83762f404d507e8feeac87c9272a4f7e
BLAKE2b-256 5e10435c6b6d05c76da75dd6511a864e697c1cfb5176a7c0296d7f2a52d76b6f

See more details on using hashes here.

Provenance

The following attestation bundles were made for aicage-1.4.10.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.10-py3-none-any.whl.

File metadata

  • Download URL: aicage-1.4.10-py3-none-any.whl
  • Upload date:
  • Size: 173.0 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.10-py3-none-any.whl
Algorithm Hash digest
SHA256 739a0f2bbc0b7119284774f81eb32ea57a4c6cfdb28b31df90d69c21601fa1aa
MD5 15dc5fb7a66323c85c36539bef0d58e0
BLAKE2b-256 458b20b7173b165a6e0dcc9ff3c4dcf4a8004ee3475a160fd1512d8eeb298249

See more details on using hashes here.

Provenance

The following attestation bundles were made for aicage-1.4.10-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

This release

1.4.10 This release

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

1.4.1

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