container

The container step type builds, pushes, runs, and inspects containers through Docker or Podman, bringing the full container lifecycle into your custom commands and workflows without leaving Atmos.

Set action to choose the operation, then provide the matching nested config block (build, push, run, or inspect). When action is omitted, Atmos defaults to run.

steps:
  - name: build
    type: container
    action: build
    build:
      context: .
      dockerfile: Dockerfile
      tags:
        - app:local

  - name: smoke
    type: container
    action: run
    run:
      image: app:local
      command: uname -a

This step type is different from the step-level container field, which runs ordinary type: shell steps inside a shared sandbox.

Fields

action: Operation to perform: build, push, run, or inspect. Defaults to run when omitted.
build: Configuration for action: build. See Build.
push: Configuration for action: push. See Push.
run: Configuration for action: run. See Run.
inspect: Configuration for action: inspect. See Inspect.

Every action block also accepts provider (docker or podman, auto-detected when omitted) and runtime_auto_start (start the Podman machine when no runtime is running).

Build

action: build builds a container image from a Dockerfile, or from a Docker Bake definition.

steps:
  - name: build
    type: container
    action: build
    build:
      provider: docker          # docker | podman (auto-detected when omitted)
      runtime_auto_start: true  # start the Podman machine if no runtime is running
      engine: buildx            # buildx (Docker BuildKit) or omit for the default builder
      context: .                # build context directory
      dockerfile: Dockerfile    # path to the Dockerfile
      tags:
        - app:local
        - app:1.0.0
      build_args:               # values passed as --build-arg
        VERSION: 1.0.0
      target: runtime           # target stage in a multi-stage build
      no_cache: false           # disable the build cache
      pull: true                # always pull newer base images

context: Build context directory. Required unless you use bake.
dockerfile: Path to the Dockerfile. Required unless you use bake.
tags: List of image tags to apply.
build_args: Map of build arguments passed as --build-arg.
target: Target stage in a multi-stage Dockerfile.
no_cache: Disable the build cache when set to true.
pull: Always attempt to pull newer base images when set to true.
engine: Build engine: buildx for Docker BuildKit, or omit for the default builder. Requires provider: docker.
bake: Build with Docker Bake instead of a single Dockerfile. See Bake. Requires provider: docker.

Bake

Set build.bake to build one or more targets from a docker-bake.hcl (or .json) definition:

build:
  provider: docker
  bake:
    file: docker-bake.hcl       # primary bake file
    files:                      # additional bake files
      - docker-bake.override.hcl
    targets:                    # targets to build (use `target` for a single one)
      - api
      - worker
    set:                        # overrides in target.key=value form
      - api.platform=linux/amd64
    vars:                       # bake variables
      VERSION: 1.0.0
    load: true                  # load the result into the local image store
    push: false                 # push the result to the registry
    print: false                # print the resolved definition and exit

file / files: Primary bake file, and any additional bake files.
target / targets: A single target, or a list of targets to build.
set: List of overrides in target.key=value form.
vars: Map of bake variables.
load: Load the built image into the local image store.
push: Push the built image to the registry.
print: Print the resolved bake definition and exit without building.

Push

action: push pushes an image and its tags to a registry.

steps:
  - name: publish
    type: container
    action: push
    push:
      provider: docker
      image: app:local          # source image to push
      tags:                     # target tags (omit to push all existing tags)
        - registry.example.com/app:1.0.0
        - registry.example.com/app:latest

image: Source image to push.
tags: Target tags to push. When omitted, Atmos pushes all existing tags for the image.

Run

action: run runs a one-shot container, and is the default when action is omitted.

steps:
  - name: smoke
    type: container
    action: run
    env:                        # environment variables come from the step-level env
      LOG_LEVEL: debug
    run:
      image: app:local          # required
      command: ./run-tests.sh   # required
      shell: /bin/sh            # shell used to run the command (default /bin/sh)
      provider: docker
      pull: missing             # missing (default) | always | never
      workspace: /workspace     # where the working directory is mounted (default /workspace)
      workspace_read_only: false
      cleanup: always           # always (default) | on_success | never
      user: "1000:1000"         # username or UID:GID
      run_args:
        - --network=host
      mounts:
        - type: bind
          source: ~/.aws
          target: /root/.aws
          read_only: true
      ports:
        - host: 8080
          container: 80
          protocol: tcp

image: Required. Container image to run.
command: Required. Command to run inside the container.
shell: Shell used to execute the command. Defaults to /bin/sh.
pull: Image pull policy: missing (default), always, or never.
workspace: Container path where the working directory is mounted. Defaults to /workspace.
workspace_read_only: Mounts the workspace read-only when set to true.
cleanup: Cleanup policy: always (default), on_success, or never.
user: User context for execution. Accepts a username or UID:GID.
run_args: List of additional arguments passed to the runtime's run command.
mounts: List of additional volume mounts. See Mounts.
ports: List of published port mappings. See Ports.

Environment variables for the container come from the step-level env field, not from a field under run.

Mounts

run.mounts is a list of mount objects:

run:
  image: app:local
  command: ls /cache
  mounts:
    - type: bind              # bind (default) | volume | tmpfs
      source: ~/.aws          # host path (bind) or volume name (volume); `~` expands to home
      target: /root/.aws
      read_only: true
    - type: volume
      source: build-cache
      target: /cache
    - type: tmpfs
      target: /tmp/scratch

type: Mount type: bind (default), volume, or tmpfs.
source: Host path for bind mounts or the volume name for volume mounts. Not used for tmpfs. ~ expands to the host home directory.
target: Required. Path inside the container.
read_only: Mounts the source read-only when set to true. Defaults to false.

Ports

run.ports is a list of port mappings:

run:
  image: nginx:latest
  command: nginx -g 'daemon off;'
  ports:
    - host: 8080              # host port
      container: 80           # container port
      protocol: tcp           # tcp (default) | udp

host: Host port number to publish.
container: Container port number to map to the host port.
protocol: Port protocol: tcp (default) or udp.

Inspect

action: inspect displays curated metadata for an image.

steps:
  - name: inspect
    type: container
    action: inspect
    inspect:
      provider: docker
      image: app:local          # image to inspect

image: Required. Image to inspect.

Fields​

Build​

Bake​

Push​

Run​

Mounts​

Ports​

Inspect​