Container
A task can run inside a container. This improves cross-platform support for your build files and reduces the number of locally installed tools required to run your tasks.
Every task can run inside a container. All you need is to set an image property on your task.
tasks:
install:
image: node:24-alpine
cmds:
- npm installThis example runs npm install inside a container with the image node:24-alpine. However, the container has no access to your local files, so nothing gets installed. To give it access to your project files, use sources, generates and mounts.
Adding source files/folders
All source files and folders are mounted when the container starts and can be accessed inside it.
tasks:
install:
image: node:24-alpine
src:
- package.json
- package-lock.json
cmds:
- npm installAdding output files/folders
The installed node_modules are written to the container's file system. If those files and folders are needed after the task has finished, declare them under generates.
tasks:
install:
image: node:24-alpine
src:
- package.json
- package-lock.json
generates:
- node_modules
cmds:
- npm installAdding mounts
For other files and folders that are neither sources nor generates, use mounts. They can be relative, absolute or relative to your home directory.
tasks:
install:
image: node:24-alpine
src:
- package.json
- package-lock.json
generates:
- node_modules
mounts:
- relative/path
- /some/absolute/path
- .npm:/root/.npm
cmds:
- npm installA mount is written host[:container]:
path— a single path mounts the host path to the same path inside the container.host:container— mounts the host path on the left to the container path on the right.host:container:ro— the same, read-only for the container (:rwis the default). Any other third part is an error.
Host paths can be relative (resolved against the build file's directory), absolute,
or in your home directory with ~/ (~/.npm:/root/.npm). $HOME/ means the home
directory too, unless the task declares a HOME in its envs, which then takes its
place. A mount in the home directory names its container path (~/.npm alone is an
error). Relative container paths resolve against the task's working directory.
$PWD/ at the start of a host path is also your home directory, not the project,
for compatibility with older build files. validate warns about
it. Write ~/ for the home directory, or a relative path for the project.
On a server, a host path outside the published files is refused, and a home-directory path is named as such in the error.
A host path that does not exist yet is created before the container starts: an empty
file when its name has an extension (config.json), else a directory. When hammerkit
can't create a directory, for example because it runs in a container of its own whose
file system is not the Docker host's, Docker creates it on its host instead. A missing
file it can't create is an error, since Docker would put a directory there.
Working directory
A container task runs with its working directory set to the build file's directory
(mirrored inside the container), and your sources are mounted there. So relative
paths in cmds (node_modules/.bin/tsc, ./script.sh) behave just like they would
when running on the host.
The sources and generates of all dependencies are mounted into the container automatically. This avoids long lists of mounts and keeps tasks consistent.
Execution shell
By default, each command runs in a sh shell. Override it with a shell property on the task.
tasks:
shell_example:
image: ubuntu
shell: bash
cmds:
- echo $RANDOM
File permission
On Linux hosts a container task runs as your uid:gid, so files it generates on
mounted paths come back owned by you rather than by root. That user has no home
directory in the image, so hammerkit sets HOME=/tmp for the task (unless its
envs set HOME): tools like npm, Go, Maven and the .NET SDK keep their caches
under it. To avoid permission
conflicts on the mount points themselves, hammerkit chowns the working directory,
the sources, the generated directories and the volumes to your uid:gid before the
task runs. A mounts entry keeps its owner: it is a path of your machine, such as the
docker socket, whose owner is not hammerkit's to change. A mounted path the task writes
to has to be writable for you already.
The blast radius is small and deliberate: the chown is not recursive, so it
only re-owns those top-level directories — files already inside an image (for
example pre-baked, root-owned content) are left untouched. On macOS and Windows the
Docker Desktop VM handles the uid mapping, so this step is skipped entirely.
Capabilities
capAdd adds Linux capabilities to the task's container, on top of the runtime's default set.
A tool that mounts file systems, for example, needs SYS_ADMIN:
tasks:
mounts:
image: alpine:3.22
capAdd: [SYS_ADMIN]
cmds:
- mount -t tmpfs tmpfs /mnt && touch /mnt/fileTo build a Dockerfile, use build instead: hammerkit adds what
BuildKit needs, wherever the task runs.
A capability is named without the CAP_ prefix, as in capabilities(7): SYS_ADMIN,
NET_ADMIN. ALL is not one, a task lists what it needs. On Docker they are --cap-add, on
Kubernetes the container's securityContext.capabilities.add. A capability holds for root
only, so a task with capAdd runs its commands as the user of its image, not as your
uid:gid (see File permission above): files it writes into the project are that user's.
Capabilities are not part of the task's cache key.
On a host that uses AppArmor, such as Ubuntu, Docker's default profile still refuses mounts whatever the capabilities, so a build that mounts needs a sandboxed runtime there. A server adds a capability only where its operator allows it, and then only in such a sandbox: see Building container images.