Skip to content

How It Works

Jump to bottom
Stefan Kuhn edited this page Jan 27, 2026 · 7 revisions

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 (same path inside the container).
  • 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).
    • 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 creates a user matching your host UID/GID and switches into it.

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 print 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, delete the project config file and run aicage again.

Clone this wiki locally