---
title: "Containers · Agent Wranglers"
url: https://agentwranglers.se/playbook/operations/containers
updated: 2026-10-20
licence: "All rights reserved"
---

# Containers

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

> Build small, pinned images that hold only what runs. Run them without root, read-only, with a health check, and scan every image before it ships.

A container image is the unit you build, test and ship. The same image runs on a laptop, in CI and in production, so its flaws travel everywhere. These rules apply to Docker, Podman and any runtime that follows the OCI image standard.

Two related rules live elsewhere. [Run the tests inside the container build](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/container-build-gated-by-tests), and [make builds repeatable](https://agentwranglers.se/playbook/engineering/running-in-production/reproducible-builds).

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers operations playbook: https://agentwranglers.se/playbook/operations/containers`.

## Required

- [Pin each base image by digest](https://agentwranglers.se/playbook/operations/containers/pinned-base-images): Name every base image by version and digest, never by a moving tag such as `latest`. Choose the smallest image that runs the app.
- [Keep build tools out of the runtime image](https://agentwranglers.se/playbook/operations/containers/multi-stage-builds): Build in one stage and copy only the finished app into a clean final stage. Compilers, test tools and development packages never reach the image you ship.
- [Run containers as a user without root](https://agentwranglers.se/playbook/operations/containers/non-root-containers): Switch to a user without root with `USER` before the app starts. Give that user write access only to the folders the app writes.
- [Never give a container control of the host](https://agentwranglers.se/playbook/operations/containers/no-privileged-containers): Never run an app container with `--privileged`, the host's network or process namespace, or the container engine's socket mounted inside.
- [Send only the files the build needs](https://agentwranglers.se/playbook/operations/containers/dockerignore): Keep a `.dockerignore` that leaves out dependencies, build output, version control, local data and every secret file.
- [Pass build secrets as mounts instead of layers](https://agentwranglers.se/playbook/operations/containers/build-secrets): Give the build a token or key only through a secret mount. Never through `ARG`, `ENV`, or a copied file.
- [Let the main process receive stop signals](https://agentwranglers.se/playbook/operations/containers/container-signals): Start the app in exec form, so it receives the stop signal itself. Add a small init process that forwards signals and reaps child processes.
- [Scan every image before it ships](https://agentwranglers.se/playbook/operations/containers/image-scanning): Scan each built image for known holes in CI, and fail the build on high or critical ones that have a fix.

## Recommended

- [Make the container file system read-only](https://agentwranglers.se/playbook/operations/containers/read-only-containers): Run containers with a read-only root file system. Mount a volume for data and a `tmpfs` for scratch files.
- [Declare a health check in the image](https://agentwranglers.se/playbook/operations/containers/container-health): Give every service image a `HEALTHCHECK` that calls the app's own [health address](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/health-check-and-rollback).
- [Run one process per container](https://agentwranglers.se/playbook/operations/containers/one-process-per-container): Give each container one main process, and read every setting from the environment.
- [Run the same images locally with Compose](https://agentwranglers.se/playbook/operations/containers/compose-for-local): Describe the local setup in one Compose file that uses the production images and versions, so the app runs the same way on every laptop.

- Previous: [Disaster recovery](https://agentwranglers.se/playbook/operations/disaster-recovery)
- [All chapters](https://agentwranglers.se/playbook/operations)