tool-containers
Search docs…Ctrl K
Menu
GitHub (opens in new tab)

Run Claude Code with Docker

run.sh starts Claude Code on the current directory, passing any arguments to claude. airgapped.run.sh does the same from a saved image on a host that cannot pull.

Images
  • GHCRghcr.io/hambn/claude-code
  • Docker Hubdocker.io/hambn/claude-code
Use case
Interactive coding on a local checkout
Upstream
github.com/anthropics/claude-code (opens in new tab)
Source
tools/ai/claude-code/docs/docker (opens in new tab)
On this page

Prerequisites

  • Docker Engine 23 or later.
  • An Anthropic API key in ANTHROPIC_API_KEY.

Run Claude Code

Shell
export ANTHROPIC_API_KEY=sk-ant-...
./run.sh                                  # interactive session
./run.sh -p "explain the build scripts"   # print one answer and exit

Run without registry access

On a machine that can pull, save the image:

Shell
docker save ghcr.io/hambn/claude-code:ubuntu-browser -o claude-code.tar

Copy the tar to the offline host and pass its path first; the remaining arguments go to claude:

Shell
./airgapped.run.sh claude-code.tar

The script loads the tar and runs CLAUDE_CODE_IMAGE with --pull=never, so set that variable if you saved a different tag.

Variables

Variable Required Purpose
ANTHROPIC_API_KEY yes Forwarded to the container; the scripts stop if it is unset.
CLAUDE_CODE_IMAGE no Image both scripts run. Defaults to ghcr.io/hambn/claude-code:ubuntu-browser; set ghcr.io/hambn/claude-code@sha256:<digest> to pin one build.

Workspace

The current directory is mounted at /workspace, the image's working directory. Claude Code runs as sysadmin (UID 1000), so new files belong to UID 1000 on the host. Its settings and session history stay in the container and are removed with it.

Files

  • run.sh pulls the image if needed and runs it.
  • airgapped.run.sh loads a saved tar and runs it without pulling.

File contents

airgapped.run.sh19 lines
#!/usr/bin/env bash
# Offline host: load the image from a tar saved on an online host, never pull.
#   docker save ghcr.io/hambn/claude-code:ubuntu-browser -o claude-code.tar
set -euo pipefail
: "${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}"

image=${CLAUDE_CODE_IMAGE:-ghcr.io/hambn/claude-code:ubuntu-browser}
tar=${1:-claude-code.tar}
shift $(($# > 0 ? 1 : 0))
[[ -f "$tar" ]] || {
    echo "missing $tar; docker save it on an online host first" >&2
    exit 1
}

docker load -i "$tar"
docker run -it --rm --pull=never \
    -e ANTHROPIC_API_KEY \
    -v "$PWD:/workspace" \
    "$image" "$@"
run.sh10 lines
#!/usr/bin/env bash
# Run Claude Code against the current directory.
set -euo pipefail
: "${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}"

image=${CLAUDE_CODE_IMAGE:-ghcr.io/hambn/claude-code:ubuntu-browser}
docker run -it --rm \
    -e ANTHROPIC_API_KEY \
    -v "$PWD:/workspace" \
    "$image" "$@"

Topics