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

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

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:
PackageWhy
node:20-alpineRuns the container entry point and pi-coding-agent SDK
gitClone repos, create branches, push commits
curlAPI calls (Sentry, arbitrary HTTP), anti-exfiltration shutdown
ca-certificatesHTTPS for git, curl, npm
openssh-clientSSH 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

PathModeContents
/appread-onlyAction Llama application + node_modules
/credentialsread-onlyMounted credential files (/<type>/<instance>/<field>)
/tmpread-write (tmpfs, 2GB)Agent working directory — repos, scratch files, SSH keys
/workspaceread-write (2GB)Persistent workspace
/home/noderead-write (64MB)Home directory

​
Configuration

KeyDefaultDescription
local.image"al-agent:latest"Base Docker image name
local.memory"4g"Memory limit per container
local.cpus2CPU limit per container
local.timeout900Max container runtime in seconds

​
Troubleshooting

“Docker is not running” — Start Docker Desktop or the Docker daemon before running al start. 
# 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: 
[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.