n8500x/claude-code

claude-code (Bedrock)

The https://docs.anthropic.com/en/docs/claude-code agentic CLI, containerized to run against AWS Bedrock — either directly (SigV4) or through an on-prem gateway that fronts Bedrock with OAuth2 auth. Ships with a Java + Python build toolchain and an autonomous agentic-loop mode.

The docs are baked into the image. Run docker run --rm n8500x/claude-code help for a cheat sheet, or docs for this full document — no credentials needed.

Jump to: Quick reference · Gateway auth (SSO) · Air-gapped · Jenkins · Troubleshooting

Overview

Anthropic's official @anthropic-ai/claude-code CLI in a slim Node runtime. Defaults to Bedrock (CLAUDE_CODE_USE_BEDROCK=1); set gateway vars to use your on-prem gateway instead (Anthropic- or OpenAI-shaped). Entrypoint launches the TUI in /workspace; -p "..." for headless, loop for autonomous. Telemetry/updater off by default — suits air-gapped networks.

Quick reference

The image is self-documenting — help (cheat sheet) and docs (this file) run with no credentials:

bash
docker run --rm n8500x/claude-code help
docker run --rm n8500x/claude-code docs

Podman works too — it's a drop-in for docker; use podman run … in place of docker run … in every example below.

Clone a private repo over SSH (and use its skills)

Inject an SSH key and optionally auto-clone a repo into /workspace — to pull code to review and pick up the repo's Claude skills (.claude/skills/, auto-discovered):

bash
docker run --rm \
  -e GIT_SSH_KEY_FILE=/keys/id -v ~/.ssh/id_ed25519:/keys/id:ro \
  -e CLONE_REPO='git@github.com:org/repo.git' \
  -v "$PWD:/workspace" [AUTH ENV…] \
  n8500x/claude-code -p "review this repo"

Key via GIT_SSH_KEY (raw), GIT_SSH_KEY_B64, or GIT_SSH_KEY_FILE; host keys via GIT_SSH_KNOWN_HOSTS[_FILE] / GIT_SSH_STRICT (default accept-new). Clone lands in /workspace (or CLONE_DIR), the entrypoint cds in so the repo's .claude/skills/ are active; CLONE_REF/CLONE_DEPTH set branch/shallow.

Quick start

docker pull n8500x/claude-code, then copy a complete command from Recipes. Interactive TUI needs -it; -p "…" runs headless; add -e AWS_PROFILE=… -v "$HOME/.aws:/home/claude/.aws:ro" for a named AWS profile.

Autonomous agentic loop

The loop subcommand runs Claude Code autonomously — headless, permissions bypassed — re-engaging the same session each iteration until the goal is verified done or a cap is hit. No TTY needed, so it suits CI / batch use. Same env as above (Bedrock or gateway), plus:

bash
docker run --rm -v "$PWD:/workspace" [AUTH ENV…] \
  n8500x/claude-code loop "make ./gradlew test pass"

The task can also come from -e CLAUDE_TASK="..." or a /workspace/TASK.md file. CLAUDE_LOOP=1 turns any invocation into a loop.

How it stops. Each iteration runs claude -p --output-format json --dangerously-skip-permissions resuming a fixed session id, so context carries over. An appended system prompt makes it emit CLAUDE_TASK_COMPLETE only when verified done. Ends on: sentinel (0), CLAUDE_LOOP_MAX_ITERS (4), budget (3), errors (1), or /workspace/.claude-stop. JSON logs in /workspace/.claude-loop/. It edits unattended — only use repos you trust.

What's inside

