Validate an Environment Image

Use this workflow before applying an agent whose inline environment changes its base image, build steps, or setup commands. It gives a repository agent a plain-Docker preflight for the current debian-contract-v0 hosted runtime contract; it does not apply a resource or create a hosted sandbox.

Choose the authored image

An inline environment accepts either an auto-managed preset or one direct Docker/OCI base-image reference:

image:
  kind: preset
  name: node24

image:
  kind: base
  ref: debian:bookworm

The direct form accepts one image-reference token. Whitespace, comments, continuations, and option-looking values are rejected. auto inserts the reference into a generated, single-stage FROM instruction; it does not import a repository Dockerfile or upload a Docker build context as environment configuration. Mutable tags can drift: a later build of debian:bookworm can resolve to different bytes even when the .auto file did not change. auto currently preserves the authored reference rather than resolving and persisting its digest. Pin ref to a registry digest when reproducible rebuilds matter.

Debian contract v0

A direct base image must satisfy every hard requirement below.

Requirement	Local proof
Operating system and architecture	Linux on `amd64` (`uname -s` is `Linux`; `uname -m` is `x86_64`)
C library	The x86-64 glibc loader exists and GNU libc is 2.28 or newer
Shell	`/bin/sh` exists and can execute Docker `RUN` instructions
Build user	Image build instructions can run as root; auto emits `USER root` before its probe and bootstrap
Git	`git` is already present or can be installed through the Debian/Ubuntu package surface used by the current bootstrap

The hosted build then runs in this order: base image, USER root, compatibility probe, auto’s harness bootstrap, your environment.steps, workspace-user creation, git mount, and your environment.setup commands as the non-root workspace user. A base without /bin/sh can fail before the probe can print a classified line. The current bootstrap also uses apt-get to install its base tools, including git, so a nominally glibc-compatible non-Debian image is not enough.

Run the local preflight

Copy the authored sequence

Read the agent and any imported environment fragments first. Record the resolved image.ref, copy each environment.steps entry in order, copy each environment.setup[].commands entry in order, and identify the repository’s existing smoke commands. Do not write a compiler or translator for .auto; this is a reviewed transcription of the environment you are about to apply.

Create a disposable source export

Run from the repository root after committing the environment change you intend to apply. The quoted heredoc reads the image ref as data, so shell metacharacters in a reviewed file are never evaluated by the host shell. Replace only its one data line.

validation_root="$(mktemp -d "${TMPDIR:-/tmp}/auto-environment-validation.XXXXXX")"
validation_context="$validation_root/context"
validation_dockerfile="$validation_root/Dockerfile"
validation_tag="auto-environment-validation:local"
mkdir -p "$validation_context"
git archive --format=tar HEAD | tar -xf - -C "$validation_context"

IFS= read -r image_ref <<'AUTO_IMAGE_REF'
debian:bookworm
AUTO_IMAGE_REF

The Docker context now contains only files committed at HEAD: no .git directory, ignored file, untracked .env, or untracked .npmrc can enter the image or Docker build cache. If the relevant changes are not committed, stop and commit them before continuing; the export deliberately ignores the live working tree.

Create a temporary validation Dockerfile

Create the file at $validation_dockerfile, using the template below. Keep the compatibility-probe line byte-for-byte intact. Replace only the marked authored step and setup examples with the commands from the repository.

Dockerfile

ARG AUTO_ENVIRONMENT_BASE=debian:bookworm
FROM ${AUTO_ENVIRONMENT_BASE}
USER root

