aicage
Give coding agents your project files, not your whole computer.
aicage runs AI coding agents in containers while you work on the same local project files.
Why use aicage?
Agents need deep access (read code, run commands, install dependencies). Their built-in safety checks are naturally limited.
Running agents in containers gives a hard boundary – with aicage the experience stays the same.
- Work with the same project files as the agent
- Configure shared folders, agent images, and runtime options
- Same paths and user inside the container1
- Pre-built and tested images
- Automatic updates for agents and images
See Why cage agents? for the full rationale.
Built-in agents
Use one of these builtin CLI agents or add your own.
 Amp CLI · amp |
Auggie CLI · auggie |
 Claude Code · claude |
 Codex CLI · codex |
GitHub Copilot CLI · copilot |
Factory CLI · droid |
 Goose CLI · goose |
Kiro CLI · kiro-cli |
 OpenCode · opencode |
 Qwen Code · qwen |
 Mistral Vibe CLI · vibe |
Quick start
Install:
pipx install aicage
First run
In your project directory, start the agent you want to use:
aicage <agent>
Accept the setup choices, then sign in or confirm that the agent is already signed in.
- Prefer file-based credential storage or API keys; keyring-based auth does not work.
- If sign-in fails, sign in with the agent on the host, then try again.
Use aicage in your IDE
Use your agent in your IDE while aicage runs it in a Docker container.
Visual Studio Code
- Install ACP Client.
- In the plugin settings, add your agent’s config from the
Visual Studio Code configuration into the
settings.json.
JetBrains
- Install AI Assistant.
- In the plugin’s settings, add your agent’s config from the
JetBrains configuration as a
custom ACP agent.
Replace/path/to/aicagewith the full path toaicage.
ACP Bridge for Amp, Claude, and Codex
These agents need one additional ACP bridge. Install the bridge for the agent you use:
# Run only the command for your agent.
npm install -g amp-acp
npm install -g @agentclientprotocol/claude-agent-acp
npm install -g @agentclientprotocol/codex-acp
In JetBrains, replace the bridge's /path/to/... in the config above with its full path.
Change a project's setup
Run aicage <agent> from the project directory to change the agent's container setup. Your IDE uses the saved
project configuration.
Configuration menu
After aicage <agent> starts, you will see this setup overview:
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: extradocker runarguments such as-e,-p, or--network.Docker socket: lets the agent use Docker on the host when you explicitly enable it.OK: saves the current project config for that agent and starts the container.
Common project changes
Bind mounts
Use Bind Mounts when the agent needs access to files or directories outside the project.
Docker args
To adjust how the container starts, open Docker Args in the setup screen.
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:
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.
Full documentation
The complete user documentation lives in the aicage.wiki.
Common scenarios
- First-use setup issues:
- See Known hiccups.
- On Windows:
- Set
git config --global core.autocrlf trueon the Windows host to avoid line-ending diffs.
- Set
- Pass arguments to the agent:
aicage <agent> resume <session-id>
- Share additional host folders:
- Use
Sharesor extension-provided shares in the setup UI.
- Use
- Use proxies:
aicageforwardsHTTP_PROXY,HTTPS_PROXY,ALL_PROXY, andNO_PROXY.- See CLI options.
- Use host networking or custom networks:
- See Host networking.
- On macOS with native Docker:
- See Known hiccups for the current support caveat.
- Add custom tools, agents, or base images:
Customization
aicage lets you customize images at three levels:
extensions: Add software and shared files/foldersagents: Add other agentsbase images: Custom agent environments
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.
- Extensions: Customization-Extensions
- Custom agents: Customization-Agents
- Custom base images: Customization-Base-Images
Image updates are handled automatically; see Updates.
Why cage agents?
You should not have to choose between approving every small step and giving an agent access to your whole computer.
Agent restrictions and approval prompts get in the way of real work. But turning them off gives the agent access to everything your user account can read or change, far beyond the project.
aicage gives the agent a container with your project files and only the extra access you choose. The rest of your
computer stays out of reach.
-
On Windows, run
aicagefrom WSL for matching paths and user. Native Windows paths are mounted under/mnt/<drive>and the container runs asroot. ↩
1 maintainer
Metadata
1 maintainer
Release files for aicage 1.5.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| aicage-1.5.2.tar.gz | 86.2 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aicage-1.5.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 268.8 kB
Release files / aicage-1.5.2.tar.gz
| Download URL | aicage-1.5.2.tar.gz |
|---|---|
| Size | 86.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ff872de7683fca6dad24a374bc396fa09b7a64a064405d64c2f770bc23d8b58
|
|
BLAKE2b-256 checksum How to use checksums |
642549df76cd777bd99da3a8133ad191d835b0b329a107921752138382d86923
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logRelease files / aicage-1.5.2-py3-none-any.whl
| Download URL | aicage-1.5.2-py3-none-any.whl |
|---|---|
| Size | 182.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a9c325dd87e3e1aca9da43c66f5aec2d6de4f352a5a6ae20863881c0f2dee8d
|
|
BLAKE2b-256 checksum How to use checksums |
aab44b48436959db4d4cc2e97b79613eadbb3249860953b732384323c027e987
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logSecurity for aicage 1.5.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for aicage-1.5.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
