hammerkit

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.

.hammerkit.yaml
tasks:
  install:
    image: node:24-alpine
    cmds:
      - npm install

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

.hammerkit.yaml
tasks:
  install:
    image: node:24-alpine
    src:
      - package.json
      - package-lock.json
    cmds:
      - npm install

Adding 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 install

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

.hammerkit.yaml
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 install

A 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 (:rw is 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.

.hammerkit.yaml
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:

.hammerkit.yaml
tasks:
  mounts:
    image: alpine:3.22
    capAdd: [SYS_ADMIN]
    cmds:
      - mount -t tmpfs tmpfs /mnt && touch /mnt/file

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

On this page