# environment-image-contract-probe:start
RUN set -eu; auto_contract_fail() { echo "$1" >&2; exit 1; }; [ "$(id -u 2>/dev/null || true)" = "0" ] || auto_contract_fail 'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=root reason=requires-root-user'; [ "$(uname -s 2>/dev/null || true)" = "Linux" ] || auto_contract_fail 'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=os reason=requires-linux'; [ "$(uname -m 2>/dev/null || true)" = "x86_64" ] || auto_contract_fail 'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=arch reason=requires-linux-x86_64'; auto_glibc_loader=; for auto_glibc_candidate in /lib64/ld-linux-x86-64.so.2 /lib/x86_64-linux-gnu/ld-linux-x86-64.so.2; do if [ -e "$auto_glibc_candidate" ]; then auto_glibc_loader=$auto_glibc_candidate; break; fi; done; [ -n "$auto_glibc_loader" ] || auto_contract_fail 'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=glibc-loader reason=requires-glibc-loader'; auto_glibc_version=$(getconf GNU_LIBC_VERSION 2>/dev/null || true); case "$auto_glibc_version" in "glibc "[0-9]*.[0-9]*) ;; *) auto_contract_fail 'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=glibc reason=requires-gnu-libc-2.28-or-newer' ;; esac; auto_glibc_version=${auto_glibc_version#glibc }; auto_glibc_major=${auto_glibc_version%%.*}; auto_glibc_minor=${auto_glibc_version#*.}; auto_glibc_minor=${auto_glibc_minor%%.*}; case "$auto_glibc_major:$auto_glibc_minor" in *[!0-9:]*|:*) auto_contract_fail 'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=glibc reason=requires-gnu-libc-2.28-or-newer' ;; esac; [ "$auto_glibc_major" -gt 2 ] || { [ "$auto_glibc_major" -eq 2 ] && [ "$auto_glibc_minor" -ge 28 ]; } || auto_contract_fail 'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=glibc reason=requires-gnu-libc-2.28-or-newer'; mkdir -p /opt/auto; : > /opt/auto/probe.env; if command -v git >/dev/null 2>&1; then auto_probe_available=1; else auto_probe_available=0; fi; echo "AUTO_PROBE_HAS_GIT=$auto_probe_available" >> /opt/auto/probe.env; if command -v bash >/dev/null 2>&1; then auto_probe_available=1; else auto_probe_available=0; fi; echo "AUTO_PROBE_HAS_BASH=$auto_probe_available" >> /opt/auto/probe.env; if command -v useradd >/dev/null 2>&1; then auto_probe_available=1; else auto_probe_available=0; fi; echo "AUTO_PROBE_HAS_USERADD=$auto_probe_available" >> /opt/auto/probe.env; if command -v apt-get >/dev/null 2>&1; then auto_probe_available=1; else auto_probe_available=0; fi; echo "AUTO_PROBE_HAS_APT_GET=$auto_probe_available" >> /opt/auto/probe.env;
# environment-image-contract-probe:end

# Equivalent compatibility bootstrap: proves the current Debian package path
# can provide git and the workspace-user tooling.
RUN apt-get update \
  && apt-get install -y --no-install-recommends git passwd \
  && rm -rf /var/lib/apt/lists/*
RUN test -x /bin/sh && command -v git >/dev/null

# Paste environment.steps here, unchanged and in order.
RUN apt-get update \
  && apt-get install -y --no-install-recommends make \
  && rm -rf /var/lib/apt/lists/*

# Local equivalent of auto's post-build workspace-user and mounted checkout.
RUN set -eu \
  && if ! getent group user >/dev/null 2>&1; then groupadd user; fi \
  && if ! id -u user >/dev/null 2>&1; then useradd -m -s /bin/bash -g user user; fi \
  && mkdir -p /workspace/repository \
  && chown -R user:user /workspace/repository /home/user
COPY --chown=user:user . /workspace/repository
USER user
WORKDIR /workspace/repository

# Paste environment.setup[].commands here, unchanged and in order.
RUN /bin/sh -lc 'set -eu; make environment-setup'

The local COPY and final RUN model the hosted mount-then-setup order. They do not reproduce the auto harness packages or E2B’s setup snapshot cache, so this remains a compatibility and repository-command preflight rather than proof of a hosted template build.

Build and run the known-good case

Ask Docker to parse and pull the ref first, then build and run both legs explicitly as linux/amd64. Docker’s own reference parser rejects values outside canonical Docker/OCI reference grammar; a parse or pull failure stops the preflight. Keep the variable expansions quoted exactly as shown and replace the smoke command with the repository’s real checks.

docker image pull --platform linux/amd64 -- "$image_ref"

docker build \
  --platform linux/amd64 \
  --build-arg "AUTO_ENVIRONMENT_BASE=$image_ref" \
  --file "$validation_dockerfile" \
  --tag "$validation_tag" \
  "$validation_context"

docker run \
  --rm \
  --platform linux/amd64 \
  "$validation_tag" \
  /bin/sh -lc 'set -eu; test "$(uname -m)" = x86_64; test "$(id -u)" != 0; git --version; make test'

A pass proves the selected base can execute the compatibility path, the authored build and setup commands succeed in the right order and user context, and the repository’s chosen smoke checks pass inside the resulting image.

Prove the incompatible classification

Run the same Dockerfile and clean export against Alpine. alpine:3.23 is a deterministic negative fixture for this contract because it uses musl rather than glibc.

incompatible_ref="alpine:3.23"
incompatible_log="$validation_root/incompatible.log"
docker image pull --platform linux/amd64 -- "$incompatible_ref"

if docker build \
  --platform linux/amd64 \
  --build-arg "AUTO_ENVIRONMENT_BASE=$incompatible_ref" \
  --file "$validation_dockerfile" \
  --tag auto-environment-validation:incompatible \
  "$validation_context" >"$incompatible_log" 2>&1; then
  echo "expected alpine:3.23 to fail debian-contract-v0" >&2
  exit 1
fi

grep -F \
  'AUTO_ENVIRONMENT_IMAGE_CONTRACT_ERROR contract=debian-contract-v0 check=glibc-loader reason=requires-glibc-loader' \
  "$incompatible_log"

The marker is classified as an image_build failure: the image violates debian-contract-v0, so retrying it as provider infrastructure trouble would not help.

Clean up the local artifacts

docker image rm --force "$validation_tag"
case "$validation_root" in
  */auto-environment-validation.*) rm -rf -- "$validation_root" ;;
  *) echo "refusing to remove unexpected validation path: $validation_root" >&2; exit 1 ;;
