Custom Dockerfiles

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:

Include Node.js 20+
Copy the application code from the base image or install it
Set ENTRYPOINT ["node", "/app/dist/agents/container-entry.js"]
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

Dockerfiles reference — build behavior, image contents, filesystem layout, and configuration
Scaling Agents — run multiple instances of an agent

First Steps

Guides

Concepts

Integrations

Reference

Agent Dockerfiles

Common additions

Writing a standalone Dockerfile

Next steps

​Agent Dockerfiles

​Common additions

​Writing a standalone Dockerfile

​Next steps

Agent Dockerfiles

Common additions

Writing a standalone Dockerfile

Next steps