Skip to content

Docker Args

Jump to bottom
Stefan Kuhn edited this page Jul 15, 2026 · 9 revisions

Docker run pass-through args

aicage lets you pass extra docker run options straight to Docker. This is useful for things like extra env vars, port publishing, or attaching to a specific Docker network.

Syntax

Any arguments between aicage and the agent are treated as Docker args. You must separate them from the agent with --.

aicage [aicage options] <docker-args> -- <agent> [<agent-args>]

aicage does not validate these args; they are forwarded verbatim to docker run.

Proxy env vars

aicage automatically forwards these host proxy env vars to local image builds and runtime when they are set: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY.

Examples

Set an environment variable inside the container (replace <agent> with your agent):

aicage -e FOO=bar -- <agent>

Publish a port:

aicage -p 3000:3000 -- <agent>

Attach to a network:

aicage --network my-net -- <agent>

Use host network mode (when supported by your Docker environment, see also Host networking:

aicage --network host -- <agent>

Mount an extra directory (in addition to your project mount):

aicage --share ~/.cache <agent>

Prefer --share over raw Docker mount args (-v/--mount) for host path sharing. --share is more convenient and lets aicage apply its host/container path handling consistently.

Extensions can also define extra shares (host mounts).

Use raw Docker mount args only when you need mount options that --share does not support.

Raw Docker mount example:

aicage -v pgdata:/var/lib/postgresql/data -- <agent>

Persistence

When you pass docker args, aicage uses them for the current run.

  • In the default Textual UI, they appear in the Docker Args section and are saved if you accept the overview.
  • With --menu simple, aicage asks whether to persist them for this project and agent.
  • With --menu none, defaults are accepted automatically, so passed docker args are persisted.

To change or remove persisted args later, run aicage <agent> and edit Docker Args in the UI, or reset the saved config with aicage --config remove [<agent>].

Clone this wiki locally