> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actionllama.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Dockerfiles

> Add tools and packages to your agent Docker images

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.

<Note>Custom Dockerfiles only apply to agents using the default container runtime. Agents configured with the [host-user runtime](/reference/agent-config#runtime) do not use Docker and will ignore any Dockerfile.</Note>

<Note>Project-level Dockerfiles are also supported but not recommended — they make agents harder to reuse across projects. See the [Dockerfiles reference](/reference/dockerfiles#project-dockerfile) for details.</Note>

## 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`:

```dockerfile theme={null}
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

```dockerfile theme={null}
# 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:

```dockerfile theme={null}
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](/reference/dockerfiles) — build behavior, image contents, filesystem layout, and configuration
* [Scaling Agents](/guides/scaling-agents) — run multiple instances of an agent