How It Works

How it works

aicage runs the agent inside a Docker container and mounts the parts of your host that the agent needs. This keeps the host boundary tight while preserving a normal developer workflow.

What gets mounted

Typical mounts:

• Your project directory.
• Agent config files or directories (for example ~/.claude, ~/.config/github-copilot, etc.).
• Optional mounts:
  • Git support mounts (git config, GnuPG and SSH keys for signing commits).
  • Extension-defined shares (host mounts).
  • Docker socket (only when you pass --docker).

The agent starts in your project directory. On Windows, the path is the WSL-style path (for example /mnt/c/...).

What the container provides

• A Linux base image with a full dev toolchain.
• The chosen agent installed on top of that base.
• A startup entrypoint that:
  • on normal Linux runs, creates a user matching your host UID/GID and switches into it
  • on root-compatible setups such as Windows compatibility or rootless Docker, stays on container root and uses /root

Config flow

• On first run, aicage asks for a base image and stores the choice per project.
• Your per-project config lives at ~/.aicage/projects/<sha256>.yaml.
• aicage --config shows the active project config and its location.

Once a project is configured for an agent, aicage will keep using that saved config. To reconfigure, run aicage --config remove and run aicage again. To reset only one agent entry, use aicage --config remove <agent>.