Skip to main content
Action Llama agents run in Docker containers built from a minimal Alpine-based image with Node.js, git, and curl. Agents that need extra tools can add a Dockerfile to their directory.
Custom Dockerfiles only apply to agents using the default container runtime. Agents configured with the host-user runtime do not use Docker and will ignore any Dockerfile.
Project-level Dockerfiles are also supported but not recommended — they make agents harder to reuse across projects. See the Dockerfiles reference for details.

​
Agent Dockerfiles

Agents that need extra tools can add a Dockerfile to their directory: 
my-project/
  agents/
    dev/
      SKILL.md
      Dockerfile            <-- custom image for this agent
    reviewer/
      SKILL.md
                            <-- no Dockerfile, uses base image
Use FROM al-agent:latest and add what you need. The build pipeline automatically rewrites the FROM line at build time. Switch to root to install packages, then back to node: 
FROM al-agent:latest

USER root
RUN apk add --no-cache github-cli
USER node
This is a thin layer on top of the base — fast to build and shares most of the image.

​
Common additions

# GitHub CLI (for gh issue list, gh pr create, etc.)
RUN apk add --no-cache github-cli

# Python (for agents that run Python scripts)
RUN apk add --no-cache python3 py3-pip

# jq (for JSON processing in bash) — already in the base image
# RUN apk add --no-cache jq

​
Writing a standalone Dockerfile

If you need full control, you can write a Dockerfile from scratch. It must:
  1. Include Node.js 20+
  2. Copy the application code from the base image or install it
  3. Set ENTRYPOINT ["node", "/app/dist/agents/container-entry.js"]
  4. Use uid 1000 (USER node on node images) for compatibility with the container launcher
Example standalone Dockerfile: 
FROM node:20-alpine

# Install your tools
RUN apk add --no-cache git curl ca-certificates openssh-client github-cli jq python3

# Copy app from the base image (avoids rebuilding from source)
COPY --from=al-agent:latest /app /app
WORKDIR /app

USER node
ENTRYPOINT ["node", "/app/dist/agents/container-entry.js"]
The key requirement is that /app/dist/agents/container-entry.js exists and can run. The entry point reads AGENT_CONFIG, PROMPT, GATEWAY_URL, and SHUTDOWN_SECRET from environment variables, and credentials from /credentials/.

​
Next steps