esac

Author the inline environment

After the local preflight passes, put the environment directly on an agent or in an imported agent fragment. Standalone .auto/environments/ files are invalid.

.auto/agents/repository-agent.yaml

name: repository-agent
harness: codex
environment:
  name: repository-runtime
  image:
    kind: base
    ref: debian:bookworm
  steps:
    - RUN apt-get update && apt-get install -y --no-install-recommends make && rm -rf /var/lib/apt/lists/*
  setup:
    - name: repository-smoke
      commands:
        - make environment-setup
mounts:
  - kind: git
    repository: acme/widgets
    mountPath: /workspace/widgets
    ref: main
    auth:
      kind: githubApp
      capabilities:
        contents: read
workingDirectory: /workspace/widgets

Keep repository tests in their normal CI as well; the local image check adds a platform-compatibility leg but does not replace repository CI.

Run the hosted preflight

In a hosted auto sandbox, validate the committed .auto working tree through the local Auto MCP tool before apply:

Focused agent file

auto.resources.dry_run({
  "paths": [".auto/agents/repository-agent.yaml"]
})

Use auto.resources.dry_run({}) when you want full-directory, prune-aware validation. Both forms are read-only: they parse, validate, and plan the resource set, but they do not apply it and do not execute a production E2B template build. A clean dry-run therefore proves the hosted authoring surface accepts the exact image shape; it does not replace the local Docker preflight or a later real session through the hosted provider.

Environment reference

Field constraints for images, build steps, setup, caches, resources, and approvals.

GitHub Sync

How committed .auto changes are validated and applied after merge.

Get Started

Concepts

Examples

Reference

Validate an Environment Image

Choose the authored image

Debian contract v0

Run the local preflight

Author the inline environment

Run the hosted preflight

Environment reference

GitHub Sync

​Choose the authored image

​Debian contract v0

​Run the local preflight

​Author the inline environment

​Run the hosted preflight

Environment reference

GitHub Sync

Choose the authored image

Debian contract v0

Run the local preflight

Author the inline environment

Run the hosted preflight