n8500x/claude-code repository overview

⁠claude-code (Bedrock)

The 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.

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:

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

⁠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):

docker run --rm \
  -e GIT_SSH_KEY_FILE=/keys/id -v ~/.ssh/id_ed25519:/keys/id:ro \
  -e CLONE_REPO='[email protected]: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:

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:22-alpine; Maven's plexus-utils and npm's bundled deps patched → the image scans at ZERO high/critical CVEs.
• 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, bash, openssl, unzip, ca-certificates.
• Python: python3 with pip (python aliased). PEP 668 — use a venv.
• Java toolchain: OpenJDK 17 (/opt/java-17) and 21 (/opt/java-21), /opt/java → 21 default (JAVA_HOME), plus Gradle 9.7.1 (GRADLE_HOME; scripts clean of deprecation warnings on Gradle 8 run unchanged). Switch JDK per run with -e JAVA_HOME=/opt/java-17 (entrypoint re-prepends $JAVA_HOME/bin to PATH; Gradle honours JAVA_HOME). Checksum-verified; 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

Gateway mode engages when CLAUDE_GATEWAY_URL is set. Auth is whichever you provide: GATEWAY_API_KEY (static key), GATEWAY_NO_AUTH=1 (none), or GATEWAY_CLIENT_ID/GATEWAY_CLIENT_SECRET + OIDC_ISSUER_URL (OAuth2 client-credentials, token auto-refreshed per CLAUDE_CODE_API_KEY_HELPER_TTL_MS and on any 401). The token endpoint is <OIDC_ISSUER_URL>/realms/<OIDC_REALM>/protocol/openid-connect/token (realm defaults to master), or set GATEWAY_TOKEN_URL which is used verbatim. See Recipes⁠.

⁠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

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

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

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)

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

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='[email protected]: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)

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:

Debugging: -e CLAUDE_DEBUG=1 (full trace) or -e BRIDGE_LOG_BODY=1 (request/response bodies).

⁠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:

-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.

⁠Gateway compatibility & payload control

Applied automatically (no flags):

Disable with -e BRIDGE_COMPAT=0; add fields via -e BRIDGE_STRIP_FIELDS="a b".

To shrink the request (the → model · …KB line shows what's sent):

⁠Baked Gradle plugins & run artifacts

The image pre-bakes Spotless com.diffplug.spotless 7.1.0 into a shared Gradle cache (GRADLE_USER_HOME=/opt/gradle-home), so air-gapped builds resolve it offline (gradle --offline works; add plugins via --build-arg SPOTLESS_VERSION=… or the same warm pattern).

Loop artifacts land in the directory Claude started in (the cloned repo when CLONE_REPO is used): claude-report.html (tokens, cost, tool calls, diff), claude-status.json (machine-readable for the pipeline), and the final commit (never pushed — CI owns the push). Override with CLAUDE_REPORT_FILE / CLAUDE_STATUS_FILE; skip with CLAUDE_REPORT=0 / CLAUDE_COMMIT=0.

⁠Long-running builds

Claude Code's Bash tool defaults to a 2-minute timeout, which kills a real Gradle/Maven build. The image raises it (all overridable):

⁠Surviving gateway/route timeouts (504)

A route that caps request duration (OpenShift HAProxy: 30s) 504s before a long completion finishes. The bridge retries and shrinks to fit:

Keep BRIDGE_STREAM=true/auto — streaming responses are far less likely to hit router timeouts.

⁠Small context windows (GLM 131k etc.)

A model with a window under Claude's assumed ~200k 400s as the conversation grows. Set -e CLAUDE_CONTEXT_LIMIT=131072. Then: (1) Claude auto-compacts its own session — after a bridge compaction ~98% of the window is reported as input usage, so Claude summarizes its own history. (2) The bridge compacts oversized requests (system + task + recent turns), proactively and on 400s. (3) Dropped turns are summarized via a gateway call into the note. In loop mode, an iteration that hit compaction makes the next one start a FRESH session re-deriving state from the repo (resuming an over-window session loops forever). BRIDGE_CONTEXT_COMPACT=0/BRIDGE_COMPACT_SUMMARY=0 disable (2)/(3); BRIDGE_TOKEN_RATIO tunes the chars-per-token estimate (3 when CLAUDE_CONTEXT_LIMIT is set, else 4).

⁠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)

Wrap any recipe⁠ in a sh step. No -it (no TTY); use -p "PROMPT" or loop "GOAL". Feed credentials from Jenkins Credentials, e.g. withCredentials([string(credentialsId: 'gateway-api-key', variable: 'GW_KEY')]) then -e GATEWAY_API_KEY="$GW_KEY".

sh '''
  docker run --rm --user root -v "$WORKSPACE:/workspace" \
    -e GATEWAY_PROTOCOL=openai -e CLAUDE_GATEWAY_URL=https://gw.internal \
    -e GATEWAY_API_KEY="$GW_KEY" -e ANTHROPIC_MODEL=glm-4.6 \
    n8500x/claude-code -p "Review the diff and add missing unit tests."
'''

Notes: exit codes drive stage pass/fail (loop: 0 done / 4 max-iters / 3 budget / 1 errors); --user root (or --user "$(id -u):$(id -g)" -e HOME=/tmp) to write $WORKSPACE; pre-load the image on air-gapped agents.

⁠Build

docker build -t n8500x/claude-code .

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

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

Override the pinned CLI version:

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

⁠Troubleshooting

⁠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.