• Base image: node:20-slim (Node.js 20; Claude Code needs Node 18+).
• Agent: @anthropic-ai/claude-code via npm (CLAUDE_CODE_VERSION, pinned 2.1.220) as claude.
• System tools: git, ripgrep (Claude Code's search backend), openssh-client, unzip, ca-certificates.
• Python: python3 (3.11) with pip/venv (python aliased). PEP 668 — install into a venv.
• Java toolchain: Eclipse Temurin JDK 17 (/opt/java-17) and JDK 21 (/opt/java-21), /opt/java → 21 as default (JAVA_HOME), plus Gradle 8.8 (GRADLE_HOME), all on PATH. Switch JDK per run with -e JAVA_HOME=/opt/java-17 (the entrypoint re-prepends $JAVA_HOME/bin to PATH; Gradle honours JAVA_HOME); JAVA_17_HOME/JAVA_21_HOME also point at each. Gradle is checksum-verified at build; override with --build-arg GRADLE_VERSION=x.y.
• User / working dir: runs as non-root claude; working directory is /workspace; config lives in /home/claude/.claude.
• Entrypoint: /usr/local/bin/claude-entrypoint — enables Bedrock and execs claude "$@", or routes to the autonomous loop runner on the loop subcommand / CLAUDE_LOOP=1.
• Loop runner: /usr/local/bin/claude-agent-loop — drives Claude Code autonomously (see Autonomous agentic loop).
• Token helper: /usr/local/bin/claude-token — SSO / OIDC OAuth2 client-credentials helper for on-prem gateway auth (see On-prem gateway auth).

Configuration

On-prem gateway auth via SSO / OIDC (OAuth2 client-credentials)

Gateway mode engages automatically when you set a gateway URL plus credentials (see Recipes 1–4). With SSO it calls your OIDC issuer for a client-credentials token, sends it to the gateway as Authorization: Bearer, and auto-refreshes it (per CLAUDE_CODE_API_KEY_HELPER_TTL_MS, default 5 min, and on any 401) so long loop runs never die on an expired token. The token endpoint is <OIDC_ISSUER_URL>/realms/<realm>/protocol/openid-connect/token (realm defaults to master; OIDC_LEGACY_PATH=1 if your issuer serves under /auth), or set a full GATEWAY_TOKEN_URL which is used verbatim.

Recipes — copy/paste for each on-prem setup

Pick the one that matches your endpoint. Every example is complete: substitute the URLs/keys and run.

1. On-prem OpenAI-compatible model (GLM, vLLM, Ollama, LM Studio) — API key, no OAuth

bash
podman run --rm -v "$PWD:/workspace"   -e GATEWAY_PROTOCOL=openai   -e CLAUDE_GATEWAY_URL=http://glm.internal:8000   -e GATEWAY_API_KEY=sk-your-key   -e ANTHROPIC_MODEL=glm-4.6   n8500x/claude-code -p "explain this repo"

2. Same, but the endpoint needs no auth at all

bash
podman run --rm -v "$PWD:/workspace"   -e GATEWAY_PROTOCOL=openai   -e CLAUDE_GATEWAY_URL=http://vllm.internal:8000   -e GATEWAY_NO_AUTH=1   -e ANTHROPIC_MODEL=qwen2.5-coder   n8500x/claude-code -p "explain this repo"

3. Corporate gateway fronting Bedrock, OAuth2 via SSO

bash
podman run --rm -v "$PWD:/workspace"   -e GATEWAY_PROTOCOL=openai   -e CLAUDE_GATEWAY_URL=https://agent-gw.internal   -e GATEWAY_TOKEN_URL=https://sso.internal/realms/prod/protocol/openid-connect/token   -e GATEWAY_CLIENT_ID=my-client -e GATEWAY_CLIENT_SECRET=my-secret   -e GATEWAY_COOKIE='ROUTEID=abc'   -e CLAUDE_CA_CERT=/certs/ca.pem -v /etc/pki/ca.pem:/certs/ca.pem:ro   -e ANTHROPIC_MODEL='anthropic.claude-3-7-sonnet-20250219-v1:0'   n8500x/claude-code -p "explain this repo"

4. Gateway that speaks the Anthropic API natively (/v1/messages)

bash
podman run --rm -v "$PWD:/workspace"   -e GATEWAY_PROTOCOL=anthropic   -e CLAUDE_GATEWAY_URL=https://agent-gw.internal   -e GATEWAY_API_KEY=sk-your-key   -e ANTHROPIC_MODEL='anthropic.claude-3-7-sonnet-20250219-v1:0'   -e CLAUDE_BRIDGE_ALWAYS=1   n8500x/claude-code -p "explain this repo"

(CLAUDE_BRIDGE_ALWAYS=1 keeps the bridge in the path for request logging without translating anything — drop it for a direct connection.)

5. Autonomous Java codegen from a private repo's skills

bash
podman run --rm --user root -v "$PWD:/workspace"   -e CLAUDE_PROFILE=java -e CLAUDE_JAVA=17   -e GATEWAY_PROTOCOL=openai -e CLAUDE_GATEWAY_URL=http://glm.internal:8000   -e GATEWAY_API_KEY=sk-your-key -e ANTHROPIC_MODEL=glm-4.6   -e GIT_SSH_KEY_FILE=/keys/id -v ~/.ssh/id_ed25519:/keys/id:ro   -e CLONE_REPO='git@git.internal:org/repo.git'   -e CLAUDE_SHOW_CODE=1   n8500x/claude-code loop "Using the skill in .claude/skills, generate the REST layer"

6. Bedrock directly (no gateway)

bash
podman run --rm -v "$PWD:/workspace"   -e AWS_REGION=us-east-1   -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN   -e ANTHROPIC_MODEL='us.anthropic.claude-3-7-sonnet-20250219-v1:0'   n8500x/claude-code -p "explain this repo"

Auth is chosen by what you set — no flag needed:

When it doesn't work, add -e CLAUDE_DEBUG=1 (full auth/token/model trace) or -e BRIDGE_LOG_BODY=1 (exact request/response bodies). See Troubleshooting.

Gateway protocol switch (Anthropic or OpenAI)

Set only the base URL and pick the protocol with one switch — it selects both the endpoint path and the message JSON format:

bash
-e GATEWAY_PROTOCOL=openai -e CLAUDE_GATEWAY_URL=https://agent-gw.internal      # base URL only

The URL is normalised: if you include /v1/messages or /v1/chat/completions it's stripped (and the matching protocol auto-selected), so paths can never double up. Override the upstream path with GATEWAY_CHAT_PATH. Startup prints what it resolved:

protocol: openai — Claude /v1/messages → bridge → https://agent-gw.internal/v1/chat/completions (JSON translated)

The bridge translates tool calls and SSE streaming both ways, and logs each rewrite in colour (▶ REWRITE … → OpenAI POST …). CLAUDE_DEBUG=1 adds the translated JSON; gateway errors print in red with the verbatim body. CLAUDE_TRACE=1 (either protocol) logs raw request/response.

Tell-tale that you need openai: the gateway replies Cannot POST /v1/messages.

Bedrock model selection

ANTHROPIC_MODEL is unset by default (CLI uses its Bedrock defaults). Pin one with -e ANTHROPIC_MODEL='us.anthropic.claude-...-v1:0'. The model must be enabled in AWS_REGION, and the ID is usually an inference-profile ID (us./eu./apac. prefix), not a bare foundation-model ID.

Environment variables

Mounts

Air-gapped / on-prem deployment

Runs fully offline against only your internal gateway or a Bedrock VPC endpoint.

Self-contained at runtime. CLI, toolchain, token helper and docs are baked in — nothing is fetched at start. Prove it: docker run --rm --network none n8500x/claude-code help. Telemetry, error reporting and the auto-updater are off by default.

Private CA (usually required). Internal SSO / gateways present a corporate-CA cert. Mount it at run time — -e CLAUDE_CA_CERT=/certs/ca.pem -v /path/ca.pem:/certs/ca.pem:ro — and both hops trust it; or bake it at build by dropping *.crt into certs/. -e CLAUDE_TLS_INSECURE=1 skips verification on trusted networks.

Distribute offline: docker save n8500x/claude-code | gzip > cc.tar.gz, copy across the gap, docker load < cc.tar.gz.

Building your projects needs internal mirrors — the image ships toolchains, not a dep cache. Gradle: use the baked gradle (not ./gradlew) + internal Maven repo. npm/pip: point at your registry.

Running in Jenkins (CI)

Run headless from any Jenkins agent with Docker. No TTY in a build, so no -it — use -p "PROMPT" or loop "GOAL"; both stream to the build log and return meaningful exit codes. Feed credentials from Jenkins Credentials.

Gateway (SSO) — Jenkinsfile stage:

groovy
stage('Agent task') {
  steps {
    withCredentials([usernamePassword(credentialsId: 'gateway-sso',
                     usernameVariable: 'GW_ID', passwordVariable: 'GW_SECRET')]) {
      sh '''
        docker run --rm --user root -v "$WORKSPACE:/workspace" \
          -e CLAUDE_GATEWAY_URL=https://agent-gw.internal/anthropic \
          -e OIDC_ISSUER_URL=https://sso.internal \
          -e ANTHROPIC_MODEL=anthropic.claude-3-7-sonnet-20250219-v1:0 \
          -e GATEWAY_CLIENT_ID="$GW_ID" -e GATEWAY_CLIENT_SECRET="$GW_SECRET" \
          n8500x/claude-code -p "Review the diff and add any missing unit tests."
      '''
    }
  }
}

Swap -p "…" for loop "…" (add -e CLAUDE_LOOP_MAX_ITERS=15) for an autonomous multi-step run. For Bedrock (SigV4) instead, bind AWS creds via AmazonWebServicesCredentialsBinding and pass -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN.

CI notes

• No -it (no TTY). loop bypasses prompts; for -p add -e CLAUDE_YOLO=1.
• Exit codes drive pass/fail: loop → 0 done / 4 max-iters / 3 budget / 1 errors; -p non-zero on failure.
• File ownership: --user root lets the agent write $WORKSPACE; or --user "$(id -u):$(id -g)" -e HOME=/tmp to keep host ownership.
• Air-gapped agents: pre-load the image (docker load); private CA is baked or via CLAUDE_CA_CERT.
• Kubernetes: use the image as a podTemplate container and run claude -p …, or sh 'docker run …'.

Build

bash
docker build -t n8500x/claude-code .

To bake a private CA, drop *.crt into certs/ before building:

bash
cp corp-root-ca.crt certs/ && docker build -t n8500x/claude-code .

Override the pinned CLI version:

bash
docker build \
  --build-arg CLAUDE_CODE_VERSION=2.1.220 \
  -t n8500x/claude-code .

Troubleshooting

First step for any auth issue: re-run with -e CLAUDE_DEBUG=1 — it prints the auth-mode decision, the exact SSO token endpoint, the client-credentials POST + HTTP status, and the token length, so the failing hop is obvious.

Notes

• Bedrock access is assumed to be reachable from the container — over the internet or a VPC/PrivateLink endpoint for air-gapped setups. This image does not bundle a model backend.
• --dangerously-skip-permissions (CLAUDE_YOLO=1) runs every tool without prompting. Only point it at workspaces you trust.
• Credentials never bake into the image — they come in at run time via env or a mounted ~/.aws.