Skip to main content
Agents run in Docker containers built from a layered image system. See Custom Dockerfiles for a guide on writing and customizing Dockerfiles.
Agents can also run without Docker using the host-user runtime. Dockerfiles and container configuration do not apply to host-user agents.

​
Agent Dockerfile

Agents that need extra tools can add a Dockerfile to their directory:
Agents without a Dockerfile use al-agent:latest directly.

​
Project Dockerfile

Project Dockerfiles make agents harder to reuse. When an agent depends on tools installed in the project base image, it won’t work when shared to another project. Prefer agent-level Dockerfiles so each agent is self-contained and portable.
Projects can optionally have a Dockerfile at the root that defines a shared base image for all agents. When present and customized beyond a bare FROM al-agent:latest, the build pipeline creates an intermediate image (al-project-base:latest) that all agent images layer on top of. If unmodified or absent, agents build directly on al-agent:latest.

​
Image Build Order

If the project Dockerfile is unmodified, the middle layer is skipped.

​
Base Image Contents

The base image (al-agent:latest) is built automatically from the Action Llama package and includes: The base image also copies the compiled Action Llama application (dist/) and installs its npm dependencies. The entry point is node /app/dist/agents/container-entry.js.

​
Build Behavior

  • The base image (al-agent:latest) is only built if it doesn’t exist yet
  • The project base image (al-project-base:latest) is rebuilt on every al start if the project Dockerfile has customizations
  • Agent images are named al-<agent-name>:latest (e.g. al-dev:latest) and are rebuilt on every al start to pick up Dockerfile changes
  • The build context is the Action Llama package root (not the project directory), so COPY paths reference the package’s dist/, package.json, etc.
  • The FROM line in agent Dockerfiles is automatically rewritten to point at the correct base image

​
Container Filesystem Layout

​
Configuration

​
Troubleshooting

“Docker is not running” — Start Docker Desktop or the Docker daemon before running al start.
Base image build fails — Run docker build -t al-agent:latest -f docker/Dockerfile . from the Action Llama package directory to see the full build output. Project base image build fails — Check that the project Dockerfile starts with FROM al-agent:latest and that any apk add packages are spelled correctly. The base image uses Alpine Linux. Agent image build fails — Check that your agent’s Dockerfile starts with FROM al-agent:latest (the build pipeline rewrites this to the correct base) and that any package install commands are correct. Image build fails — Check that your Dockerfile uses apk add (Alpine) or apt-get (Debian) depending on the base. The default base is Alpine. Container out of memory — Increase the memory limit in config.toml:
Container exits immediately — Check al logs <agent> for the error. Common causes: missing credentials, missing SKILL.md, invalid model config.