Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 52 additions & 1 deletion claude.sh
Original file line number Diff line number Diff line change
Expand Up @@ -84,14 +84,65 @@ fi
# The entrypoint creates /home/claude-user for the mapped user.
CONTAINER_HOME="/home/claude-user"

# --- Git data of a worktree ---
# A worktree's .git file, and the .git files of its submodules, point to the
# main checkout's git directory by host path, absolute or relative. Mount that
# directory and the worktree at their host paths, and start in the worktree's
# host path, so these links resolve in the container. /workspace stays.
HOST_DIR=$(cd "${SCRIPT_DIR}" && pwd -P)
CONTAINER_WORKDIR=/workspace
GIT_TOP=""
GIT_COMMON_DIR=""
if git_top=$(git -C "${HOST_DIR}" rev-parse --show-toplevel 2> /dev/null) &&
git_common=$(git -C "${HOST_DIR}" rev-parse --git-common-dir 2> /dev/null); then
GIT_TOP=$(cd "${git_top}" 2> /dev/null && pwd -P) || GIT_TOP=""
GIT_COMMON_DIR=$(cd "${HOST_DIR}" && cd "${git_common}" 2> /dev/null && pwd -P) ||
GIT_COMMON_DIR=""
fi

# True when host path $1 does not overlap a path that the container already uses.
outside_container_paths() {
[[ "$1/" != /workspace/* && "$1/" != "${CONTAINER_HOME}/"* ]]
}

GIT_MOUNTS=()
# Only for the top of a checkout: a plain folder inside another repository
# must not get that repository's .git.
if [[ "${GIT_TOP}" == "${HOST_DIR}" && -n "${GIT_COMMON_DIR}" &&
"${GIT_COMMON_DIR}/" != "${HOST_DIR}/"* ]]; then
if outside_container_paths "${HOST_DIR}" &&
outside_container_paths "${GIT_COMMON_DIR}"; then
GIT_MOUNTS=(
-v "${HOST_DIR}:${HOST_DIR}"
-v "${GIT_COMMON_DIR}:${GIT_COMMON_DIR}"
)
CONTAINER_WORKDIR=${HOST_DIR}
else
echo "Warning: ${HOST_DIR} and its git data in ${GIT_COMMON_DIR} cannot" \
"both be mounted at their host paths, because one of them is under" \
"/workspace or ${CONTAINER_HOME}. Git does not work in the container." >&2
fi
fi

# --- Assemble docker run arguments ---
DOCKER_RUN_ARGS=(
--rm
--name "${CONTAINER_NAME}"
-v "${SCRIPT_DIR}:/workspace"
-e "HOST_UID=$(id -u)"
-e "HOST_GID=$(id -g)"
-w /workspace
-w "${CONTAINER_WORKDIR}"
)
if [[ ${#GIT_MOUNTS[@]} -gt 0 ]]; then
DOCKER_RUN_ARGS+=("${GIT_MOUNTS[@]}")
fi

# The host paths of other worktrees do not exist in the container, so git gc
# there would prune their records from the shared .git directory. Stop that.
DOCKER_RUN_ARGS+=(
-e GIT_CONFIG_COUNT=1
-e GIT_CONFIG_KEY_0=gc.worktreePruneExpire
-e GIT_CONFIG_VALUE_0=never
)

# TTY/stdin handling for interactive, CI, and piped-input cases:
Expand Down
15 changes: 11 additions & 4 deletions docker/claude-entrypoint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@
# inside the container have the correct ownership on the host volume.
set -e

# claude.sh starts a git worktree in its host path. env.sh sets paths from
# its own location, so source the copy there to keep the paths the same.
ENV_SH=/workspace/env.sh
if [ -f "${PWD}/env.sh" ]; then
ENV_SH="${PWD}/env.sh"
fi

if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then
USER_NAME="claude-user"
USER_HOME="/home/${USER_NAME}"
Expand Down Expand Up @@ -40,9 +47,9 @@ if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then

# Set up ORFS environment (PATH to tools, FLOW_HOME, etc.)
# Sourced here; inherited through setpriv into all child processes.
if [ -f /workspace/env.sh ]; then
if [ -f "${ENV_SH}" ]; then
set +e
. /workspace/env.sh > /dev/null
. "${ENV_SH}" > /dev/null
set -e
fi

Expand All @@ -53,9 +60,9 @@ if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then
-- "$@"
else
# No UID/GID mapping requested; run as root
if [ -f /workspace/env.sh ]; then
if [ -f "${ENV_SH}" ]; then
set +e
. /workspace/env.sh > /dev/null
. "${ENV_SH}" > /dev/null
set -e
fi
exec "$@"
Expand Down
130 changes: 130 additions & 0 deletions docker/test-claude-sh.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
#!/usr/bin/env bash
# Check the git mounts that claude.sh adds, with a stub docker command, and
# which env.sh the entrypoint sources.
# Needs bash and git only; no container engine runs.
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
tmp=$(mktemp -d)
trap 'rm -rf "${tmp}"' EXIT

mkdir -p "${tmp}/bin" "${tmp}/home"
cat > "${tmp}/bin/docker" << 'EOF'
#!/usr/bin/env bash
# The image exists. For "run", print each argument on its own line.
if [[ "$1" == run ]]; then
shift
printf '%s\n' "$@"
fi
EOF
chmod +x "${tmp}/bin/docker"

git -c init.defaultBranch=main init -q "${tmp}/main"
cp "${SCRIPT_DIR}/../claude.sh" "${tmp}/main/claude.sh"
git -C "${tmp}/main" add claude.sh
git -C "${tmp}/main" -c user.name=test -c user.email=test@example.invalid \
-c core.hooksPath=/dev/null -c commit.gpgsign=false commit -q -m init
git -C "${tmp}/main" worktree add -q "${tmp}/wt"
common=$(cd "${tmp}/main/.git" && pwd -P)
wt=$(cd "${tmp}/wt" && pwd -P)
mkdir "${tmp}/plain"
cp "${SCRIPT_DIR}/../claude.sh" "${tmp}/plain/claude.sh"
# A plain folder inside another repository, for example a home in git.
git -c init.defaultBranch=main init -q "${tmp}/parent"
mkdir -p "${tmp}/parent/src/orfs"
cp "${SCRIPT_DIR}/../claude.sh" "${tmp}/parent/src/orfs/claude.sh"
parent_git=$(cd "${tmp}/parent/.git" && pwd -P)

# Git before 2.31 does not know --path-format. rev-parse then prints the
# option as output and exits 0. This wrapper does the same.
mkdir "${tmp}/oldgit"
cat > "${tmp}/oldgit/git" << EOF
#!/usr/bin/env bash
args=()
for arg in "\$@"; do
case "\${arg}" in
--path-format=*) echo "\${arg}" ;;
*) args+=("\${arg}") ;;
esac
done
exec "$(command -v git)" "\${args[@]}"
EOF
chmod +x "${tmp}/oldgit/git"

run_args() { # Print the docker run arguments of claude.sh in checkout $1.
env -u SSH_AUTH_SOCK HOME="${tmp}/home" PATH="${tmp}/bin:${PATH}" \
bash "$1/claude.sh" --shell < /dev/null
}

workdir() { # Print the value of -w in the arguments $1.
grep -A1 -xF -- -w <<< "$1" | tail -n 1
}

fail() {
echo "FAIL: $*" >&2
exit 1
}

check_plain() { # check_plain NAME ARGS: only /workspace, prune guard set.
if grep -qF "${common}:" <<< "$2" || grep -qF "${wt}:" <<< "$2"; then
fail "$1: unexpected git mount"
fi
[[ "$(workdir "$2")" == /workspace ]] || fail "$1: workdir is not /workspace"
grep -qxF GIT_CONFIG_VALUE_0=never <<< "$2" ||
fail "$1: automatic worktree prune is not disabled"
}

check_worktree() { # check_worktree NAME ARGS: host-path mounts and workdir.
grep -qxF "${common}:${common}" <<< "$2" ||
fail "$1: ${common} is not mounted at its host path"
grep -qxF "${wt}:${wt}" <<< "$2" ||
fail "$1: ${wt} is not mounted at its host path"
[[ "$(workdir "$2")" == "${wt}" ]] || fail "$1: workdir is not ${wt}"
grep -qxF GIT_CONFIG_VALUE_0=never <<< "$2" ||
fail "$1: automatic worktree prune is not disabled"
}

check_worktree worktree "$(run_args "${tmp}/wt")"
echo "A worktree gets its host path and the main .git at their host paths"

check_plain "main checkout" "$(run_args "${tmp}/main")"
echo "A main checkout gets no extra mount"

check_plain "not a repository" "$(run_args "${tmp}/plain")"
echo "A folder outside git gets no extra mount"

args=$(run_args "${tmp}/parent/src/orfs")
check_plain "folder in a parent repository" "${args}"
if grep -qF "${parent_git}" <<< "${args}"; then
fail "folder in a parent repository: the parent .git is mounted"
fi
echo "A folder inside another repository does not get its .git"

check_worktree "old git, worktree" "$(PATH="${tmp}/oldgit:${PATH}" run_args "${tmp}/wt")"
check_plain "old git, main checkout" "$(PATH="${tmp}/oldgit:${PATH}" run_args "${tmp}/main")"
echo "Git without --path-format gives the same mounts"

# The entrypoint, here without UID mapping, sources env.sh from its start
# directory, which claude.sh sets to the worktree's host path.
mkdir "${tmp}/start"
echo 'export CLAUDE_TEST_ENV="${BASH_SOURCE[0]}"' > "${tmp}/start/env.sh"
sourced() { # Print which env.sh the entrypoint sourced when started in $1.
(cd "$1" && env -u HOST_UID -u HOST_GID \
bash "${SCRIPT_DIR}/claude-entrypoint.sh" printenv CLAUDE_TEST_ENV) || true
}
[[ "$(sourced "${tmp}/start")" == "${tmp}/start/env.sh" ]] ||
fail "entrypoint: env.sh in the start directory is not sourced"
[[ -z "$(sourced "${tmp}/plain")" ]] ||
fail "entrypoint: a start directory without env.sh sourced something"
echo "The entrypoint sources env.sh from its start directory"

# The entrypoint sources env.sh from a host path, which can contain spaces.
mkdir "${tmp}/with space"
cp "${SCRIPT_DIR}/../env.sh" "${tmp}/with space/env.sh"
printf '#!/bin/sh\necho /brew\n' > "${tmp}/bin/brew" # env.sh calls brew on macOS
chmod +x "${tmp}/bin/brew"
flow_home=$(PATH="${tmp}/bin:${PATH}" bash -c \
'. "$1/env.sh" > /dev/null && echo "${FLOW_HOME}"' _ "${tmp}/with space")
[[ "${flow_home}" == "$(cd "${tmp}/with space" && pwd -P)/flow" ]] ||
fail "env.sh in a path with a space: FLOW_HOME is '${flow_home}'"
echo "env.sh works in a path with a space"
30 changes: 28 additions & 2 deletions docs/user/ClaudeCode.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ are mounted so their contents survive:
| `~/.claude/` | `~/.claude/` | Credentials, settings, conversation history |
| `~/.cache/bazel-claude/` | `~/.cache/bazel/` | Bazel external dependencies |
| `~/.gitconfig` | `~/.gitconfig` | Git identity (read-only) |
| Worktree and main `.git` (worktree only) | Same host paths | Git refs, objects, hooks, config |
| `$SSH_AUTH_SOCK` | forwarded | SSH agent for git over SSH |

## Environment variables
Expand Down Expand Up @@ -132,7 +133,7 @@ Handles UID/GID mapping so files created inside the container have the
correct ownership on the host. The entrypoint:

1. Creates a user matching the host UID/GID
2. Sources `env.sh` to set up tool paths
2. Sources `env.sh` to set up tool paths, from the start directory if it has one, else from `/workspace`
3. Drops privileges via `setpriv` before running the command

This follows the same pattern as `tools/OpenROAD/etc/docker-entrypoint.sh`
Expand All @@ -143,13 +144,38 @@ and the `--user` mode in `flow/util/docker_shell`.
Wrapper script that assembles the `docker run` command with the correct
volume mounts, environment variables, and entrypoint arguments.

When you run `claude.sh` from the top of a git worktree, it also mounts the worktree and the main checkout's `.git` directory at their host paths.
The shell starts in the worktree's host path.
The worktree's `.git` file and the `.git` files of its submodules point to these paths, so git works in the container.
The entrypoint sources `env.sh` from there, so `OPENROAD`, `FLOW_HOME` and `PATH` use the host path too.
Rebuild the image with `./claude.sh --build` to get this entrypoint.
The worktree is also at `/workspace`, but git links in submodules do not resolve from that path.
If one of these host paths is under `/workspace` or `/home/claude-user`, the wrapper prints a warning and adds no mounts, and git does not work in the container.

The paths of the other worktrees do not exist in the container, so git sees them as stale.
The wrapper sets `gc.worktreePruneExpire=never` in the container, so `git gc` keeps their records.
`git gc` still removes the record of a worktree that has no index file.
Do not run `git worktree prune` or `git worktree repair` in the container: they change the records of the other worktrees.

The start directory is part of some keys and caches.
Claude Code stores the history of a worktree session under the host path, not under `/workspace`, so earlier `/workspace` sessions of that worktree do not resume.
Bazel uses a new output base, and a CMake build directory that you configured under `/workspace` must be configured again.

Check the mounts with a stub `docker` command, without a container engine:

```shell
bash docker/test-claude-sh.sh
```

## Security model

Claude Code runs with `--dangerously-skip-permissions` **inside** the
container, meaning it can execute any shell command without confirmation.
The Docker container provides the isolation:

- File access is limited to the mounted repository
- File access is limited to the mounted repository.
From a git worktree, this includes the main checkout's `.git` directory, with the refs and objects of all its worktrees.
It also holds git hooks and config, which run on the host at the next git command, so code in the container can run code on the host.
- No access to host system packages, services, or other projects
- No access to host network services bound to localhost
- `docker kill claude-orfs` stops everything instantly
Expand Down
4 changes: 2 additions & 2 deletions env.sh
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
#!/usr/bin/env bash
function __setpaths() {
if [[ "$OSTYPE" == "darwin"* ]]; then
DIR="$(dirname $(perl -e 'use Cwd "abs_path";print abs_path(shift)' "${BASH_SOURCE[0]:-${(%):-%x}}"))"
DIR="$(dirname "$(perl -e 'use Cwd "abs_path";print abs_path(shift)' "${BASH_SOURCE[0]:-${(%):-%x}}")")"
else
DIR="$(dirname $(readlink -f "${BASH_SOURCE[0]:-${(%):-%x}}"))"
DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]:-${(%):-%x}}")")"
fi

export OPENROAD=${DIR}/tools/OpenROAD
Expand Down