> ## 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.

# Dockerfiles

> Docker image structure, build behavior, and container configuration

Agents run in Docker containers built from a layered image system. See [Custom Dockerfiles](/guides/custom-dockerfiles) for a guide on writing and customizing Dockerfiles.

<Note>Agents can also run without Docker using the [host-user runtime](/reference/agent-config#runtime). Dockerfiles and container configuration do not apply to host-user agents.</Note>

## Agent Dockerfile

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

Agents without a Dockerfile use `al-agent:latest` directly.

## Project Dockerfile

<Warning>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.</Warning>

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

```
al-agent:latest            <-- Action Llama package (automatic)
    |
    v
al-project-base:latest     <-- project Dockerfile (if customized)
    |
    v
al-<agent>:latest          <-- per-agent Dockerfile (if present)
```

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:

| Package           | Why                                                                     |
| ----------------- | ----------------------------------------------------------------------- |
| `node:20-alpine`  | Runs the container entry point and bundled harness/runtime dependencies |
| `git`             | Clone repos, create branches, push commits                              |
| `curl`            | API calls (Sentry, arbitrary HTTP), anti-exfiltration shutdown          |
| `ca-certificates` | HTTPS for git, curl, npm                                                |
| `openssh-client`  | SSH for `GIT_SSH_COMMAND` — git clone/push over SSH                     |

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

| Path           | Mode                    | Contents                                                 |
| -------------- | ----------------------- | -------------------------------------------------------- |
| `/app`         | read-only               | Action Llama application + node\_modules                 |
| `/credentials` | read-only               | Mounted credential files (`/<type>/<instance>/<field>`)  |
| `/tmp`         | read-write (tmpfs, 2GB) | Agent working directory — repos, scratch files, SSH keys |
| `/home/node`   | read-write (64MB)       | Home directory                                           |

## Configuration

| Key             | Default             | Description                      |
| --------------- | ------------------- | -------------------------------- |
| `local.image`   | `"al-agent:latest"` | Base Docker image name           |
| `local.memory`  | `"4g"`              | Memory limit per container       |
| `local.cpus`    | `2`                 | CPU limit per container          |
| `local.timeout` | `900`               | Max container runtime in seconds |

## Troubleshooting

**"Docker is not running"** — Start Docker Desktop or the Docker daemon before running `al start`.

```bash theme={null}
# macOS — open Docker Desktop
open -a Docker

# Linux
sudo systemctl start docker
```

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

```toml theme={null}
[local]
memory = "8g"    # default: "4g"
```

**Container exits immediately** — Check `al logs <agent>` for the error. Common causes: missing credentials, missing `SKILL.md`, invalid model config.