Container Contract

Every container image the augments deploy tooling generates satisfies a uniform contract. Kubernetes, Cloud Run, ECS, App Runner, and Lambda all use the same image shape; only the orchestration layer differs.

The contract

Every generated image:

Binds 0.0.0.0 on $PORT so the platform can route traffic to it.
Reads configuration from environment variables, not from baked-in files.
Runs stateless: no in-process state that cannot survive a restart.
Handles SIGTERM with a drain window sized for in-flight agent turns (the Kubernetes manifests set terminationGracePeriodSeconds: 45, which allows active agent-loop turns to complete before the process exits).
Exposes GET /healthz (liveness) and GET /readyz (readiness) so orchestrators can distinguish a starting container from a crashed one.
Writes structured logs to stdout so the platform's log aggregator can collect them without additional configuration.

Generated Dockerfile

augments deploy init writes this Dockerfile at the build context root:

FROM python:3.12-slim
 
ENV PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1
 
WORKDIR /app
 
COPY requirements.txt ./
RUN pip install -r requirements.txt
 
RUN adduser --disabled-password --gecos "" appuser \
    && chown -R appuser:appuser /app
COPY . .
USER appuser
 
ENV PORT=8080 \
    AGENT_REF=my_pkg.agents:assistant
EXPOSE 8080
 
CMD ["sh", "-c", "augments serve --agent \"$AGENT_REF\" --host 0.0.0.0 --port \"$PORT\""]

The CMD passes --host 0.0.0.0 so the serving process binds all interfaces and accepts traffic from the container network. The platform-injected $PORT overrides the baked-in default when the platform sets it (Cloud Run, Knative, App Runner all do this).

Package installation

augments-adk is published to PyPI, so the generated requirements.txt references the package by name together with the extras the deployment needs:

augments-adk[serve,a2a]

Two alternatives when the image build should not resolve from PyPI:

Vendored wheel (zero external index lookups at build time):

# Copy the wheel into the build context first, then reference it:
augments-adk[serve,a2a] @ file:///app/augments_adk-<ver>-py3-none-any.whl

VCS install (useful during active development):

augments-adk[serve,a2a] @ git+https://github.com/augments-labs/augments-adk-python@<ref>

The generated requirements.txt ships with a comment explaining these options so the choice is visible at the point it needs to be made.

Build and push

Once requirements.txt is ready, build and push the image:

# Generate artifacts
augments deploy init \
  --agent my_pkg.agents:assistant \
  --image registry.example.com/my-agent:latest
 
# requirements.txt installs augments-adk from PyPI as generated;
# edit it first only to pin, vendor a wheel, or use a VCS URL, then:
augments deploy build \
  --agent my_pkg.agents:assistant \
  --image registry.example.com/my-agent:latest \
  --push

deploy build runs docker build followed by docker push (when --push is given) by shelling out to the operator's installed docker CLI. The framework imports no Docker SDK.

Environment variables

The container reads all configuration from environment variables. Pass API keys and other secrets at runtime rather than baking them into the image:

# Local test
docker run -p 8080:8080 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  registry.example.com/my-agent:latest
 
# Name the secret keys the manifests should surface
augments deploy init \
  --agent my_pkg.agents:assistant \
  --image registry.example.com/my-agent:latest \
  --env-key OPENAI_API_KEY \
  --env-key ANTHROPIC_API_KEY

--env-key (repeatable) records which environment variable names carry secrets. The Kubernetes and Helm manifests reference them from Kubernetes Secrets; Cloud Run maps them to Secret Manager secrets of the same name.