Skip to content

Entrypoint Contract

Jump to bottom
Stefan Kuhn edited this page Jul 10, 2026 · 5 revisions

Entrypoint contract

aicage images start through entrypoint.sh.

Most users do not need to set its variables directly. aicage normally passes them for you. This page is mainly useful when you:

  • inspect aicage --dry-run
  • debug a container startup issue
  • run an image manually with docker run
  • work on aicage or the image repos

What the entrypoint expects

The entrypoint reacts to these environment variables:

Variable Meaning
AICAGE_UID Runtime user id inside the container.
AICAGE_GID Runtime group id inside the container.
AICAGE_HOST_USER Runtime user name inside the container.
AICAGE_HOME Active home directory inside the container.
AICAGE_MOUNT_HOME Host-home mount anchor when mounted paths do not live under the active HOME. Usually only needed for non-Linux host setups.
AICAGE_WORKSPACE Working directory the container starts in.
AICAGE_ENTRYPOINT_CMD Final command the entrypoint executes.
TZ Optional timezone to apply inside the container.

Normal behavior

For the common Linux case, aicage passes a host-like runtime identity:

  • AICAGE_UID and AICAGE_GID match the host user
  • AICAGE_HOST_USER matches the host user name
  • AICAGE_HOME matches the mounted home path in the container

The entrypoint then:

  • prepares that user if needed
  • sets HOME and USER
  • adjusts a few ownership details for workspace and mounted home paths
  • starts the agent command

Root behavior

If AICAGE_UID=0 and AICAGE_GID=0, the entrypoint stays on container root instead of switching to a generated user.

This is mainly relevant for special host/platform setups. In that case:

  • AICAGE_HOME is usually /root
  • AICAGE_MOUNT_HOME may point at a different mounted host-home path

What users usually need to know

  • aicage --entrypoint bash -- <agent> skips the entrypoint completely.
  • aicage -e AICAGE_ENTRYPOINT_CMD=bash -- <agent> still runs the entrypoint, but starts a shell instead of the agent.
  • If config files under your mounted home are not readable in the container, check the generated UID/GID, HOME, and mount paths first.

Manual docker run example

docker run --rm -it \
  -e AICAGE_UID="$(id -u)" \
  -e AICAGE_GID="$(id -g)" \
  -e AICAGE_HOST_USER="$USER" \
  -e AICAGE_HOME="$HOME" \
  -e AICAGE_WORKSPACE="$PWD" \
  --mount "type=bind,src=$PWD,dst=$PWD" \
  ghcr.io/aicage/aicage:codex-ubuntu

That is only a debugging example. For normal use, prefer running through aicage so the full mount and environment setup stays consistent.

Clone this wiki locally