DEV Community: Koti Vellanki

Migration, Production Adoption, Hardened Packages & Real-World Patterns

Koti Vellanki — Thu, 20 Aug 2026 12:28:08 +0000

Docker Hardened Images Series — Blog 5 (Final)

What We Are Building

This final blog turns everything you have learned into a practical adoption plan.

You will:

Walk through a realistic migration of an existing Dockerfile
Use a clear migration checklist so nothing is missed
Understand when Community is enough and when Select/Enterprise becomes useful
Get a short overview of hardened system packages
Leave with a production checklist and honest limitations
See how Docker Hardened Images and Docker Sandboxes fit together

Why This Matters

Pulling a DHI and building a new service is easy.

Migrating an existing production service without breaking it is the real work.

Most failures happen because of the same few issues:

Missing shell or package manager in the runtime stage
Application cannot run as non-root
Trying to bind to a privileged port
Forgetting that secrets and tools do not belong in the final image

This blog gives you the checklist and the judgement to avoid those problems.

What You Should Know Before Starting

Full Hardened Images series (Blogs 1–4) completed
At least one existing Dockerfile you can migrate (we will use a typical example)

Migration Checklist (Print This)

Item	What to do	Why it fails if ignored
Base image	Change `FROM` to a matching `dhi.io/...` variant	Still using the old attack surface
Package management	Install only in `*-dev` stage, copy artefacts	Runtime image has no package manager
Shell commands	Move all `RUN` that need a shell into the build stage	Runtime image has no shell
Non-root user	Ensure files are readable/executable by the non-root user (usually UID 65532)	Permission denied at runtime
Ports	Listen on ≥ 1025 inside the container	Non-root cannot bind to privileged ports
TLS certificates	Remove manual `ca-certificates` install steps	Already present in DHI
ENTRYPOINT / CMD	Inspect the DHI and adjust if needed	Unexpected default entrypoint
Multi-stage	Always use `-dev` for build, pure runtime for final	Final image becomes large and less secure
Secrets	Never bake secrets into layers	They will be visible in the image history
Policy check	Run `docker scout policy ... --policy-bundle dhi/policies:latest`	Image may not meet the hardened standard

Step 1 — Realistic Migration Example

Before (typical official image)

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 80
CMD ["python", "app.py"]

After (proper DHI multi-stage)

# syntax=docker/dockerfile:1

FROM dhi.io/python:3.13-dev AS builder
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app
RUN python -m venv /app/venv
ENV PATH="/app/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM dhi.io/python:3.13
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"
WORKDIR /app
COPY --from=builder /app/venv /app/venv
COPY app.py .
EXPOSE 8000
CMD ["python", "app.py"]

Key changes:

Build tools only in the first stage
Final image is minimal and non-root
Port moved above 1024
No unnecessary packages left behind

Build and test:

docker build -t migrated-app .
docker run --rm -p 8000:8000 migrated-app
docker scout policy migrated-app --policy-bundle dhi/policies:latest

Step 2 — Community vs Select vs Enterprise (Honest View)

Need	Community (free)	Select	Enterprise
Minimal, near-zero CVE images	Yes	Yes	Yes
Signed SBOM + SLSA provenance	Yes	Yes	Yes
FIPS / STIG variants	No	Yes	Yes
7-day SLA for critical/high CVEs	No	Yes	Yes
Customisations	No	Limited (5)	Unlimited
Hardened system packages repository	Public only	Limited	Full access
Extended lifecycle (post-EOL)	No	No	Yes (add-on)

Practical recommendation

Start with Community for almost every service.

Move to Select/Enterprise only when you have a concrete compliance (FIPS/STIG) or SLA requirement.

Step 3 — Hardened System Packages (Short Overview)

Docker builds many system packages from source and signs them.

These packages are already inside the DHI base images.

Community users can also configure the public hardened package repositories in their own Dockerfiles if they need extra packages during a build stage.

Enterprise customers get a private repository with broader access and longer support.

For most applications you will never need to touch this — the base image already contains the hardened packages you need.

Step 4 — Production Adoption Checklist

[ ] Every new service starts from a DHI base
[ ] Existing services have a migration ticket and a deadline
[ ] Multi-stage pattern is the team standard
[ ] CI always authenticates to dhi.io and runs the DHI policy bundle
[ ] Policy failures block the merge
[ ] Images are scanned and attested in the pipeline
[ ] Non-root and high ports are verified in staging
[ ] Team knows how to use docker scout attest and docker scout policy
[ ] Old official base images are removed from the allowed list

Step 5 — Combining with Docker Sandboxes

The two series fit together cleanly:

Developers use Docker Sandboxes so AI agents can work safely
Those same agents (or the CI) build application images from Docker Hardened Images
The final artefact that reaches production is both built in an isolated environment and based on a hardened, attested base

This gives you strong isolation during development and strong supply-chain guarantees at runtime.

Realistic Limitations (Be Honest)

Runtime images have no shell → debugging needs docker debug, a sidecar, or a temporary -dev container
Some legacy applications still expect to run as root or bind to port 80 → you must change the application or use a workaround
Community tier has no SLA — patch timing follows upstream + Docker’s cadence
Very exotic native dependencies may not yet exist as hardened packages
Organisation governance (for Sandboxes) and DHI Select/Enterprise are separate paid offerings

Common Migration Pitfalls

Leaving a USER root statement “just in case”
Installing packages in the final stage
Forgetting to update health-check or readiness probes that assumed port 80
Assuming every tag has a -dev variant (check the catalog)
Migrating only the base image and leaving the rest of the Dockerfile unchanged

Troubleshooting Quick Reference

Symptom	Most common cause	Fix
`exec: "bash": executable not found`	Runtime image used for a shell command	Move the command to a `-dev` stage
Permission denied	Non-root user cannot write	Fix ownership with `COPY --chown` or in builder
Address already in use / bind error	Trying to use port < 1024	Change application to listen on ≥ 1025
Policy fails on “shell present”	Final stage still has a shell	Use pure runtime variant
Cannot pull in CI	Missing `docker login dhi.io`	Add the login step shown in Blog 4

Cleanup

docker rmi migrated-app 2>/dev/null || true

What We Learned in the Whole Hardened Images Series

Why typical images need hardening and how to pull the first DHI
Anatomy of runtime vs dev variants and how to build real applications
SBOMs, provenance, signatures and how to enforce the same policies
Production multi-stage Dockerfiles + CI gates
Migration checklist, tier decisions, limitations and how to adopt safely

You now have a complete, practical path from “I have heard of hardened images” to “I can migrate and run them in production with confidence”.

Final Combined Recommendation

Use Docker Sandboxes for any AI coding agent work
Use Docker Hardened Images as the base for every application image
Enforce both with clear team defaults and automated checks

That combination gives you strong isolation during development and a minimal, attested, continuously maintained runtime in production.

References

https://docs.docker.com/dhi/migration/checklist/ — official migration checklist
https://docs.docker.com/dhi/ — tiers and feature comparison
https://docs.docker.com/dhi/how-to/hardened-packages/ — system packages
https://docs.docker.com/dhi/how-to/use/ — adoption considerations
https://docs.docker.com/dhi/migration/ — language-specific migration guides

All technical claims verified against current official documentation (August 2026).

Multi-Stage Best Practices + CI/CD Integration

Koti Vellanki — Thu, 20 Aug 2026 12:23:32 +0000

Docker Hardened Images Series — Blog 4

What We Are Building

By the end of this blog you will have:

A clean, production-ready multi-stage Dockerfile that uses Docker Hardened Images correctly
A GitHub Actions workflow that:
- Authenticates to dhi.io
- Builds the image
- Runs the official DHI policy checks
- Fails the pipeline if the image does not meet the hardened standard

This turns everything from the previous blogs into a repeatable, automated practice.

Why This Matters

A good local Dockerfile is not enough. In real teams the image must be built the same way every time, and security checks must be automatic.

If the policy check only runs on a developer laptop, it will be skipped under pressure.

If the CI cannot pull from dhi.io, the build will fail randomly.

If the Dockerfile still uses a fat base image or runs as root, the hardened base loses most of its value.

This blog closes those gaps.

What You Should Know Before Starting

Blogs 1–3 completed
Basic GitHub Actions knowledge (or any CI that can run Docker)
A GitHub repository (public or private) where you can add secrets

Step 1 — Production Multi-Stage Dockerfile (Best Practices)

Here is the pattern I recommend for most language frameworks (Python example):

# syntax=docker/dockerfile:1

# ---------- Build stage ----------
FROM dhi.io/python:3.13-dev AS builder

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/app/venv/bin:$PATH"

WORKDIR /app

# Create isolated environment
RUN python -m venv /app/venv

COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --no-cache-dir -r requirements.txt

# ---------- Runtime stage ----------
FROM dhi.io/python:3.13

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/app/venv/bin:$PATH"

WORKDIR /app

# Copy only what is required
COPY --from=builder /app/venv /app/venv
COPY app.py .

# Runtime image already defaults to non-root
EXPOSE 8000
CMD ["python", "app.py"]

Key rules this Dockerfile follows

Rule	Why it matters
`-dev` only in build stage	Tools exist only where they are needed
Pure runtime variant in final stage	Minimal attack surface, non-root
Virtual environment (or equivalent)	Keeps runtime clean
Cache mount for pip/npm	Faster CI builds
No secrets in layers	Secrets must come from the runtime environment or a secret store
Explicit `CMD` in exec form	No shell required

Multi-stage Flow

Explanation

Everything that needs a package manager or compiler stays in the first stage.

Only the final artefacts are copied into the hardened runtime image.

Step 2 — Local Verification Before CI

docker build -t my-dhi-app:local .
docker run --rm -p 8000:8000 my-dhi-app:local

# Policy check
docker scout policy my-dhi-app:local --policy-bundle dhi/policies:latest

Fix any failures before you push.

Step 3 — GitHub Actions Workflow (Complete Example)

Create .github/workflows/dhi-build.yml:

name: Build and check with Docker Hardened Images

on:
  push:
    branches: [ "main" ]
  pull_request:

env:
  IMAGE_NAME: my-dhi-app:${{ github.sha }}

jobs:
  build-and-policy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Docker Hub (for Scout + policy bundle)
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}

      - name: Log in to dhi.io
        uses: docker/login-action@v3
        with:
          registry: dhi.io
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}

      - name: Build image
        uses: docker/build-push-action@v6
        with:
          context: .
          load: true
          tags: ${{ env.IMAGE_NAME }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Evaluate against DHI policies
        uses: docker/scout-action@v1
        with:
          command: policy
          image: ${{ env.IMAGE_NAME }}
          policy-bundle: dhi/policies:latest
          exit-code: true          # fail the job if any policy is violated

Required GitHub Secrets

In the repository settings → Secrets and variables → Actions, add:

DOCKER_USER — your Docker Hub username
DOCKER_PAT — a personal access token with read access (and write if you later push images)

What the pipeline does

Checks out the code
Logs into both Docker Hub and dhi.io
Builds the multi-stage image (with cache)
Runs the official DHI policy bundle
Fails the pull request or push if the image does not meet the hardened standard

Step 4 — Optional Improvements

Push the image only on main after the policy check passes
Pin the policy-bundle digest instead of :latest for reproducibility
Add docker scout cves as an extra informational step
Use OIDC login (available for Docker organisations) instead of long-lived PATs when possible

Let’s Break It

Temporarily change the final stage back to a normal python:3.13 image.
Push the change.
Watch the policy step fail (root user, extra packages, missing attestations, etc.).
Revert to the DHI runtime stage and see the pipeline go green again.

Production Thinking

In a real team I would:

Make this workflow the default for every service repository
Treat a failing DHI policy check the same way as a failing unit test
Keep the multi-stage Dockerfile pattern in a shared template or cookiecutter
Review any exception that needs a -dev image in the final stage (almost never justified)
Combine this with the Sandboxes series so agents themselves build on hardened bases

Security Considerations

The CI runner must be able to authenticate to dhi.io; otherwise builds become flaky
Long-lived PATs should be rotated and scoped as tightly as possible
Policy evaluation happens on the final image, not just the base — that is what matters
Caching is fine; it does not weaken the policy check

Common Mistakes

Logging into Docker Hub but forgetting dhi.io
Using a runtime image in the build stage (missing tools)
Leaving exit-code: false so the policy check never fails the build
Baking secrets into the image layers
Using :latest tags for base images in production Dockerfiles

Troubleshooting

Problem	Likely cause	Fix
`unauthorized: dhi.io`	Missing or wrong login to dhi.io	Add the second `docker/login-action` step
Policy step always green	`exit-code` not set to true	Set `exit-code: true`
Build fails on `pip` / `npm`	Runtime image used for build	Switch build stage to `*-dev`
Cache not helping	No `cache-from` / `cache-to`	Add the GHA cache lines shown above
Policy bundle not found	Not logged into Docker Hub	Ensure Hub login happens before the scout step

Cleanup

No permanent resources are created on your machine.

In GitHub you can delete the workflow file or the test branch when finished.

What We Learned

Multi-stage with a -dev build stage + pure runtime stage is the standard pattern
CI must authenticate to both Docker Hub and dhi.io
The official DHI policy bundle can be enforced automatically on every build
A failing policy check should block the merge

You now have a complete, automated path from code to a hardened production image.

What’s Next?

In the final blog (Blog 5) we cover migration of existing applications, production adoption checklist, hardened system packages overview, known limitations, and how to combine Docker Hardened Images with the Sandboxes series for a full secure development workflow.

References

https://docs.docker.com/dhi/how-to/use/ — multi-stage patterns and CI notes
https://docs.docker.com/dhi/how-to/policies/ — policy bundle and GitHub Actions example
https://docs.docker.com/build/cache/backends/gha/ — GitHub Actions cache
Official Scout GitHub Action documentation

All commands and workflow patterns verified against current official documentation (August 2026).

SBOM, Provenance, Signatures, Scanning & DHI Policies

Koti Vellanki — Tue, 18 Aug 2026 02:59:45 +0000

Docker Hardened Images Series — Blog 3

What We Are Building

By the end of this blog you will:

Inspect the signed attestations that every Docker Hardened Image carries
Understand SBOM, provenance, signatures and VEX in practical terms
Verify that an image really comes from Docker and has not been tampered with
Scan your own application image
Evaluate any image against the same policy bar that DHI images meet

This is the supply-chain transparency part of hardened images.

Why This Matters

A minimal image with few CVEs is good.

Knowing exactly what is inside it, how it was built, and being able to prove those claims is better.

Docker Hardened Images ship with:

A signed Software Bill of Materials (SBOM)
SLSA Build Level 3 provenance
Cryptographic signatures
VEX statements (which vulnerabilities are actually exploitable)

You can inspect and verify all of this yourself. You can also hold your own images to the same standard using the official DHI policy bundle.

What You Should Know Before Starting

Blogs 1 and 2 completed
docker login dhi.io already done
Docker Scout available (included with Docker Desktop)

Core Concepts (Simple Explanations)

Concept	What it answers	Why it matters
SBOM	What packages and versions are inside the image?	Transparency & vulnerability matching
Provenance	Who built it, from which source, with which steps?	Tamper resistance (SLSA)
Signature	Has this attestation been altered since Docker signed it?	Trust
VEX	Is this CVE actually exploitable in this image?	Reduce noise in scans

Supply-chain Metadata Flow

Explanation

Docker builds the image and attaches signed attestations.

You (or your CI) can later pull those attestations and verify the signatures.

If the signature is valid, you know the metadata has not been changed.

Step 1 — List Attestations on a DHI

docker scout attest list dhi.io/python:3.13

Output

➜  dhi-lab docker scout attest list dhi.io/python:3.13
    i New version 1.24.0 available (installed version is 1.23.1) at https://github.com/docker/scout-cli
    ✓ SBOM obtained from attestation, 100 packages found
    ✓ Provenance obtained from attestation


## Overview

              │                    Analyzed Image                     
──────────────┼───────────────────────────────────────────────────────
 Subject      │  dhi.io/python:3.13                                   
   digest     │  24a8822f76af                                         
   platform   │ linux/arm64                                           
   provenance │ https://github.com/docker-hardened-images/definitions 
              │  5fb32dbb43253700792f258345f151035442841c             
   size       │ 26 MB                                                 
   packages   │ 100                                                   


## Attestations

https://cyclonedx.org/bom/v1.6  CycloneDX SBOM  
  sha256:cd84b3cc8ea0476ce46f0332d80c32559fb027a75c4e54c0e53d9e68d9c6335f

 Name                        │  dhi.io/python                             
   digest                    │  cd84b3cc8ea0                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://cyclonedx.org/bom/v1.6             


https://docker.com/dhi/changelog/v0.1  Changelog  
  sha256:8d5f5d332cd3f4849aee647a6e3cd3656273364c8330b73a3204dd15ec2fb615

 Name                        │  dhi.io/python                             
   digest                    │  8d5f5d332cd3                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://docker.com/dhi/changelog/v0.1      


https://docker.com/dhi/source/v0.1
  sha256:ff88fffcb43f8b1f1c097f03b3b7d0625456ee2b6c94c43609442ab77cdc07fa

 Name                        │  dhi.io/python                             
   digest                    │  ff88fffcb43f                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://docker.com/dhi/source/v0.1         


https://in-toto.io/attestation/vulns/v0.2  in-toto vulnerabilities  
  sha256:37889af6f7e43d2c7990b75801624071f451bc62037faf64f2268fb00853cdea

 Name                        │  dhi.io/python                             
   digest                    │  37889af6f7e4                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://in-toto.io/attestation/vulns/v0.2  


https://openvex.dev/ns/v0.2.0  OpenVEX  
  sha256:613cdd6ab043d43ca77ffcf90aba336899a03d51a84c93f0bd5c620d0f7ca37a

 Name                          │  dhi.io/python                             
   digest                      │  613cdd6ab043                              
                               │                                            
 Media type                    │ application/vnd.oci.image.manifest.v1+json 
 Artifact type                 │ application/vnd.in-toto+json               
 Annotations                   │                                            
   com.docker.scout.vex.source │ exceptions                                 
   in-toto.io/predicate-type   │ https://openvex.dev/ns/v0.2.0              


https://scout.docker.com/provenance/v0.1  Scout provenance  
  sha256:6a19c4b87c703e42ae53005562088c95e1a94d6c72dd07d47e064935a3b9bfea

 Name                        │  dhi.io/python                             
   digest                    │  6a19c4b87c70                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://scout.docker.com/provenance/v0.1   


https://scout.docker.com/sbom/v0.1  Scout SBOM  
  sha256:586bc87d9734f37b0733973179241ec2f955fbed732dc38522e421f1f4c9b0d1

 Name                        │  dhi.io/python                             
   digest                    │  586bc87d9734                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://scout.docker.com/sbom/v0.1         


https://scout.docker.com/secrets/v0.1  Scout secret scan  
  sha256:d20496aab3d5e4b3a50e091bac7c0e7ddb1f6909c23e9ea0c0c3ae8e192abd31

 Name                        │  dhi.io/python                             
   digest                    │  d20496aab3d5                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://scout.docker.com/secrets/v0.1      


https://scout.docker.com/tests/v0.1  Scout test report  
  sha256:7a2f5e93a4be1d0eb3c5ed966104c6fb193b87de3a20b7cb536bd10e4418daf2

 Name                        │  dhi.io/python                             
   digest                    │  7a2f5e93a4be                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://scout.docker.com/tests/v0.1        


https://scout.docker.com/virus/v0.1  Scout virus/malware report  
  sha256:55aa6a3cd931cfe60c4abff38787668580a1c425e6f385b6a8e9b04dd3a47931

 Name                        │  dhi.io/python                             
   digest                    │  55aa6a3cd931                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://scout.docker.com/virus/v0.1        


https://scout.docker.com/vulnerabilities/v0.1  Scout vulnerabilities  
  sha256:85ea5c8e021775fcd6933bfc712dd45b0ba63275e07b4bc44b1be440bf194a38

 Name                        │  dhi.io/python                                
   digest                    │  85ea5c8e0217                                 
                             │                                               
 Media type                  │ application/vnd.oci.image.manifest.v1+json    
 Artifact type               │ application/vnd.in-toto+json                  
 Annotations                 │                                               
   in-toto.io/predicate-type │ https://scout.docker.com/vulnerabilities/v0.1 


https://slsa.dev/provenance/v0.2  SLSA provenance  
  sha256:43283e5c83d2625542ee63797cf9cd3d0ee94e6012c6b5b8ed8c0a482e698156

 Name                        │  dhi.io/python                             
   digest                    │  43283e5c83d2                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://slsa.dev/provenance/v0.2           


https://slsa.dev/provenance/v1  SLSA provenance  
  sha256:22870de00ae3918dd426c22dff0628620586e50d97f14df52c846f266a232bb2

 Name                        │  dhi.io/python                             
   digest                    │  22870de00ae3                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://slsa.dev/provenance/v1             


https://slsa.dev/verification_summary/v1  SLSA verification summary  
  sha256:63485f84f89c1534b60e9a24b9bef9d4c10bba652bd9e351bb7861742b5a9c3c

 Name                        │  dhi.io/python                             
   digest                    │  63485f84f89c                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://slsa.dev/verification_summary/v1   


https://spdx.dev/Document  SPDX SBOM  
  sha256:91c071b3faf69247626618fcf7cc758415553ab6edb394b50131cd50f3d36180

 Name                        │  dhi.io/python                             
   digest                    │  91c071b3faf6                              
                             │                                            
 Media type                  │ application/vnd.oci.image.manifest.v1+json 
 Artifact type               │ application/vnd.in-toto+json               
 Annotations                 │                                            
   in-toto.io/predicate-type │ https://spdx.dev/Document                  

➜  dhi-lab

You will see several attestations (SBOM, provenance, vulnerability reports, etc.).

Note: If the image is already present locally, prefix the name with registry://:
docker scout attest list registry://dhi.io/python:3.13

Step 2 — Retrieve and Verify an SBOM

docker scout attest get \
  --predicate-type https://scout.docker.com/sbom/v0.1 \
  --verify \
  dhi.io/python:3.13

If verification succeeds you will see confirmation that the signature is valid, plus the equivalent cosign command.

You can also ask for a CycloneDX SBOM:

docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/python:3.13

Or simply:

docker scout sbom dhi.io/python:3.13

Step 3 — Scan Your Own Application Image

Rebuild the small Flask app from Blog 2 (or any image you have):

pwd
#navigate to dhi-lab
dhi-lab   # or recreate the simple app
docker build -t my-dhi-app:v1 .

➜  dhi-lab docker build -t my-dhi-app:v1 .
[+] Building 5.4s (19/19) FINISHED                                                                                                                                                        docker:desktop-linux
 => [internal] load build definition from Dockerfile                                                                                                                                                      0.0s
 => => transferring dockerfile: 728B                                                                                                                                                                      0.0s
 => resolve image config for docker-image://docker.io/docker/dockerfile:1                                                                                                                                 1.7s
 => [auth] docker/dockerfile:pull token for registry-1.docker.io                                                                                                                                          0.0s
 => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:ecfaec9ed6d810b56388c508f4121597bfbba70d41a6dfeee4d8cad5f295fc32                                                                           0.0s
 => => resolve docker.io/docker/dockerfile:1@sha256:ecfaec9ed6d810b56388c508f4121597bfbba70d41a6dfeee4d8cad5f295fc32                                                                                      0.0s
 => [internal] load metadata for dhi.io/python:3.13                                                                                                                                                       2.2s
 => [internal] load metadata for dhi.io/python:3.13-dev                                                                                                                                                   3.4s
 => [auth] python:pull token for dhi.io                                                                                                                                                                   0.0s
 => [internal] load .dockerignore                                                                                                                                                                         0.0s
 => => transferring context: 2B                                                                                                                                                                           0.0s
 => [builder 1/5] FROM dhi.io/python:3.13-dev@sha256:b31351cce7a96e52c272b009d9167f62e8ffba0f0531bce7c55b74d580c4363a                                                                                     0.0s
 => => resolve dhi.io/python:3.13-dev@sha256:b31351cce7a96e52c272b009d9167f62e8ffba0f0531bce7c55b74d580c4363a                                                                                             0.0s
 => [internal] load build context                                                                                                                                                                         0.0s
 => => transferring context: 63B                                                                                                                                                                          0.0s
 => [stage-1 1/4] FROM dhi.io/python:3.13@sha256:5669b3baeccdcd7b189df90aab1616a92bee6a766dc537b90a169268c0ab962c                                                                                         0.0s
 => => resolve dhi.io/python:3.13@sha256:5669b3baeccdcd7b189df90aab1616a92bee6a766dc537b90a169268c0ab962c                                                                                                 0.0s
 => CACHED [stage-1 2/4] WORKDIR /app                                                                                                                                                                     0.0s
 => CACHED [builder 2/5] WORKDIR /app                                                                                                                                                                     0.0s
 => CACHED [builder 3/5] RUN python -m venv /app/venv                                                                                                                                                     0.0s
 => CACHED [builder 4/5] COPY requirements.txt .                                                                                                                                                          0.0s
 => CACHED [builder 5/5] RUN pip install --no-cache-dir -r requirements.txt                                                                                                                               0.0s
 => CACHED [stage-1 3/4] COPY --from=builder /app/venv /app/venv                                                                                                                                          0.0s
 => CACHED [stage-1 4/4] COPY app.py .                                                                                                                                                                    0.0s
 => exporting to image                                                                                                                                                                                    0.0s
 => => exporting layers                                                                                                                                                                                   0.0s
 => => exporting manifest sha256:2d981cdcc89cc5122fae8386ac9291917ec2a6e1c3b0352025185161a8ab6e68                                                                                                         0.0s
 => => exporting config sha256:e9b998ce0fe58f26568f8371b1acfadeb88b6fdb621ef737cc3860e2ab98c1d2                                                                                                           0.0s
 => => exporting attestation manifest sha256:31ed97bd0834de4b09ba5d46c4245e340119ad852f6a4ee702c537cbfdc87ff6                                                                                             0.0s
 => => exporting manifest list sha256:e8c9377134bb24982fd0fb771881c290c9a3545ba0177b0fb5041db927991aa3                                                                                                    0.0s
 => => naming to docker.io/library/my-dhi-app:v1                                                                                                                                                          0.0s
 => => unpacking to docker.io/library/my-dhi-app:v1                                                                                                                                                       0.0s

View build details: docker-desktop://dashboard/build/desktop-linux/desktop-linux/pu3qzidtva9nrroqyhv7mlsm5
➜  dhi-lab

Scan it:

docker scout cves my-dhi-app:v1

Output

➜  dhi-lab docker scout cves my-dhi-app:v1
    i New version 1.24.0 available (installed version is 1.23.1) at https://github.com/docker/scout-cli
    ✓ Image stored for indexing
    ✓ Indexed 107 packages
    ✓ Provenance obtained from attestation
    ✗ Detected 8 vulnerable packages with a total of 17 vulnerabilities


## Overview

                   │       Analyzed Image        
───────────────────┼─────────────────────────────
 Target            │  my-dhi-app:v1              
   digest          │  e8c9377134bb               
   platform        │ linux/arm64                 
   vulnerabilities │    0C     3H     2M    12L  
   size            │ 31 MB                       
   packages        │ 107                         


## Packages and Vulnerabilities

   0C     2H     0M     0L  msgpack 1.1.2
pkg:pypi/msgpack@1.1.2

    ✗ HIGH GHSA-6v7p-g79w-8964 [Use After Free]
      https://scout.docker.com/v/GHSA-6v7p-g79w-8964
      Affected range : <=1.2.0                                      
      Fixed version  : 1.2.1                                        
      CVSS Score     : 7.5                                          
      CVSS Vector    : CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H 

    ✗ HIGH CVE-2026-57585
      https://scout.docker.com/v/CVE-2026-57585
      Affected range : <1.2.1                                       
      Fixed version  : 1.2.1                                        
      CVSS Score     : 7.5                                          
      CVSS Vector    : CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H 


   0C     1H     1M     0L  setuptools 70.3.0
pkg:pypi/setuptools@70.3.0

    ✗ HIGH CVE-2025-47273 [Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')]
      https://scout.docker.com/v/CVE-2025-47273
      Affected range : <78.1.1                                                             
      Fixed version  : 78.1.1                                                              
      CVSS Score     : 7.7                                                                 
      CVSS Vector    : CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:N/VI:H/VA:N/SC:N/SI:N/SA:N/E:P 

    ✗ MEDIUM CVE-2026-59890 [Improper Handling of Unicode Encoding]
      https://scout.docker.com/v/CVE-2026-59890
      Affected range : <83.0.0                                      
      Fixed version  : 83.0.0                                       
      CVSS Score     : 6.1                                          
      CVSS Vector    : CVSS:3.1/AV:L/AC:L/PR:N/UI:R/S:U/C:H/I:L/A:N 


   0C     0H     1M     0L  expat 2.8.2-1~deb13u1+dhi0
pkg:deb/debian/expat@2.8.2-1~deb13u1%2Bdhi0?os_distro=trixie&os_name=debian&os_version=13

    ✗ MEDIUM CVE-2026-72522
      https://scout.docker.com/v/CVE-2026-72522
      Affected range : >0        
      Fixed version  : not fixed 


   0C     0H     0M     7L  glibc 2.41-12+deb13u3+dhi1
pkg:deb/debian/glibc@2.41-12%2Bdeb13u3%2Bdhi1?os_distro=trixie&os_name=debian&os_version=13

    ✗ LOW CVE-2019-9192
      https://scout.docker.com/v/CVE-2019-9192
      Affected range : >0        
      Fixed version  : not fixed 

    ✗ LOW CVE-2019-1010025
      https://scout.docker.com/v/CVE-2019-1010025
      Affected range : >0        
      Fixed version  : not fixed 

    ✗ LOW CVE-2019-1010024
      https://scout.docker.com/v/CVE-2019-1010024
      Affected range : >0        
      Fixed version  : not fixed 

    ✗ LOW CVE-2019-1010023
      https://scout.docker.com/v/CVE-2019-1010023
      Affected range : >0        
      Fixed version  : not fixed 

    ✗ LOW CVE-2019-1010022
      https://scout.docker.com/v/CVE-2019-1010022
      Affected range : >0        
      Fixed version  : not fixed 

    ✗ LOW CVE-2018-20796
      https://scout.docker.com/v/CVE-2018-20796
      Affected range : >0        
      Fixed version  : not fixed 

    ✗ LOW CVE-2010-4756
      https://scout.docker.com/v/CVE-2010-4756
      Affected range : >0        
      Fixed version  : not fixed 


   0C     0H     0M     2L  sqlite3 3.46.1-7+deb13u1+dhi2
pkg:deb/debian/sqlite3@3.46.1-7%2Bdeb13u1%2Bdhi2?os_distro=trixie&os_name=debian&os_version=13

    ✗ LOW CVE-2025-70873
      https://scout.docker.com/v/CVE-2025-70873
      Affected range : >0        
      Fixed version  : not fixed 

    ✗ LOW CVE-2021-45346
      https://scout.docker.com/v/CVE-2021-45346
      Affected range : >0        
      Fixed version  : not fixed 


   0C     0H     0M     1L  openssl 3.5.6-1~deb13u2+dhi1
pkg:deb/debian/openssl@3.5.6-1~deb13u2%2Bdhi1?os_distro=trixie&os_name=debian&os_version=13

    ✗ LOW CVE-2010-0928
      https://scout.docker.com/v/CVE-2010-0928
      Affected range : >=3.2.1-3 
      Fixed version  : not fixed 


   0C     0H     0M     1L  flask 3.0.3
pkg:pypi/flask@3.0.3

    ✗ LOW CVE-2026-27205 [Use of Cache Containing Sensitive Information]
      https://scout.docker.com/v/CVE-2026-27205
      Affected range : <3.1.3                                                          
      Fixed version  : 3.1.3                                                           
      CVSS Score     : 2.3                                                             
      CVSS Vector    : CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:P/VC:L/VI:N/VA:N/SC:N/SI:N/SA:N 


   0C     0H     0M     1L  util-linux 2.41.5-0+deb13u1+dhi2
pkg:deb/debian/util-linux@2.41.5-0%2Bdeb13u1%2Bdhi2?os_distro=trixie&os_name=debian&os_version=13

    ✗ LOW CVE-2022-0563
      https://scout.docker.com/v/CVE-2022-0563
      Affected range : >0        
      Fixed version  : not fixed 



17 vulnerabilities found in 8 packages
  CRITICAL  0  
  HIGH      3  
  MEDIUM    2  
  LOW       12 


What's next:
    View base image update recommendations → docker scout recommendations my-dhi-app:v1

➜  dhi-lab

Compare with the pure base:

docker scout compare my-dhi-app:v1 --to dhi.io/python:3.13 --ignore-unchanged

Output

➜  dhi-lab docker scout compare my-dhi-app:v1 --to dhi.io/python:3.13 --ignore-unchanged
    i New version 1.24.0 available (installed version is 1.23.1) at https://github.com/docker/scout-cli
    ! 'docker scout compare' is experimental and its behaviour might change in the future
    ✓ Image stored for indexing
    ✓ Indexed 107 packages
    ✓ Provenance obtained from attestation
    ✓ SBOM obtained from attestation, 100 packages found
    ✓ Provenance obtained from attestation
    ✓ Policy evaluation completed
    ✓ VEX statements obtained from attestation
    ✓ Policy evaluation completed
    ✓ VEX statements obtained from attestation


  ## Overview

                     │       Analyzed Image        │                   Comparison Image                    
  ───────────────────┼─────────────────────────────┼───────────────────────────────────────────────────────
   Target            │  my-dhi-app:v1              │  dhi.io/python:3.13                                   
     digest          │  e8c9377134bb               │  24a8822f76af                                         
     tag             │  v1                         │  3.13                                                 
     platform        │ linux/arm64                 │ linux/arm64                                           
     provenance      │                             │ https://github.com/docker-hardened-images/definitions 
                     │                             │  5fb32dbb43253700792f258345f151035442841c             
     vulnerabilities │    0C     3H     2M    12L  │    0C     0H     1M     0L                            
                     │           +3     +1    +12  │                                                       
     size            │ 31 MB (+5.4 MB)             │ 26 MB                                                 
     packages        │ 107 (+7)                    │ 100                                                   
                     │                             │                                                       


  ## Environment Variables


    - PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    + PATH=/app/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    + PYTHONDONTWRITEBYTECODE=1
    + PYTHONUNBUFFERED=1
      PYTHON_VERSION=3.13.15
      SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt



  ## Labels


      com.docker.dhi.chain-id=sha256:a12342a94f7cf5f1d5dc0c6bc57007908b47f8e8681d261c97ec9aa60c9cdcc0
      com.docker.dhi.compliance=cis
      com.docker.dhi.created=2026-08-12T13:14:57Z
      com.docker.dhi.date.end-of-life=2029-10-31
      com.docker.dhi.date.release=2024-10-07
      com.docker.dhi.definition=image/python/debian-13/3.13
      com.docker.dhi.distro=debian-13
      com.docker.dhi.entitlement=public
      com.docker.dhi.flavor=
      com.docker.dhi.name=dhi/python
      com.docker.dhi.package-manager=
      com.docker.dhi.shell=
      com.docker.dhi.title=Python 3.13.x
      com.docker.dhi.url=https://dhi.io/catalog/python
      com.docker.dhi.variant=runtime
      com.docker.dhi.version=3.13.15-debian13



  ## Config


    + 8000/tcp=
    - cmd=python3
    + cmd=python app.py
      user=65532
    - workdir=/
    + workdir=/app



  ## Policies


  0 improved, 2 worsened

    Policy                                       Analyzed  Comparison  Change             

    Default non-root user                        ✓         ✓                   No Change  
    No copyleft licenses                         ! 119     ! 119               No Change  
    No fixable critical or high vulnerabilities  ! 3       ✓           +3      Worsened   
    No high-profile vulnerabilities              ✓         ✓                   No Change  
    No outdated base images                      ✓         ✓                   No Change  
    No unapproved base images                    ✓         ✓                   No Change  
    Supply chain attestations                    ! 1       ✓           +1      Worsened   

      View policy details → docker scout policy my-dhi-app:v1


  ## Packages and Vulnerabilities


    +    7 packages added  
        95 packages unchanged


    + 16 vulnerabilities added


     Package       Type  Version  Compared Version  

  +  blinker       pypi  1.9.0                      
  +  click         pypi  8.4.2                      
  +  flask         pypi  3.0.3                      
     └─  +  LOW          CVE-2026-27205  [https://scout.docker.com/v/CVE-2026-27205]  
                         2.3  Use of Cache Containing Sensitive Information  
                         ✓ fixed in  3.1.3   

  +  itsdangerous  pypi  2.2.0                      
  +  jinja2        pypi  3.1.6                      
  +  markupsafe    pypi  3.0.3                      
  +  werkzeug      pypi  3.1.8                      


➜  dhi-lab

Step 4 — Evaluate Against Official DHI Policies

Docker publishes the exact policy set that hardened images are held to. You can apply the same policies to any image:

docker scout policy my-dhi-app:v1 --policy-bundle dhi/policies:latest

Output

➜  dhi-lab docker scout policy my-dhi-app:v1 --policy-bundle dhi/policies:latest
    i New version 1.24.0 available (installed version is 1.23.1) at https://github.com/docker/scout-cli
    ! 'docker scout policy' is experimental and its behaviour might change in the future
    ✓ Image stored for indexing
    ✓ Indexed 107 packages
    ✓ Provenance obtained from attestation
    ✓ Policy evaluation completed


## Overview

            │ Analyzed Image  
────────────┼─────────────────
 Target     │  my-dhi-app:v1  
   digest   │  e8c9377134bb   
   platform │ linux/arm64     


## Policies

Policy status  FAILED  (4/9 policies met)

 Status │                    Policy                     │           Results           
────────┼───────────────────────────────────────────────┼─────────────────────────────
 ✓      │ No default root user for non-dev images       │                             
 !      │ Image contains embedded malware               │    2 deviations             
 !      │ Image contains embedded secrets               │    2 deviations             
 !      │ Image has failing tests                       │    2 deviations             
 !      │ Fixable vulnerabilities past remediation SLA  │    0C     3H     0M     1L  
 ✓      │ No high-profile vulnerabilities               │    0C     0H     0M     0L  
 ✓      │ STIG scan                                     │    0 deviations             
 !      │ Missing or unsigned supply chain attestations │    6 deviations             
 ✓      │ Unintentional shell or package manager        │    0 deviations             


## "No embedded malware" policy evaluation results
This policy checks that no malware is embedded in the image.

              Predicate              │                                            Reason                                             
─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────
 https://scout.docker.com/virus/v0.1 │ doesn't match subject sha256:e8c9377134bb24982fd0fb771881c290c9a3545ba0177b0fb5041db927991aa3 
 https://scout.docker.com/virus/v0.1 │ is missing                                                                                    


## "No embedded secrets" policy evaluation results
This policy checks that no secrets are embedded in the image.

               Predicate               │                                            Reason                                             
───────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────
 https://scout.docker.com/secrets/v0.1 │ doesn't match subject sha256:e8c9377134bb24982fd0fb771881c290c9a3545ba0177b0fb5041db927991aa3 
 https://scout.docker.com/secrets/v0.1 │ is missing                                                                                    


## "No failing tests" policy evaluation results
This policy checks that the image has tests and none are failing.

              Predicate              │                                            Reason                                             
─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────
 https://scout.docker.com/tests/v0.1 │ doesn't match subject sha256:e8c9377134bb24982fd0fb771881c290c9a3545ba0177b0fb5041db927991aa3 
 https://scout.docker.com/tests/v0.1 │ is missing                                                                                    


## "No fixable vulnerabilities past their remediation SLA" policy evaluation results
Flags packages with a fixable CVE whose remediation SLA has elapsed. SLAs vary by severity, with a shorter SLA for CISA KEV-listed vulnerabilities. Only vulnerabilities that have a fix available are considered.

    Vulnerability    │  Severity  │  Current package version   │ Fix version 
─────────────────────┼────────────┼────────────────────────────┼─────────────
 CVE-2026-57585      │    HIGH    │ pkg:pypi/msgpack@1.1.2     │ 1.2.1       
 GHSA-6v7p-g79w-8964 │    HIGH    │ pkg:pypi/msgpack@1.1.2     │ 1.2.1       
 CVE-2025-47273      │    HIGH    │ pkg:pypi/setuptools@70.3.0 │ 78.1.1      
 CVE-2026-27205      │    LOW     │ pkg:pypi/flask@3.0.3       │ 3.1.3       


## "Signed supply chain attestations" policy evaluation results
This policy checks that all required SSC attestations are available and signed by a trusted party.

            Predicate             │                                            Reason                                             
──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────
 https://slsa.dev/provenance/v0.2 │ doesn't match subject sha256:e8c9377134bb24982fd0fb771881c290c9a3545ba0177b0fb5041db927991aa3 
 https://slsa.dev/provenance/v0.2 │ doesn't resolve to image ref                                                                  
 https://slsa.dev/provenance/v0.2 │ is missing                                                                                    
 https://spdx.dev/Document        │ doesn't match subject sha256:e8c9377134bb24982fd0fb771881c290c9a3545ba0177b0fb5041db927991aa3 
 https://spdx.dev/Document        │ doesn't resolve to image ref                                                                  
 https://spdx.dev/Document        │ is missing                                                                                    


What's next:
    View vulnerabilities → docker scout cves my-dhi-app:v1
    View base image update recommendations → docker scout recommendations my-dhi-app:v1
    Compare with the latest in the registry → docker scout compare --to-latest my-dhi-app:v1

➜  dhi-lab

bash
The command pulls the policy bundle, generates an SBOM for your image, enriches it with CVE/VEX data, and checks every policy.

Typical policies in the bundle include:

Runs as non-root (for non-dev images)
No fixable critical/high CVEs past the remediation window
No high-profile / known-exploited vulnerabilities
No embedded malware or secrets
Signed supply-chain attestations present
No unintentional shell or package manager

Policy Evaluation Flow

Explanation

Scout does not just look at the base image. It analyses the full contents of your image and tells you whether it meets the same bar that Docker Hardened Images are required to meet.

Step 5 — Fix a Failing Check (Hands-on)

If the policy run reports that your image runs as root or contains an unexpected shell, go back to the multi-stage Dockerfile from Blog 2 and ensure:

Final stage uses a pure runtime variant (not -dev)
You did not accidentally add a shell or switch to USER root

Rebuild and re-run the policy command until it is clean.

Let’s Break It

Build a naïve image that starts from a normal python:3.13 and runs as root.
Run docker scout policy ... --policy-bundle dhi/policies:latest.
Observe the failures (root user, extra packages, missing attestations, etc.).
Switch the base to a DHI runtime image and rebuild — most failures disappear.

Production Thinking

In a real pipeline I would:

Always verify DHI attestations when pulling base images in CI
Run docker scout policy --policy-bundle dhi/policies:latest as a required gate
Fail the build if critical policies are not met
Keep the policy config in the repository so the whole team uses the same rules
Prefer images that already carry signed SBOMs and provenance

Security Considerations

A signed SBOM tells you what is inside; it does not magically remove vulnerabilities
VEX helps you ignore CVEs that are not exploitable in this particular image
Provenance proves the build process; it does not prove the application code is correct
Policy evaluation is only as good as the policies you enable

Common Mistakes

Forgetting the registry:// prefix when the image is already local
Expecting every attestation type on every variant (some are variant-specific)
Treating a green Scout report as “the application is secure”
Not pinning the policy-bundle digest in CI (using :latest is convenient but less reproducible)

Troubleshooting

Problem	Check / Command	Fix
`unauthorized` on attest list	`docker login dhi.io`	Re-authenticate
Attestation not found	Image name / tag / platform	Use exact tag and `--platform` if needed
Signature verification fails	Network / key	Try `--skip-tlog` if transparency log issue
Policy bundle pull fails	Docker Hub login	`docker login` (normal Hub credentials)
Too many policy failures	Base image still official	Switch final stage to a DHI runtime variant

Cleanup

docker rmi my-dhi-app:v1 2>/dev/null || true

What We Learned

Every DHI carries signed SBOMs, provenance and other attestations
You can list, retrieve and cryptographically verify them with Docker Scout
The same policy bar that Docker applies to hardened images can be applied to your own images
This gives real supply-chain transparency, not just marketing claims

You can now prove what is inside an image and enforce the same standards yourself.

What’s Next?

In Blog 4 we put everything into practice for CI/CD: proper multi-stage Dockerfiles, caching, authenticating to dhi.io in pipelines, and making the DHI policy check a required gate so every build stays clean.

References

https://docs.docker.com/dhi/how-to/verify/ — listing and verifying attestations
https://docs.docker.com/dhi/how-to/policies/ — DHI policy bundle
https://docs.docker.com/dhi/core-concepts/ — SBOM, SLSA, provenance, signatures
https://docs.docker.com/dhi/core-concepts/sbom/ — SBOM details
https://docs.docker.com/dhi/core-concepts/signatures/ — code signing

All commands and behaviour verified against current official documentation (August 2026).

Anatomy of a Hardened Image + Building Real Applications

Koti Vellanki — Mon, 17 Aug 2026 16:37:12 +0000

Docker Hardened Images Series — Blog 2

What We Are Building

By the end of this blog you will:

Inspect what is actually inside a Docker Hardened Image
Clearly understand runtime vs dev variants
See why many runtime images have no shell
Build a real small application (Python Flask) using a proper multi-stage Dockerfile on DHI bases
Run the final minimal image successfully as non-root

Why This Matters

In Blog 1 we pulled a DHI and compared size/CVEs. That showed the benefit, but it did not explain how the image is different or how to build real applications on top of it.

If you simply change FROM python:3.13 to FROM dhi.io/python:3.13 many Dockerfiles will break because:

There is often no shell
There is no package manager in the runtime variant
The container runs as a non-root user by default

This blog shows the correct, production-ready pattern.

What You Should Know Before Starting

Blog 1 completed (docker login dhi.io already done)
Basic Dockerfile knowledge
A working Docker environment

Step 1 — Inspect a Hardened Image

Pull both a runtime and a dev variant (example with Python):

docker pull dhi.io/python:3.13
docker pull dhi.io/python:3.13-dev

Output

Check the default user

docker inspect dhi.io/python:3.13 --format '{{.Config.User}}'
docker inspect dhi.io/python:3.13-dev --format '{{.Config.User}}'

Output

Runtime images usually show a non-root user (often nonroot or a numeric UID such as 65532).

Dev images often run as root so you can install packages during build.

Try to get a shell

docker run -it --rm dhi.io/python:3.13 bash
# Usually fails — no shell

docker run -it --rm dhi.io/python:3.13-dev bash
# Works — shell is present

Step 2 — Create a Simple Application

mkdir -p dhi-lab
cd dhi-lab

cat > app.py << 'EOF'
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello from a Docker Hardened Image!"

@app.route("/health")
def health():
    return {"status": "ok"}

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)
EOF

cat > requirements.txt << 'EOF'
flask==3.0.3
EOF

Step 3 — Write a Correct Multi-Stage Dockerfile

# syntax=docker/dockerfile:1

# ---------- Build stage ----------
FROM dhi.io/python:3.13-dev AS builder

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

WORKDIR /app

# Create a virtual environment and install dependencies
RUN python -m venv /app/venv
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# ---------- Runtime stage ----------
FROM dhi.io/python:3.13

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

WORKDIR /app

# Copy only what is needed
COPY --from=builder /app/venv /app/venv
COPY app.py .

EXPOSE 8000

# Runtime image already runs as non-root
CMD ["python", "app.py"]

Why this pattern works

Build stage uses the -dev image → has shell + pip
Runtime stage uses the minimal image → no shell, non-root, tiny attack surface
Only the virtual environment and application code are copied

Step 4 — Build and Run

docker build -t dhi-flask-app .
docker run --rm -p 8000:8000 dhi-flask-app

Open another terminal:

curl http://localhost:8000
curl http://localhost:8000/health

Terminal 2 Output

You should see the expected responses.

Verify the final image is minimal and non-root

docker images dhi-flask-app
docker inspect dhi-flask-app --format '{{.Config.User}}'
docker history dhi-flask-app

Output

Compare size with a naïve single-stage build if you want — the multi-stage DHI version is significantly smaller and cleaner.

What Just Happened Internally

The builder stage installed dependencies inside a virtual environment using tools that only exist in the dev variant.
The runtime stage started from a minimal hardened base that already runs as non-root.
Only the necessary files were copied across.
The final container has no package manager and no shell, so an attacker who gets code execution has far fewer tools available.

Let’s Break It

Try a single-stage Dockerfile that uses only the runtime image and tries to run pip install:

FROM dhi.io/python:3.13
COPY requirements.txt .
RUN pip install -r requirements.txt   # This will fail

It fails because there is no pip (and often no shell). That is intentional. Multi-stage is the correct solution.

Production Thinking

In real projects I always:

Use -dev (or -sdk) only in build stages
Keep the final stage as the pure runtime variant
Prefer virtual environments (Python) or equivalent so the runtime image stays clean
Explicitly set USER only if I need to override the default non-root user
Test that the application works when running as non-root (file permissions, ports > 1024)

Security Considerations

Non-root by default removes an entire class of privilege-escalation attacks
No shell and no package manager make post-exploitation much harder
The image is still only as secure as the application code and the dependencies you copy in
Always scan the final image, not just the base

Common Mistakes

Using a runtime image for the build stage → missing tools
Forgetting to copy the virtual environment or node_modules correctly
Assuming the container can bind to ports below 1024
Adding a shell “just in case” back into the runtime image
Running as root again with USER root without a strong reason

Troubleshooting

Problem	Why it happens	Fix
`pip: command not found`	Using runtime image for build	Switch build stage to `*-dev`
Permission denied writing files	Non-root user	`COPY --chown=...` or fix ownership in builder
Cannot bind to port 80	Non-root + older Docker/K8s	Use port ≥ 1024 inside the container
Image still large	Copied too much from builder	Copy only venv / binary / needed files
`exec format error`	Platform mismatch	Build with `--platform` or matching arch

Cleanup

docker rmi dhi-flask-app dhi.io/python:3.13 dhi.io/python:3.13-dev 2>/dev/null || true
rm -rf ~/dhi-lab

What We Learned

Runtime variants are intentionally minimal (no shell, non-root)
Dev variants exist precisely so you can still build software
Multi-stage Dockerfiles are the standard and recommended pattern with DHI
You can build real applications that stay small and secure

You now know how to look inside a hardened image and how to build on top of it correctly.

What’s Next?

In Blog 3 we inspect the supply-chain metadata that every DHI carries: signed SBOMs, SLSA Build Level 3 provenance, signatures and VEX data. We will also learn how to verify them and how to enforce the same standards on our own images with Docker Scout policies.

References

https://docs.docker.com/dhi/how-to/use/ — runtime vs dev, multi-stage patterns
https://docs.docker.com/dhi/explore/what/ — distroless approach and design goals
https://hub.docker.com/hardened-images/catalog — variant details and examples
https://docs.docker.com/dhi/migration/ — common migration considerations

All commands and behaviour verified against current official documentation (August 2026).

Why Images Need Hardening + Getting Started with Docker Hardened Images

Koti Vellanki — Sat, 15 Aug 2026 11:44:35 +0000

Docker Hardened Images Series — Blog 1

What We Are Building

By the end of this blog you will understand the real problem with typical container images, know what a Docker Hardened Image (DHI) actually is, authenticate to dhi.io, pull your first hardened image, run it, and compare it side-by-side with a normal official image.

You will leave with a clear “why” and a working first image.

Why This Matters

Most teams still start with official images like python:3.13 or node:22. These images are convenient, but they usually contain:

Many packages you never use
Shells, package managers and debugging tools
Known CVEs that keep appearing in scans
A larger attack surface than your application needs

When a vulnerability is disclosed, you spend time triaging, rebuilding and redeploying — often for packages that should never have been in the runtime image in the first place.

A hardened image is deliberately minimised and continuously maintained so that the number of known vulnerabilities stays near zero and the attack surface is dramatically smaller.

Docker Hardened Images (DHI) are Docker’s official implementation of this idea. The Community tier is free and open under Apache 2.0.

What You Should Know Before Starting

Basic Docker knowledge (docker pull, docker run, docker images)
A free Docker account
Docker Desktop or Docker Engine with the Scout CLI plugin (comes with Docker Desktop)

Important Distinctions (Do Not Confuse These)

Term	What it means	Automatically secure?
Small / Slim	Fewer packages, smaller size	No
Minimal	Only what is needed to run	Better, still not enough
Distroless	No shell, no package manager	Good reduction
Hardened (DHI)	Minimal + continuous CVE patching + signed SBOM + SLSA provenance + non-root by default	Closest to “secure by default”

Smaller does not automatically mean secure. Hardening is about continuous maintenance, provenance and reduced attack surface together.

Before vs After — Attack Surface

Explanation

Left side shows a typical official image full of extra tools and packages.

Right side shows a hardened image that keeps only what is required to run the application. Fewer components = fewer places for vulnerabilities.

Step 1 — See the Problem Yourself

Pull a normal official image and check its size and vulnerabilities (example with Python):

docker pull python:3.13
docker images python:3.13

Output

➜  dhi docker pull python:3.13
3.13: Pulling from library/python
018e5aeb5455: Pull complete 
fcff83b0426f: Pull complete 
6e8333d59c37: Pull complete 
50fe3346a36b: Pull complete 
cecdaccf3d35: Pull complete 
7c92d7371fba: Pull complete 
4d3df26e3af2: Pull complete 
ae85bf126208: Download complete 
1635e0a2f722: Download complete 
Digest: sha256:e16ab55c341bfd0e7da665bc2d48939cff890b43a41867fe6e1f0690638ceb7c
Status: Downloaded newer image for python:3.13
docker.io/library/python:3.13

What's next:
    View a summary of image vulnerabilities and recommendations → docker scout quickview python:3.13
➜  dhi 
➜  dhi docker images python:3.13
                                                                                                                                                                                           i Info →   U  In Use
IMAGE         ID             DISK USAGE   CONTENT SIZE   EXTRA
python:3.13   e16ab55c341b       1.62GB          420MB        
➜  dhi

If you have Docker Scout:

docker scout cves python:3.13 --platform linux/amd64

Docker scout Output
(It's too lengthy output added the main summary for getting context)

313 vulnerabilities found in 52 packages
  CRITICAL     3   
  HIGH         42  
  MEDIUM       22  
  LOW          199 
  UNSPECIFIED  47  


What's next:
    View base image update recommendations → docker scout recommendations python:3.13

➜  dhi

You will usually see a long list of CVEs and a relatively large image size. Note the numbers — we will compare them soon.

Step 2 — Browse the Hardened Images Catalog

Open the official catalog:

https://hub.docker.com/hardened-images/catalog

Search for python, node, golang, nginx, etc.

You will see variants (Debian/Alpine, runtime/dev, etc.) and security information.

Step 3 — Authenticate to dhi.io

Community images live on the dhi.io registry and require authentication (same Docker account you already have).

docker login dhi.io

Output

➜  dhi docker login dhi.io
Authenticating with existing credentials... [Username: vellankikoti]

i Info → To login with a different account, run 'docker logout' followed by 'docker login'


Login Succeeded
➜  dhi

Use your Docker Hub username and password (or a personal access token).

Step 4 — Pull and Run Your First DHI

docker pull dhi.io/python:3.13

Output

➜  dhi docker pull dhi.io/python:3.13
3.13: Pulling from python
3969c08c9319: Pull complete 
a3577369b942: Pull complete 
267158a60674: Pull complete 
26a837766441: Pull complete 
61947a7c3e2f: Pull complete 
Digest: sha256:45c7b8b9a4edeb7b41ee8dfb1e902dd37782e9d78bef53ae31d01bcb6259b7bf
Status: Downloaded newer image for dhi.io/python:3.13
dhi.io/python:3.13

What's next:
    View a summary of image vulnerabilities and recommendations → docker scout quickview dhi.io/python:3.13
➜  dhi

Run a simple command:

docker run --rm dhi.io/python:3.13 python -c "print('Hello from Docker Hardened Image')"

Output

➜  dhi docker run --rm dhi.io/python:3.13 python -c "print('Hello from Docker Hardened Image')"
Hello from Docker Hardened Image

Notice that many DHI runtime images are intentionally minimal — they may not contain a full shell or package manager. That is by design.

Check the size:

docker images dhi.io/python:3.13

➜  dhi docker images dhi.io/python:3.13         
                                                                                                                                                                                           i Info →   U  In Use
IMAGE                ID             DISK USAGE   CONTENT SIZE   EXTRA
dhi.io/python:3.13   45c7b8b9a4ed        148MB           26MB        
➜  dhi docker images python:3.13                                                           
                                                                                                                                                                                           i Info →   U  In Use
IMAGE         ID             DISK USAGE   CONTENT SIZE   EXTRA
python:3.13   e16ab55c341b       1.62GB          420MB        
➜  dhi

Step 5 — Compare Side-by-Side with Docker Scout

docker scout compare dhi.io/python:3.13 \
  --to python:3.13 \
  --platform linux/amd64 \
  --ignore-unchanged

Look at the Overview section. You will typically see:

Large reduction in image size
Many (sometimes almost all) CVEs removed
Clear difference in the number of packages

Your exact numbers will vary by tag and date, but the improvement is usually dramatic.

Comparison Flow

Explanation

Scout analyses both images and shows the concrete differences in size, packages and known vulnerabilities. This is the fastest way to see the value of a hardened image.

What Just Happened Internally

You authenticated to the dedicated DHI registry (dhi.io)
You pulled a continuously maintained, minimal image built by Docker
The image is designed to run as non-root by default
It comes with signed SBOMs, SLSA Build Level 3 provenance and VEX data (we will inspect these in later blogs)
The comparison proves the reduction in attack surface with real numbers

Let’s Break It (Gently)

Try to run an interactive shell on a minimal runtime image:

docker run -it --rm dhi.io/python:3.13 bash

Output

➜  dhi docker run -it --rm dhi.io/python:3.13 bash

What's next:
    Debug this container error with Gordon → docker ai "help me fix this container error"
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "bash": executable file not found in $PATH

Run 'docker run --help' for more information
➜  dhi

It will often fail because many runtime variants intentionally do not include a shell.

That is expected. Use a -dev variant when you need a shell for building, and keep the runtime image minimal.

Production Thinking

In a real project I would:

Start every new service with a DHI base image from day one
Use multi-stage builds (dev variant for build, runtime variant for final image)
Treat the Scout comparison as part of the PR checklist
Prefer Community tier first; move to Select/Enterprise only when I need FIPS, SLA or customisation

Security Considerations

Near-zero known CVEs is a strong starting point, but it is not a complete security programme
A hardened base image does not make insecure application code safe
Always still scan your final application image
Non-root by default removes a whole class of privilege-escalation issues
Smaller attack surface means fewer packages that can be exploited

Common Mistakes

Expecting every DHI to have a shell and package manager
Forgetting docker login dhi.io
Comparing images without specifying --platform
Thinking “I pulled a small image, so I am secure”
Putting secrets or unnecessary tools into the final runtime image

Troubleshooting

Problem	Check	Fix
`unauthorized` when pulling	`docker login dhi.io`	Log in again with Docker Hub credentials
Image has no shell	You pulled a runtime variant	Use a `-dev` variant for build stages
Scout compare fails	Scout plugin / login	Ensure Docker Desktop + logged in
Numbers look different	Tag or platform	Always pin platform and compare same tags

Cleanup

docker rmi dhi.io/python:3.13 python:3.13 2>/dev/null || true

What We Learned

Typical official images carry unnecessary packages and CVEs
Docker Hardened Images are minimal, continuously patched, non-root by default, and come with strong supply-chain metadata
Community tier is free; you only need docker login dhi.io
A simple Scout comparison immediately shows the practical benefit

You can now pull and run hardened images with confidence.

What’s Next?

In Blog 2 we look inside a hardened image (layers, distroless nature, non-root user) and start building real application images on top of DHI bases using multi-stage Dockerfiles.

References

https://docs.docker.com/dhi/ — official overview and tiers
https://docs.docker.com/dhi/get-started/ — quickstart
https://docs.docker.com/dhi/explore/what/ — what hardened images are
https://docs.docker.com/dhi/how-to/use/ — authentication and basic usage
https://hub.docker.com/hardened-images/catalog — public catalog

All commands and behaviour verified against current official documentation (August 2026).

Security Model, Troubleshooting, Limitations & Production Best Practices

Koti Vellanki — Fri, 14 Aug 2026 11:50:37 +0000

Blog 5 — Docker Sandboxes Series (Final)

What We Are Building

This final blog brings everything together.

You will:

Clearly understand the five isolation layers and the real trust boundary
Know exactly what is protected and what is still shared
Diagnose real problems with sbx diagnose and policy logs
See realistic limitations so you do not over-promise
Leave with a practical production checklist and team runbook

After this blog you should be able to introduce Docker Sandboxes to a real team with confidence and honest expectations.

Why This Matters

You now know how to launch agents, control files, network and secrets, build containers inside the sandbox, use templates, kits, ports and SSH.

The last missing piece is judgement.

An experienced engineer needs to answer:

What can still go wrong?
Where does the protection stop?
How do I debug when something fails?
When should I not use a sandbox?
How do I run this safely with a team?

This blog answers those questions with practical detail.

What You Should Know Before Starting

Blogs 1–4 completed
At least one working sandbox from previous labs

The Five Isolation Layers (Security Model)

Docker Sandboxes protect the host with five layers. The primary trust boundary is the microVM.

High-level Trust Boundary

Explanation

Everything inside the microVM is fully controlled by the agent (including sudo).

The hypervisor prevents the agent from reaching anything on the host except what you deliberately share (workspace, allowed network via proxy, injected credentials).

Layer-by-layer summary

Hypervisor isolation

Separate kernel. No shared processes or memory with the host. Removing the sandbox deletes the entire VM.
Network isolation

All HTTP/HTTPS goes through a host-side proxy that enforces deny-by-default policy.

Raw TCP, UDP and ICMP are blocked at the network layer.

Sandboxes cannot talk to each other or to host localhost.
Docker Engine isolation

Each sandbox has its own Docker daemon. There is no path to the host Docker socket.
Workspace isolation (optional but important)
- Default = direct read-write mount (agent can change your real files)
- --clone = private clone inside the VM + read-only mount of your repo (much safer)
Credential isolation

Secrets stay in the OS keychain on the host. The proxy injects them into HTTP headers. Raw values never enter the microVM.

What the agent can do inside the microVM

Install any package with sudo
Build and run any containers with its own Docker
Read/write the workspace (or the private clone)
Make network calls to domains you have allowed

What is protected

Host filesystem outside the workspace / shared skills store
Host Docker daemon
Host network and localhost
Any domain not explicitly allowed
Direct communication between sandboxes
Raw secrets

Hands-on: Controlled Breakage & Recovery

1. Confirm the isolation layers yourself

# Start a clean sandbox
sbx run --name sec-test --clone shell

# Inside the sandbox try things that should fail
ls /home          # only the agent user
docker info       # works — but it is the sandbox daemon
curl -I https://example.com   # may be blocked depending on policy

On the host:

docker images | grep -i alpine || echo "Host Docker is clean"

2. Run diagnostics

sbx diagnose

This checks CLI, daemon, storage, authentication and gives suggested fixes.

Also useful:

sbx policy ls
sbx policy log
sbx ls

3. Simulate a common failure

Intentionally block a domain the agent needs, watch it fail, then fix it:

sbx policy deny network registry.npmjs.org
# try npm install inside the sandbox → fails
sbx policy allow network "*.npmjs.org"
# try again → works

Realistic Limitations

Be honest with your team about these:

Resource overhead — each sandbox is a microVM + its own Docker daemon. Disk and memory usage grows with images and packages. Clean up regularly with sbx rm.
Direct mount risk — without --clone the agent can modify Git hooks, CI files, .env, IDE configs, etc. Always review changes.
Clone mode still reads your files — including untracked .env files. Secrets should never live in the workspace.
Non-HTTP protocols — SSH, raw TCP, UDP are blocked by default. Limited IP:port exceptions exist but are not free-for-all.
Organisation governance (paid) completely replaces local sbx policy rules. Local allow rules become inactive.
Filesystem performance — large repositories in direct mode can feel slower. Virtiofs caching helps; you can disable it if needed.
No shared Docker layers between sandboxes — each keeps its own cache.
MCP servers that run on the host are outside the microVM boundary. Treat them as trusted host integrations.

Production Best Practices & Team Runbook

Recommended defaults for a team

# Always prefer clone mode for agent work
sbx run --name feature-xyz --clone claude

# Keep network tight
sbx policy set-default balanced   # or stricter
# then add only what is needed

# Secrets only via sbx secret
sbx secret set anthropic
sbx secret set github -t "$(gh auth token)"

# Named sandboxes + clean up
sbx rm feature-xyz   # when the task is finished

Simple team runbook (copy-paste ready)

Install sbx and run sbx login + sbx setup ssh once.
Prefer --clone for any non-trivial agent session.
Use named sandboxes (--name).
Store all secrets with sbx secret.
Start from Balanced (or Locked) network policy and open only required domains.
Connect VS Code / Cursor via *.sbx when you need a full editor.
Publish ports only when you need to open a service in the browser.
When the task is done: sbx stop → sbx rm.
Weekly: sbx ls and remove anything older than a few days.
If something is broken: sbx diagnose first.

Combining with Docker Hardened Images

Inside the sandbox you can (and should) build your application images from Docker Hardened Images (dhi.io/...). The sandbox’s own Docker daemon will pull them after you have authenticated to dhi.io on the host. This gives you both strong agent isolation and secure base images.

If you haven't heard or tried Docker Hardened Images (DHI) yet, don't worry similar to Sandboxes I'll be publishing short blog series on DHI as well.

Common Mistakes (Final List)

Running agents in direct mode on important repositories without review
Leaving secrets in .env files that the agent can read
Opening network too widely (“just allow **”)
Forgetting to remove old sandboxes → disk fills up
Expecting local policy rules to work when organisation governance is active
Treating the sandbox as a full replacement for a proper CI environment

Troubleshooting Quick Reference

Symptom	First command	Typical fix
Anything strange	`sbx diagnose`	Follow the suggestions
Network blocked	`sbx policy log`	`sbx policy allow network <domain>`
Cannot connect editor	`sbx setup ssh`	Re-run setup
Disk full	`sbx ls`	`sbx rm` old sandboxes
Agent cannot authenticate	`sbx secret ls`	Re-set the secret
Slow file operations	Check if direct mount	Try `--clone` or disable virtiofs cache
Policy changes ignored	`sbx policy ls`	Check for “Managed by ”
Completely broken state	—	`sbx reset` (destructive, keeps secrets optional)

Cleanup

sbx stop sec-test 2>/dev/null || true
sbx rm sec-test 2>/dev/null || true
# Review remaining sandboxes
sbx ls

What We Learned in the Whole Series

Why microVM isolation exists and how to install/use sbx
Full control over workspace, persistence, network and secrets
Running real coding agents + isolated Docker safely
Templates, kits, ports, SSH and daily workflows
The exact security model, real limitations and how to run this in production

You now have a complete, practical Zero-to-Hero path for Docker Sandboxes.

Final Production Checklist

[ ] Everyone on the team has sbx installed and logged in
[ ] Default is --clone for agent sessions
[ ] Secrets only via sbx secret
[ ] Network policy starts restrictive
[ ] Named sandboxes + regular cleanup
[ ] VS Code / Cursor connected via SSH when needed
[ ] sbx diagnose is the first troubleshooting step
[ ] Team knows the limitations (especially direct mount and resource use)

What’s Next?

You have finished the Docker Sandboxes series.
I'll see you again with another interesting series.

References

https://docs.docker.com/ai/sandboxes/security/ — security model overview
https://docs.docker.com/ai/sandboxes/security/isolation/ — detailed isolation layers
https://docs.docker.com/ai/sandboxes/troubleshooting/ — diagnostics and common fixes
https://docs.docker.com/ai/sandboxes/governance/ — organisation governance
https://docs.docker.com/ai/sandboxes/faq/ — practical limitations and tips
https://docs.docker.com/ai/sandboxes/architecture/ — comparison with other approaches

All technical claims and commands verified against current official documentation (August 2026).

Templates, Kits, Ports, SSH Integrations & Daily Workflows

Koti Vellanki — Thu, 13 Aug 2026 05:14:44 +0000

Blog 4 — Docker Sandboxes Series

What We Are Building

By the end of this blog you will turn a one-off sandbox into a reusable, daily development environment.

You will:

Understand and use custom templates
Apply kits for extra tools, network rules and startup behaviour
Publish ports so you can open services from your browser
Connect VS Code or Cursor to the sandbox over SSH
Use the interactive TUI and practical day-to-day patterns

After this blog a sandbox should feel like a normal remote development machine — just safer.

Why This Matters

In Blog 3 we successfully ran agents and used Docker inside the sandbox. That is powerful, but repeating the same setup every time is tiring.

You want:

The same tools pre-installed for every team member
Easy access to the web app the agent just started
Your favourite editor (VS Code / Cursor) connected to the isolated environment
A clean way to start, stop and manage multiple sandboxes

Templates, kits, ports and SSH give you exactly that.

What You Should Know Before Starting

Blogs 1–3 completed
A working project (we will reuse agent-lab or create a fresh one)
VS Code or Cursor installed (optional but recommended for the SSH part)
Docker Desktop is required only if you want to build your own template image

Environment Setup

Clean previous test sandboxes:

sbx ls
sbx stop $(sbx ls -q) 2>/dev/null || true
sbx rm $(sbx ls -q) 2>/dev/null || true

➜  agent-lab git:(main) ✗ sbx ls
No sandboxes found.
Launch one: sbx run claude
➜  agent-lab git:(main) ✗

Go back to the project (or recreate it quickly):

cd agent-lab || (mkdir -p agent-lab && cd agent-lab)

I'm on agent-lab directory
Output

➜  agent-lab git:(main) ✗ pwd
/Users/koti/myFuture/writings/docker/sandboxes/agent-lab
➜  agent-lab git:(main) ✗

Step 1 — Custom Templates (Reusable Base Environments)

Official templates live under docker/sandbox-templates:<variant>.

Most agents already use the -docker variant by default (full Docker Engine inside the microVM).

You can point to any template:

sbx run --name templated --template docker.io/docker/sandbox-templates:shell-docker shell

Building your own template (optional)

If you have Docker Desktop:

# Dockerfile
FROM docker/sandbox-templates:shell-docker

USER root
RUN apt-get update && apt-get install -y \
    tree \
    jq \
    httpie \
    && rm -rf /var/lib/apt/lists/*

USER agent

Build and use it:

# build docker image
docker build -t my-dev-template:v1 .

#run the container
sbx run --name custom-template --template my-dev-template:v1 shell

This error is expected

Docker Sandboxes cannot see images that exist only in your local Docker Desktop / Docker Engine.The sbx runtime has its own separate image store. When you run the following command it tries to pull the image from a registry → gets 403 Forbidden because the image only exists locally.

sbx run --name custom-template --template my-dev-template:v1 shell

Correct way to use a locally built custom template

Follow these exact steps:

1. Save your local image as a tar file

docker image save my-dev-template:v1 -o my-dev-template.tar

2. Load it into the Sandbox runtime

sbx template load my-dev-template.tar

3. Now run the sandbox using the template

sbx run --name custom-template --template my-dev-template:v1 shell

Useful commands after loading

# See templates available to sbx in host terminal
sbx template ls

Output

➜  agent-lab git:(main) ✗ sbx template ls
REPOSITORY                           TAG                  IMAGE ID       FLAVOR               CREATED
docker.io/docker/sandbox-templates   claude-code-docker   ae8a46a10575   claude-code-docker   3 days ago
docker.io/docker/sandbox-templates   shell-docker         d86a6cdc105a   shell-docker         3 days ago
docker.io/library/my-dev-template    v1                   b403131ff1e6   shell-docker         2 minutes ago
➜  agent-lab git:(main) ✗

# Remove a template if needed
sbx template rm my-dev-template:v1

Inside the new sandbox you already have tree, jq and httpie without installing them again.

Output

agent@custom-template:agent-lab$ tree
.
|-- Dockerfile
`-- my-dev-template.tar

1 directory, 2 files
agent@custom-template:agent-lab$ jq
jq - commandline JSON processor [version 1.8.1]

Usage:  jq [options] <jq filter> [file...]
    jq [options] --args <jq filter> [strings...]
    jq [options] --jsonargs <jq filter> [JSON_TEXTS...]

jq is a tool for processing JSON inputs, applying the given filter to
its JSON text inputs and producing the filter's results as JSON on
standard output.

The simplest filter is ., which copies jq's input to its output
unmodified except for formatting. For more advanced filters see
the jq(1) manpage ("man jq") and/or https://jqlang.org/.

Example:

    $ echo '{"foo": 0}' | jq .
    {
      "foo": 0
    }

For listing the command options, use jq --help.
agent@custom-template:agent-lab$ httpie
usage: httpie [-h] [--debug] [--traceback] [--version] {cli,plugins} ...
httpie: error: Please specify one of these: 'cli', 'plugins'

This command is only for managing HTTPie plugins.
To send a request, please use the http/https commands:

  $ http POST pie.dev/post hello=world

  $ https POST pie.dev/post hello=world

agent@custom-template:agent-lab$

Template vs Kit Diagram

Explanation

A template is a Docker image — heavy things that rarely change (language runtimes, system packages, Docker itself).

A kit is applied at runtime — lighter, declarative additions (extra tools, network allow-list, startup scripts, files).

Step 2 — Kits (Declarative Extensions)

Kits are YAML files (spec.yaml). They can be local directories, Git URLs or OCI artifacts.

Simple example — create a small kit that adds a useful tool and allows a domain:

mkdir -p my-kit

cat > my-kit/spec.yaml << 'EOF'
schemaVersion: "1"
kind: mixin
name: handy-tools
description: Adds a few everyday tools and allows example.com

commands:
  startup:
    - command: ["bash", "-c", "sudo apt-get update && sudo apt-get install -y tree jq || true"]
      user: "root"

network:
  allowedDomains:
    - "example.com:443"
EOF

Run with the kit:

sbx run --name with-kit --kit my-kit shell

Inside the sandbox jq is available and example.com is reachable.

You can stack multiple kits with repeated --kit flags.

Step 3 — Publishing Ports

*This we have covered in previous blog but for the simplicity and to get familiarised I'm adding detailed section for ports here. *

Sandboxes are network-isolated by default. To open a service from your host browser you must publish a port.

Start a simple server inside a sandbox (or let the agent do it):

sbx run --name port-demo --clone shell
# inside the sandbox
python3 -m http.server 8000

From the host:

sbx ports port-demo --publish 8000
# or pin a host port
sbx ports port-demo --publish 8080:8000

Check:

sbx ports port-demo
sbx ls

Output

➜  agent-lab git:(main) ✗ sbx ports port-demo --publish 8080:8000
Published 127.0.0.1:8080 -> 8000/tcp
Published [::1]:8080 -> 8000/tcp
➜  agent-lab git:(main) ✗ 
➜  agent-lab git:(main) ✗ 
➜  agent-lab git:(main) ✗ sbx ports port-demo
HOST IP     HOST PORT   SANDBOX PORT   PROTOCOL
127.0.0.1   8080        8000           tcp
::1         8080        8000           tcp
127.0.0.1   49156       9418           tcp
127.0.0.1   49157       8000           tcp
::1         49157       8000           tcp
➜  agent-lab git:(main) ✗ sbx ls
SANDBOX     AGENT   STATUS    PORTS                                                                                                                     WORKSPACE
port-demo   shell   running   127.0.0.1:8080->8000/tcp, ::1:8080->8000/tcp, 127.0.0.1:49157->8000/tcp, ::1:49157->8000/tcp, 127.0.0.1:49156->9418/tcp   /Users/koti/myFuture/writings/docker/sandboxes/agent-lab
with-kit    shell   stopped                                                                                                                             /Users/koti/myFuture/writings/docker/sandboxes
➜  agent-lab git:(main) ✗

Open http://localhost:8080 (or the ephemeral port shown).

Unpublish when finished:

sbx ports port-demo --unpublish 8080:8000

Port Publishing Diagram

Explanation

Traffic from your browser hits a port on the host. sbx ports forwards it into the microVM. The app never needs to bind to the host network directly.

Step 4 — SSH Integration (VS Code / Cursor)

One-time setup:

sbx setup ssh

Output

➜  agent-lab git:(main) ✗ sbx setup ssh
SSH ──────────────────────────────────────────────────────
Status       ● enabled · signed in as vellankikoti
Access       *.sbx -> sandboxd.sock (no port · login-gated)

Connect ──────────────────────────────────────────────────────
Terminal     ssh <sandboxname>.sbx
File access  sftp <sandboxname>.sbx
Copy files   scp myfile.txt <sandboxname>.sbx:/path/to/workspace/

You can safely re-run sbx setup ssh to reconfigure
➜  agent-lab git:(main) ✗

This writes a managed block into your SSH config so any *.sbx host is handled by the sbx daemon.

Create or use a named sandbox:

sbx create --name editor-demo shell .
sbx run --name editor-demo

Output

Connect:

ssh editor-demo.sbx

Output

➜  agent-lab git:(main) ✗ sbx ls
SANDBOX       AGENT   STATUS    PORTS   WORKSPACE
editor-demo   shell   running           /Users/koti/myFuture/writings/docker/sandboxes/agent-lab
➜  agent-lab git:(main) ✗ 
➜  agent-lab git:(main) ✗ sbx run --name editor-demo


Starting shell agent in sandbox 'editor-demo'...
Workspace: /Users/koti/myFuture/writings/docker/sandboxes/agent-lab

agent@editor-demo:agent-lab$ ls
multi_line.txt
agent@editor-demo:agent-lab$

Try SSH to sbx

➜  agent-lab git:(main) ✗ ssh editor-demo.sbx       

Connecting to sandbox "editor-demo"…
agent@editor-demo:workspace$ 
agent@editor-demo:workspace$ pwd
/home/agent/workspace
agent@editor-demo:workspace$ cd /Users/koti/myFuture/writings/docker/sandboxes/agent-lab
agent@editor-demo:agent-lab$ ls
multi_line.txt
agent@editor-demo:agent-lab$

SSH Connection Diagram

Explanation

The editor talks to a local proxy provided by sbx. No inbound port is opened on the microVM. Authentication is tied to your Docker login. The sandbox starts automatically if it was stopped.

Step 5 — Daily Workflow Patterns & TUI

Launch the interactive dashboard:

sbx

You get a live view of all sandboxes (CPU, memory, status). From here you can create, start/stop, attach, open a shell or remove sandboxes. There is also a network panel.

Practical patterns I use every day:

Named sandboxes per feature: --name feature-login
Always prefer --clone for agent work
Publish only the ports you need
Connect the editor once and leave it attached
Clean up with sbx rm when the task is done

Multiple workspaces example:

sbx run --name multi claude ~/main-project ~/shared-libs:ro ~/docs:ro

Let’s Break It

Publish a port, open the service, then unpublish and confirm the browser can no longer reach it.
Connect VS Code, make a change, and confirm it appears both in the editor and on the host (or via the clone remote).
Apply a kit that denies a domain and watch the agent fail to reach it.

Production Thinking

In a real team I would:

Publish a small set of internal templates to a private registry
Keep common kits in the project repository (./kits/)
Document the exact sbx run ... --kit ... command in the README
Prefer SSH + editor over pure terminal for longer sessions
Use the TUI for quick overview of resource usage

Security Considerations

Templates and kits can install packages with root inside the microVM — treat them like any other code you run
Port publishing intentionally punches a controlled hole from host → sandbox
SSH access is still subject to the same network policy and workspace rules
Kits can declare their own network allow-lists; those rules are enforced

Common Mistakes

Forgetting sbx setup ssh before trying to connect an editor
Publishing ports on a stopped sandbox
Building templates without Docker Desktop
Putting secrets inside a template image instead of using sbx secret
Leaving many sandboxes with large Docker image caches

Troubleshooting

Problem	Check	Fix
`*.sbx` not resolving	`sbx setup ssh`	Re-run the setup command
Port not reachable	`sbx ports <name>`	Publish again or check the mapping
Editor cannot find folder	Absolute path inside sandbox	Use the host path that was mounted
Kit not applying	`sbx ls` / logs	Check kit path and `spec.yaml` syntax
Template pull fails	Image name	Use full `docker.io/...` reference

Useful commands:

sbx ports <name>
sbx setup ssh
ssh <name>.sbx
sbx
sbx exec -it <name> bash

Cleanup

sbx stop port-demo editor-demo with-kit custom-template 2>/dev/null || true
sbx rm port-demo editor-demo with-kit custom-template 2>/dev/null || true

What We Learned

Templates give you reusable base images with tools pre-installed
Kits add lightweight, declarative capabilities at runtime
sbx ports makes services inside the sandbox reachable from the host
SSH turns the sandbox into a first-class remote development target for VS Code and Cursor
The combination makes daily agent work feel natural and safe

You now have everything needed for comfortable, repeatable development inside sandboxes.

What’s Next?

In the final blog (Blog 5) we go deep into the security model, realistic troubleshooting, known limitations, organisation governance concepts, and production best practices so you can introduce Docker Sandboxes to a real team with confidence.

References

https://docs.docker.com/ai/sandboxes/customize/templates/ — templates
https://docs.docker.com/ai/sandboxes/customize/kits/ — kits overview and examples
https://docs.docker.com/ai/sandboxes/integrations/ — SSH, VS Code, Cursor
https://docs.docker.com/ai/sandboxes/usage/ — ports, TUI, workflows
https://docs.docker.com/reference/cli/sbx/ports/ — port command reference
https://docs.docker.com/ai/sandboxes/customize/kit-reference/ — full kit spec

All commands and behaviour verified against current official documentation (August 2026).

Running Coding Agents + Docker Inside the Sandbox

Koti Vellanki — Tue, 11 Aug 2026 13:12:37 +0000

Blog 3 — Docker Sandboxes Series

What We Are Building

By the end of this blog you will:

Launch real coding agents (Claude, Gemini, Codex, Copilot, OpenCode, Kiro, etc.) inside a sandbox
Give an agent an actual development task and watch it work safely
Use the isolated Docker daemon that lives inside every sandbox to build and run containers
Prove that nothing touches your host Docker or host system packages

This is the point where sandboxes stop being a demo and become a daily tool.

Why This Matters

In the first two blogs we built a safe environment and learned how to control files, network and secrets.

Now we put a real agent inside that environment. The agent can install packages, edit code, run tests and build Docker images — all without risk to your laptop.

The key design point is this: every sandbox comes with its own Docker daemon. The agent can run docker build, docker run and even docker compose freely. Those containers live only inside the microVM. Your host Docker stays completely untouched.

What You Should Know Before Starting

Blogs 1 and 2 completed
A free Docker account (already signed in)
At least one of the following (optional but recommended):
- Anthropic API key or Claude subscription (for claude)
- OpenAI API key (for codex)
- Google API key (for gemini)
- Or just use the shell agent if you have no keys yet

We will show both paths.

Step 1: Environment Setup

Clean any old sandboxes:

sbx ls
sbx stop $(sbx ls -q) 2>/dev/null || true
sbx rm $(sbx ls -q) 2>/dev/null || true

Create a realistic small project:

mkdir -p agent-lab
cd agent-lab

Store secrets if you have them (examples):

# Anthropic (Claude)
sbx secret set anthropic

# or OpenAI (Codex)
# sbx secret set openai

# GitHub (useful for most agents)
sbx secret set github -t "$(gh auth token)" 2>/dev/null || true

Recommended Method (Claude Subscription – Pro / Max / Team / Enterprise)

You do not need to run sbx secret set anthropic.

Exact steps:

Start Claude Code Inside the Sandbox:

   sbx run --name agent-lab --clone claude

(or whatever name/workspace you are using)
What happens:

A new microVM starts
Claude Code launches inside it
You will see the Claude Code interface

You are now inside Claude Code (running inside the sandbox).

Once Claude Code starts inside the sandbox, type this command:

   /login

Claude will open a browser window (or give you a link) for OAuth login.
Sign in with your Claude subscription account (the same one you use on claude.ai).
After successful login you will see something like:

   Login successful

You can now start chatting with Claude. The session token stays on your host and is never stored inside the sandbox.

Step 2 — Ask Claude to Create the Application

Still inside the Claude Code session, paste this prompt:

Create a simple Flask application with these files:

1. app.py – A Flask app that has two routes:
   - / → returns "Hello from Docker Sandbox!"
   - /health → returns {"status": "ok"}

2. requirements.txt – contains flask

3. Dockerfile – Use python:3.12-slim, install requirements, expose port 5000, and run the app.

Make the code clean and production-ready.

Claude will create the files for you.

Step 3 — Use Docker Inside the Sandbox

You now have two clean ways to work with Docker.

Method A: Let Claude do everything (Recommended)

Still inside Claude Code, type:

Build the Docker image, run the container on port 5000, and test both endpoints using curl.

Claude will run all the Docker commands itself.

Method B: Run Docker commands yourself (Manual control)

If you want to type the Docker commands yourself, follow these exact steps:

Keep the Claude Code terminal open (do not close it).
Open a new terminal on your host machine and run:

sbx exec -it agent-lab bash

You are now inside a normal Linux shell inside the same sandbox.

Run these commands one by one:

docker build -t agent-lab-app .
docker images
docker run -d -p 5000:5000 --name demo agent-lab-app
docker ps
curl http://localhost:5000
curl http://localhost:5000/health

When finished, type exit to leave this shell. The Claude Code session in the other terminal remains running.

Important Notes (Read Carefully)

Situation	What to do
You pressed `Ctrl + C` or `Ctrl + X` and Claude stopped	Just run `sbx run --name agent-lab` again
You want a normal shell	Use `sbx exec -it agent-lab bash`
You want Claude to do the work	Stay in the Claude Code terminal and give instructions
You want to check running containers	Use `sbx exec -it agent-lab bash` then `docker ps`

Step 4 — Publish the Port (Optional)

If you want to access the app from your host browser:

On your sandbox run app:

On your host machine run:

sbx ports agent-lab --publish 8080:5000

Then open: http://localhost:8080

Step 5 — Clean Up

When you are finished:

# On host machine
sbx stop agent-lab
sbx rm agent-lab

References

https://docs.docker.com/ai/sandboxes/agents/ — supported agents list
https://docs.docker.com/ai/sandboxes/usage/ — running, attaching, reconnecting
https://docs.docker.com/ai/sandboxes/architecture/ — isolated Docker daemon
https://docs.docker.com/ai/sandboxes/get-started/ — first agent session examples
https://docs.docker.com/reference/cli/sbx/run/ — exact CLI options
Individual agent pages under https://docs.docker.com/ai/sandboxes/agents/ (claude, gemini, etc.)

All commands and behaviour verified against current official documentation (August 2026).

Docker Sandbox Workspace, Network Policies & Secrets — Complete Practical Guide (2026)

Koti Vellanki — Mon, 10 Aug 2026 12:35:33 +0000

Blog 2 — Docker Sandboxes Series

Docker Sandbox Workspace, Network Policies & Secrets — Complete Practical Guide (2026)

What We Are Building

By the end of this blog you will fully control three critical things:

How the agent sees and changes your files (direct mount vs clone mode)
What survives when you stop a sandbox and what is deleted when you remove it
Exactly which network destinations the agent can reach, and how secrets are injected safely without ever entering the microVM

You will break things on purpose, fix them, and leave with a clean, controlled environment ready for real agents.

Why This Matters

In Blog 1 we launched a sandbox and saw basic isolation. That is not enough for real work.

If the agent can freely rewrite your entire project and can reach any website, one wrong command can still cause pain.

If secrets sit as environment variables inside the sandbox, the agent (or any code it runs) can read them.

If you do not understand what survives a stop, you will keep losing installed packages or Docker images.

This blog gives you the practical controls an experienced engineer actually uses every day.

What You Should Know Before Starting

Blog 1 completed (sbx installed and working)
A project directory (we will reuse or recreate ~/sandbox-lab)
Optional but useful: gh CLI if you want to test GitHub secrets

Environment Setup

Make sure you are in a clean state from Blog 1:

sbx ls

# If any sandbox is still running, stop and remove it
sbx stop first-sandbox 2>/dev/null || true
sbx rm first-sandbox 2>/dev/null || true

Create a fresh project:

mkdir -p sandbox-lab
cd sandbox-lab
git init
echo "hello from host - direct mode" > note.txt
git add . && git commit -m "initial"

Step 1 — Direct Mount (Default Behaviour)

Launch a normal sandbox:

sbx run --name direct-sandbox shell

Inside the sandbox:

pwd
cat note.txt
echo "changed by agent" >> note.txt
echo "new file from agent" > agent-file.txt
ls -la

Exit the sandbox (Ctrl+D or exit) or open terminal in the sandbox directory.

On the host:

ls 
cat note.txt

You see the changes immediately. This is the default direct mount.

Direct Mount Diagram

Explanation

The project folder on your host is mounted directly into the microVM at the exact same path. Any change the agent makes appears on your host instantly, and vice versa. There is no copy and no sync delay.

Step 2 — Clone Mode (Safer Isolation for Files)

Remove the previous sandbox:

sbx stop direct-sandbox
sbx rm direct-sandbox

Now create one with --clone:

sbx run --name clone-sandbox --clone shell

Inside the sandbox:

pwd
ls -la
cat note.txt
echo "this change stays inside the clone" >> note.txt
git status

On the host:

cat note.txt
# The host file is unchanged

The agent is working on a private Git clone inside the microVM. Your original files are mounted read-only.

Clone Mode Diagram

Explanation

Start from the host repository (mounted read-only). The sandbox creates its own private clone. The agent edits only that clone. When you want the changes, you fetch from the special remote sandbox-<name> that Docker automatically adds on the host. Removing the sandbox deletes the private clone.

Important: --clone can only be set at creation time. You cannot switch an existing sandbox later.

Step 3 — Persistence: What Survives Stop vs Remove

Inside any running sandbox install something:

# still inside clone-sandbox or start a new one
apt-get update && apt-get install -y tree

#if command fails due to root privileges use then use the following command

sudo apt-get update && sudo apt-get install -y tree

docker pull alpine:latest

Stop it (state is kept):

# from host
sbx ls
sbx stop clone-sandbox
sbx ls

Start it again:

sbx run --name clone-sandbox

Inside:

tree --version
docker images

Everything is still there.

Now remove it completely:

sbx stop clone-sandbox
sbx rm clone-sandbox

If you recreate a sandbox with the same name, the packages and images are gone. That is expected.

Lifecycle Diagram

Explanation

stop pauses the microVM but keeps the disk state (packages, images, agent history).

rm deletes the entire microVM and everything inside it. Host project files are never touched.

Step 4 — Network Policies

List current rules:

sbx policy ls

You will see the Balanced preset rules (or whatever you chose earlier).

Allow a specific host:

sbx policy allow network docker.com

Deny something:

sbx policy deny network docs.docker.com

Test from inside a sandbox:

sbx run --name net-test shell
# inside
curl -I https://docker.com
curl -I https://docs.docker.com   # should fail if denied

Rules apply immediately. Deny always wins over allow.

You can scope a rule to one sandbox with --sandbox <name> or keep it global (default).

Network Flow Diagram

Explanation

Every outbound HTTP/HTTPS request from the sandbox goes through a proxy that lives on your host. The proxy checks the policy rules. Non-HTTP traffic (raw TCP, UDP, ICMP) is blocked at the network layer and cannot be opened with normal policy rules (except limited IP:port cases).

Step 5 — Secrets (The Safe Way)

Never put real tokens as normal environment variables inside the sandbox.

Store a secret on the host:

# Example with GitHub (if you have gh CLI)
sbx secret set github -t "$(gh auth token)"

![sbx github secret](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/95mykhlfukxre589fo7r.png)


# Or interactively
sbx secret set anthropic

The value is stored in your OS keychain. When the agent makes an HTTP request that needs it, the host-side proxy injects the credential. The raw secret never enters the microVM.

Verify from the host:

sbx secret ls

Credential Injection Diagram

Explanation

The agent only sees a normal HTTP request. The proxy quietly adds the authentication header using the secret stored on the host. Even if the agent is compromised, it cannot read the real token.

Let’s Break It

Start a sandbox with Locked Down style policy and try to reach a package registry → it fails.
Allow the host → it works.
Put a fake secret with sbx secret set and confirm the agent can use the service without the value appearing in env inside the sandbox.

Production Thinking

In a real project I would:

Prefer --clone when the agent is experimental or when multiple agents run on the same repo
Keep network policy as restrictive as possible (start from Balanced or stricter)
Always use sbx secret for any token
Name sandboxes clearly and remove them when the task is finished
Document the exact sbx policy allow list the team needs

Security Considerations

Direct mount = agent can rewrite your working tree
Clone mode = safer file isolation, but you must fetch the work later
Secrets injected by proxy are the only safe method
Network is deny-by-default; anything not explicitly allowed is blocked
Organisation policies (if your company enables them) override local rules completely

Common Mistakes

Forgetting --clone is create-time only
Expecting stop to free disk space (only rm does)
Putting secrets in .env files inside the sandbox
Adding too many global allow rules and wondering why isolation feels weak
Not checking sbx policy ls after changing rules

Troubleshooting

Problem	How to confirm	Fix
Changes not appearing on host	Are you in clone mode?	Fetch from `sandbox-<name>` remote
Network still blocked	`sbx policy ls`	Add allow rule or check deny precedence
Secret not working	`sbx secret ls`	Re-set the secret; restart sandbox
Disk full	Many old sandboxes	`sbx ls` then `sbx rm` unused ones
Policy not applying	Org governance active?	Local rules are ignored

Useful commands:

sbx policy ls
sbx secret ls
sbx diagnose

Cleanup

sbx stop net-test clone-sandbox 2>/dev/null || true
sbx rm net-test clone-sandbox 2>/dev/null || true
sbx policy ls          # review and clean rules if needed
# Optional full reset of policies (careful)
# sbx policy reset

What We Learned

Direct mount is convenient but gives the agent write access to your real files
Clone mode keeps your working tree safe and is the better default for experimental work
stop keeps state, rm destroys it
Network is fully controllable with sbx policy
Secrets never need to enter the microVM — the proxy injects them

You now have complete control over the three things that matter most for safe daily use.

What’s Next?

In Blog 3 we put everything together: launch real coding agents (Claude, Gemini, Codex, etc.), give them actual development tasks, and use the isolated Docker daemon that lives inside every sandbox to build and run containers safely.

References

https://docs.docker.com/ai/sandboxes/usage/ — workspace and clone mode details
https://docs.docker.com/ai/sandboxes/architecture/ — mounting, persistence, networking
https://docs.docker.com/ai/sandboxes/security/ — isolation layers and credential model
https://docs.docker.com/ai/sandboxes/security/credentials/ — sbx secret behaviour
https://docs.docker.com/ai/sandboxes/governance/access-controls/local/ — policy commands and presets
https://docs.docker.com/reference/cli/sbx/policy/ and related pages — exact CLI syntax

All commands and behaviour verified against current official documentation (August 2026).

Docker Sandboxes from Zero to Production: The Complete Hands-on Guide (2026)

Koti Vellanki — Sun, 09 Aug 2026 18:34:54 +0000

Blog 1 — Docker Sandboxes Series

Docker Sandboxes from Zero — Why They Exist, Setup, First Sandbox & Basic Isolation

What We Are Building

By the end of this blog you will understand why AI coding agents are risky on a normal laptop, install the sbx CLI, launch your first isolated sandbox, see the isolation boundary with your own eyes, and clean everything up properly.

No paid AI subscription is required. We use the shell agent.

Why This Matters

AI coding agents are useful because they act on their own. They install packages, edit files, run tests, build Docker images, and sometimes run commands you would never type yourself.

If you run them directly on your machine they can:

Change or delete files outside the project
Install system packages that break your setup
Talk to your host Docker daemon
Reach any network destination
Accidentally expose credentials already present in your environment

Normal containers share the host kernel. Mounting the Docker socket gives the agent the same power as you. Full virtual machines are heavy and slow to start.

Docker Sandboxes solve this by giving each agent its own lightweight microVM.

Before vs After — The Core Problem

Explanation of the diagram

Left side shows the dangerous default: the agent runs with the same power as you on the host.

Right side shows the sandbox approach: the agent is locked inside a microVM. Only the project folder is shared. Everything else stays isolated.

What You Should Know Before Starting

Comfortable with a terminal
Free Docker account
Supported platform:
- macOS
- Windows 11 with Windows Hypervisor Platform enabled
- Ubuntu 24.04+ with KVM working

Docker Desktop is not required. (No blocker for corporates...)

Environment Setup

Install the sbx CLI

macOS

brew trust docker/tap
brew install docker/tap/sbx

Ubuntu / Linux

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sudo usermod -aG kvm $USER
newgrp kvm

Windows

winget install -h Docker.sbx

Verify:

sbx version

Sign in

sbx login

Step 1 — Create a Simple Project

mkdir -p ~/sandbox-lab
cd ~/sandbox-lab
echo "hello from the host" > note.txt

Step 2 — Launch the First Sandbox

sbx run --name first-sandbox shell

On the first run choose the Balanced network preset (recommended).

You are now inside a Bash shell that lives inside the microVM.

Step 3 — Look Around Inside the Sandbox

pwd
ls -la
cat note.txt
whoami
docker version

Open a second terminal on the host:

sbx ls

High-level Sandbox Architecture (what you just created)

Explanation of the diagram

You talk to the sbx CLI. The CLI starts a microVM. Inside that microVM the agent, its Docker daemon and its filesystem live. The only connection back to the host is the workspace folder you chose.

Step 4 — Prove the Isolation

Inside the sandbox:

echo "written from inside the sandbox" >> note.txt
echo "created inside sandbox" > from-sandbox.txt
docker pull alpine:latest
docker images

On the host:

cat ~/sandbox-lab/note.txt
ls ~/sandbox-lab
docker images | grep alpine || echo "alpine image is NOT on the host"

Note: Ideally you should see message alpine image is NOT on the host as output but as I'm using postgres alpine image for another application it showed up but you can observe this alpine images is not what we pulled in the sandbox.

Isolation Boundary Diagram

Explanation of the diagram

Files in the project folder move both ways (live mount).

The sandbox Docker daemon has no path to the host Docker daemon. Images and containers stay inside the microVM.

What Just Happened Internally

The microVM has its own kernel. The agent has full power inside the microVM (including sudo). Network traffic goes through a host-side proxy that enforces the policy you chose. Credentials (when we use them later) are injected by the proxy and never stored inside the VM.

Let’s Break It (Gently)

Inside the sandbox try:

curl -I https://koti.dev

If it is blocked under Balanced policy, that is expected.

On the host allow it:

sbx policy allow network koti.dev

Retry. It should now work.

Production Thinking

In real work I always:

Start with Balanced or stricter
Give every sandbox a clear name
Prefer --clone for experimental or untrusted agent work
Treat sbx rm as the normal way to finish a session

Security Considerations

The agent is powerful inside the sandbox. Do not treat it like a normal restricted container.
The workspace is read-write by default.
Never put long-lived secrets as normal environment variables inside the sandbox (we cover the proper way in the next blog).

Common Mistakes

Forgetting the kvm group on Linux → sandbox will not start
Skipping sbx login
Expecting host Docker to see images built inside the sandbox
Leaving many sandboxes running → disk fills up

Troubleshooting

Problem	Quick check	Fix
`sbx` not found	Installation	Re-run install steps
KVM error on Linux	`lsmod \	grep kvm`
Sandbox stuck	`sbx ls`	`sbx stop` then `sbx rm`
Need clean state	—	`sbx reset` (destructive)

Also useful:

sbx diagnose

Cleanup

sbx stop first-sandbox
sbx rm first-sandbox
sbx ls

Your ~/sandbox-lab folder remains. Only the microVM is gone.

What We Learned

AI agents need strong isolation. MicroVMs give that isolation without the weight of full VMs.
The sbx CLI is the current free way to use Docker Sandboxes.
Workspace is shared; almost everything else stays inside the sandbox.
You can now install, launch, inspect and cleanly remove a sandbox.

What’s Next?

In Blog 2 we take full control of the environment: how files persist, the difference between direct mount and clone mode, network policies in depth, and the safe way to inject secrets so the agent never sees the real values.

References

https://docs.docker.com/ai/sandboxes/ — official overview
https://docs.docker.com/ai/sandboxes/get-started/ — installation and first run
https://docs.docker.com/ai/sandboxes/architecture/ — microVM and isolation details
https://docs.docker.com/reference/cli/sbx/ — command reference

All commands and behaviour verified against current official documentation (August 2026).

Why I Broke Kubernetes Cluster 35 Times? I did it So You Don't Have To

Koti Vellanki — Tue, 07 Apr 2026 14:51:21 +0000

The Problem With Learning Kubernetes

Everyone tells you to "learn Kubernetes"

So you read the docs. You watch YouTube. You follow a tutorial that deploys nginx. You feel great.

After a cheerful weekend, you logged in Monday morning. A pod is stuck in CrashLoopBackOff. You stare at the terminal. You Google or ask any GPT models. You paste random commands. Thirty minutes later, you're still stuck.

Sound familiar?

Here's the thing: you don't really understand Kubernetes until something breaks.

And the best way to learn troubleshooting is to break things on purpose, in a safe environment, where you can take your time and actually understand what went wrong.

That's exactly why I built this.

Introducing: Troubleshoot Kubernetes Like a Pro

GitHub: https://github.com/vellankikoti/troubleshoot-kubernetes-like-a-pro

It's a free, open-source collection of 35 real-world Kubernetes failure scenarios that you can simulate, investigate, and fix on your own cluster.

No custom Docker images. No complex setup. No cloud account required. Just a local Kubernetes cluster (Minikube, Kind, or Docker Desktop) and kubectl.

How It Works

Every scenario follows the same simple pattern:

1. Break it

kubectl apply -f issue.yaml

This creates a deliberately broken Kubernetes resource. A pod that crashes. A service that points to nothing. A container that runs out of memory.

2. Investigate it

kubectl get pods
kubectl describe pod <pod-name>
kubectl logs <pod-name>

Just like you would in production. No hints. No hand-holding. You figure it out.

3. Fix it

kubectl apply -f fix.yaml

The fix resolves the issue. You can compare the two YAML files to see exactly what changed and why.

4. Understand it

Every scenario includes a description.md that explains:

What the issue is
What causes it in the real world
How to identify it
How to fix it

The 35 Scenarios

Here's what's inside, organized by category:

Scheduling Failures (Pod stuck in Pending)

Scenario	What Happens
Affinity Rules Violation	Pod requires a node label that doesn't exist
Node Affinity Issue	Pod targets a non-existent node
Insufficient Resources	Pod requests more CPU/memory than available
Taints and Tolerations Mismatch	Pod can't schedule due to node selector
Cluster Autoscaler Issues	Too many replicas for the cluster to handle

Container Crashes

Scenario	What Happens
CrashLoopBackOff	Container exits immediately with error
OOM Killed	Container exceeds memory limit, killed by cgroup
Wrong Container Command	Invalid command in container spec
CGroup Issues	Memory stress exceeds cgroup limits
Failed Resource Limits	Workload exceeds restrictive resource limits

Image Problems

Scenario	What Happens
Image Pull BackOff	Non-existent image
Image Pull Error	Private registry image without credentials

Probe Failures

Scenario	What Happens
Liveness Probe Failure	Probe hits wrong endpoint, container keeps restarting
Readiness Probe Failure	Probe fails, pod shows 0/1 Ready
Liveness & Readiness Failure	Both probes misconfigured

Storage Issues

Scenario	What Happens
Volume Mount Issue	Pod references a volume that doesn't exist
Persistent Volume Claim Issues	PVC can't bind to any PV
Disk IO Errors	HostPath points to non-existent directory
File Permissions on Mounted Volumes	Read-only filesystem blocks writes
Crash Due to Insufficient Disk Space	Ephemeral storage limit exceeded

Networking Issues

Scenario	What Happens
DNS Resolution Failure	Custom DNS config points to invalid nameserver
Firewall Restriction	NetworkPolicy blocks all egress
Network Connectivity Issues	NetworkPolicy blocks pod traffic
Service Port Mismatch	Service port doesn't match container port
Ingress Configuration Issue	Ingress points to wrong host
LoadBalancer Misconfiguration	Service selector doesn't match any pods
Port Binding Issues	Container port conflict

Security & RBAC

Scenario	What Happens
Service Account Permissions	Pod references non-existent ServiceAccount
Security Context Issues	Running as root vs non-root (best practice)
SELinux/AppArmor Policy Violation	Security policy configuration
PID Namespace Collision	Host PID namespace shared (security risk)

Other

Scenario	What Happens
Container Runtime (CRI) Errors	RuntimeClass with non-existent handler
Resource Requests & Limits Mismatch	CPU limit less than request (API rejection)
Pod Disruption Budget Violations	PDB blocks voluntary disruptions
Outdated Kubernetes Version	Educational scenario about version management

Quick Start (5 Minutes)

Option 1: Use the interactive script

git clone https://github.com/vellankikoti/troubleshoot-kubernetes-like-a-pro.git
cd troubleshoot-kubernetes-like-a-pro
./manage-scenarios.sh

Pick a scenario number. The script handles everything - creates the issue, lets you investigate, then applies the fix.

Option 2: Run scenarios manually

cd scenarios/crashloopbackoff

# Create the problem
kubectl apply -f issue.yaml

# Investigate
kubectl get pods
kubectl describe pod crashloopbackoff-pod
kubectl logs crashloopbackoff-pod

# Fix it
kubectl delete -f issue.yaml
kubectl apply -f fix.yaml

# Verify
kubectl get pods

What You'll Actually Learn

After working through these scenarios, you'll be able to:

Read pod status and know exactly what's wrong - Pending means scheduling, CrashLoopBackOff means the app is failing, ImagePullBackOff means the image is wrong.
Use kubectl describe like a pro - The Events section at the bottom tells you everything. Failed scheduling, failed mounts, failed pulls, probe failures - it's all there.
Understand resource management - Requests vs limits, ephemeral storage, cgroup OOM kills, and why your pod got evicted.
Debug networking issues - DNS resolution, NetworkPolicy, service selectors, port mismatches, and ingress configuration.
Handle security configurations - ServiceAccounts, security contexts, PID namespaces, and runtime classes.

Who Is This For?

Beginners who just finished a Kubernetes tutorial and want real practice
Developers who deploy to Kubernetes but panic when something breaks
DevOps engineers preparing for CKA/CKAD certification
SREs who want to sharpen their troubleshooting instincts
Teams who want to run Kubernetes troubleshooting workshops

A Note on Two Scenario Types

30 scenarios produce hard failures - you'll see Pending, CrashLoopBackOff, OOMKilled, Error, or ImagePullBackOff. These are obvious and satisfying to fix.

3 scenarios are educational - Security Context, SELinux, and Outdated K8s Version. Both the issue and fix pods run successfully. The learning is in understanding the security implications of the configuration difference.

2 scenarios require a CNI with NetworkPolicy support (like Calico or Cilium) to fully demonstrate blocked traffic.

Try It Today

git clone https://github.com/vellankikoti/troubleshoot-kubernetes-like-a-pro.git
cd troubleshoot-kubernetes-like-a-pro
./manage-scenarios.sh

Star the repo if it helps you: https://github.com/vellankikoti/troubleshoot-kubernetes-like-a-pro

Share it with someone who's learning Kubernetes. The best way to learn is to break things safely.

Built and maintained by Koti Vellanki. Contributions welcome!

How I Automated GitHub Repos, Branches & PRs Using Claude AI and Docker Desktop MCP

Koti Vellanki — Sat, 17 May 2025 22:07:19 +0000

🚀 Introduction

In this guide, I’ll walk you through how I used Docker Desktop, the MCP Toolkit extension, and Claude Desktop to connect to GitHub and automate tasks like:

Creating a repository
Adding multiple branches
Opening a pull request — all via simple prompts to Claude

We’ll set up everything step-by-step so you can follow this like a playbook and get the same results.

✅ Prerequisites

Before we begin, make sure you have the following installed:

Docker Desktop
Claude Desktop
A GitHub Personal Access Token (PAT) with repo and user access
Internet connectivity

🛠️ Step-by-Step Guide

🔹 Step 1: Open Docker Desktop and Navigate to Extensions

Launch Docker Desktop
Click on the "Add Extensions" tab

🔹 Step 2: Install MCP Toolkit Extension

Search for “MCP Toolkit”
Click Install
Wait until installation is complete and launch the extension

🔹 Step 3: Enable GitHub as MCP Server

Inside MCP Toolkit, Search for GitHub under MCP Servers and select the official MCP Server
Paste your GitHub Personal Access Token If you don't have the GitHub PAT ready go to Account Settings --> Developer Settings - Create Token and paste it in the github.personal_access_token

This enables Docker to act as an MCP Server that communicates securely with GitHub.

🔹 Step 4: Launch Claude Desktop and Configure MCP Client

Open Claude Desktop settings or config file
Copy the MCP Client config instructions shown in Docker MCP extension
Paste them into Claude’s config
Restart Claude Desktop

Now Claude is linked to the GitHub MCP server and ready to take commands.

🔹 Step 5: Create a GitHub Repository Using Claude

Open Claude’s interface and type:

create a repo called yt-demo-github-mcp in my github account

✅ You’ll see a confirmation from Claude that the repository is created.

🔹 Step 6: Create Multiple Branches

Prompt:

can you create 3 branches dev, qe, prod and list all the available branches?

✅ Claude will confirm branch creation.

🔹 Step 7: Open a Pull Request

Prompt:

can you create a file called tes.py with hello worls code in Python and raise Pull request from Dev to QE, QE to Prod and Prod to main?

✅ Claude opens the PR instantly, no GitHub UI involved.

💡 What Else Can You Do?

The GitHub MCP Server supports over 48 different GitHub features — from repository settings to contributor roles, issues, PR reviews, and more.

👉 You can explore all supported features here:
📖 GitHub MCP Official Documentation

🔗 References

🎯 Wrapping Up

You just saw how easy it is to:

Set up Docker MCP and Claude Desktop
Connect to GitHub
Automate key GitHub tasks with natural language

This guide is part of my Docker Series, where I’ll continue sharing hands-on, real-world use cases to help you get the most out of Docker tools and extensions.