← All Posts

How to Do Docker Container Creation on Claude Code

Claude Code can create Docker containers end-to-end by generating Dockerfiles, docker-compose.yml configs, and running docker build/docker run commands directly in your terminal. It is ideal for developers who want to containerize an app without switching to documentation tabs. The main trade-off: complex multi-stage builds require precise prompting, and Claude Code will consume tokens on every iteration. Monitor usage carefully during long containerization sessions.

  • Claude Code executes shell commands natively, so docker build, docker run, and docker compose up all work inline.
  • Generating a production-ready Dockerfile from a natural language description typically takes 1-3 prompt iterations.
  • You can use /usage in Claude Code or check Usagebar to track token consumption before a heavy containerization session hits a usage ceiling.

What is Docker container creation in Claude Code?

Claude Code is Anthropic's agentic CLI tool that runs in your terminal and can read files, execute commands, and write code. Docker container creation inside Claude Code means you are asking the agent to:

  • Write a Dockerfile tailored to your project's runtime and dependencies
  • Generate a docker-compose.yml for multi-service stacks
  • Run docker build and docker run commands on your behalf
  • Iterate on the container config when a build fails, reading error output automatically

Because Claude Code has direct bash access, the entire loop of write, build, fail, fix happens in one session without you copying errors into a chat window. This is one of the strongest use cases for the agent's agentic shell execution capability, available on Claude Pro and Max plans.

How to create a Docker container with Claude Code step by step

1. Start Claude Code in your project root

Open your terminal, navigate to your project directory, and launch Claude Code:

claude

Claude Code will index your project files. This gives it the context it needs to pick the right base image and copy the correct source paths.

2. Describe the container you need

Give Claude a direct, specific prompt. The more runtime details you include, the fewer iterations you need:

Create a production Dockerfile for this Node.js 20 app. Use a multi-stage build, install only production dependencies in the final stage, expose port 3000, and run as a non-root user.

Claude will read your package.json, infer the entry point, and write the Dockerfile to disk immediately.

3. Ask for a docker-compose file if needed

For apps with a database or cache layer, follow up with:

Add a docker-compose.yml that brings up this app alongside a PostgreSQL 16 container with a persistent volume.

Claude Code will write both files and can also run docker compose up --build right away to verify everything starts cleanly. For related database work, see how to do PostgreSQL migrations on Claude Code.

4. Let Claude fix build errors automatically

If docker build fails, Claude reads the error output and proposes a fix without you doing anything. Just confirm and it re-runs the build. Common fixes include missing apt-get dependencies, wrong WORKDIR paths, and incorrect COPY directives.

5. Run and validate the container

Once the build succeeds, ask Claude to start the container and confirm the app is responding:

Run the container on port 3000 and curl localhost:3000 to verify it returns a 200.

Claude executes the docker run command and the health check in sequence, reporting back the result.

Useful prompts for Docker work in Claude Code

These prompts cover the most common container creation scenarios:

  • Multi-stage builds: "Write a multi-stage Dockerfile for this Go binary. The build stage should use golang:1.22 and the final stage should be scratch."
  • Environment variables: "Add an .env.example file and wire those variables into the Dockerfile with ARG and ENV instructions."
  • Health checks: "Add a HEALTHCHECK instruction that pings /health every 30 seconds."
  • Image size audit: "Analyze the current Dockerfile and suggest changes to reduce the final image size."
  • Compose networking: "Update the compose file so the app container can reach the Redis container by hostname."
  • Cleanup: "Run docker system prune to remove unused images and volumes after the build."

For a broader list of what you can prompt, see best Claude Code commands for developers.

How to use slash commands during Docker sessions

Claude Code's slash commands are especially useful during iterative container work:

  • /usage shows your current token consumption for the session. Docker build iterations are token-heavy; check this before starting a long containerization task so you are not cut off mid-build.
  • /clear resets the conversation context. Use it between unrelated Docker tasks to keep prompts focused and reduce token use.
  • /help lists all available commands if you need a quick reference.

You can also reduce Claude Code token usage during Docker sessions by keeping prompts specific and using /clear aggressively between tasks.

Monitor usage so a Docker session doesn't get cut off

Docker container creation is one of those tasks where you really do not want a surprise lockout. A typical workflow involving a Dockerfile, a compose file, a few failed builds, and a final validation run can burn through a meaningful slice of your hourly token budget. Getting cut off with a broken container mid-session means either waiting up to 5 hours for the window to reset or losing your flow entirely.

Usagebar sits in your macOS menu bar and shows your Claude Code usage at a glance, with smart alerts at 50%, 75%, and 90% of your limit. You see the number without switching windows. Credentials are stored in macOS Keychain. Pricing is pay-what-you-want, with a free tier for students.

You can also check usage natively via the /usage command in Claude Code or at claude.ai/settings/usage, but neither gives you proactive warnings before you hit the wall. To understand exactly when your window resets, see when does Claude Code usage reset.

Get Usagebar for an instant download and stay in flow through your next Docker session.

Key takeaways

  1. Start Claude Code in your project root so it reads your existing files before generating a Dockerfile.
  2. Include runtime version, port, and non-root user requirements in your first prompt to minimize iterations.
  3. Use follow-up prompts to add docker-compose, health checks, and environment variable wiring without restarting the session.
  4. Let Claude read build errors and self-correct. You rarely need to paste errors manually.
  5. Run /usage or check Usagebar before starting a heavy containerization session to make sure you have enough headroom.
  6. Use /clear between unrelated Docker tasks to keep context lean and token usage low.

Sources

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar