Getting Started with Claude CLI in Docker Containers

Running Claude CLI inside a Docker container gives you a reproducible, isolated environment for AI-powered tasks. This guide walks through the setup process, from base image to a fully configured container that can execute workflows without interactive prompts.

Choosing a Base Image

Start with node:22-slim if your workflows involve JavaScript or Node.js tooling. This image is lightweight but missing a few dependencies that the Claude CLI installer requires. You will need to add bash, curl, and ca-certificates before installing.

FROM node:22-slim

RUN apt-get update && apt-get install -y \
    bash curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

Installing Claude CLI

The recommended installation method is the official install script. Do not use npm — the install script handles binary placement and platform detection automatically.

RUN curl -fsSL https://claude.ai/install.sh | bash

This places the claude binary in ~/.local/bin/. If your container runs as a different user (for example, the node user in Node.js images), you need to copy the binary into that user’s path:

USER node
RUN mkdir -p /home/node/.local/bin && \
    cp /root/.local/bin/claude /home/node/.local/bin/claude
ENV PATH="/home/node/.local/bin:$PATH"

Do not rely on symlinks here — they often fail with permission errors. And avoid placing the binary only in /usr/local/bin, because the CLI uses its own install path for self-updates and configuration resolution.

Skipping Interactive Prompts

Claude CLI has several first-run prompts: onboarding, tool permissions, and workspace trust. In a container environment, you need to pre-create configuration files to bypass all of these.

Set the CLAUDE_CONFIG_DIR environment variable to an isolated directory:

ENV CLAUDE_CONFIG_DIR="/home/node/.config/claude"

Then create these files before the first run:

.credentials.json — Your OAuth credentials for authentication.

.claude.json — Must include hasCompletedOnboarding: true and a numStarts value greater than 1 to skip the welcome flow.

settings.json — Include permissions.allow: ['*'] to pre-approve all tool permissions. Only do this in isolated container environments where you control the execution context.

projects/<encoded-workdir>/settings.local.json — Set isTrusted: true to skip the workspace trust prompt. The directory name is your working directory path with / replaced by -.

Running a Workflow

With everything configured, you can run Claude CLI in non-interactive mode:

claude --dangerously-skip-permissions -p "Your prompt here"

For longer workflows, pipe in a workflow file:

claude --dangerously-skip-permissions -p "$(cat workflow.md)"

Networking and Resource Limits

In production, consider these Docker run flags:

• --network=none: Disable network access if your workflow does not need it.
• --memory=2g: Cap memory usage to prevent runaway processes.
• --cpus=1: Limit CPU to keep costs predictable on shared infrastructure.

Debugging Tips

If the CLI hangs on startup, check that all config files are valid JSON and that CLAUDE_CONFIG_DIR points to the right location. If tools fail with permission errors, verify that the running user owns the config directory and its contents.

Running Claude CLI in Docker is the foundation of FlowKoi’s execution model. Every workflow runs in a fresh container, ensuring clean state, security isolation, and reproducible results.