claudejail

Run Claude Code inside a Docker container with your project mounted at /code. The image is built locally from a bundled Dockerfile based on the latest official debian image, with a non-root claude user and Homebrew installed at /home/linuxbrew/.linuxbrew (outside the user's home so a persistent volume can cover /home/claude without hiding brew). Anything written to /home/claude persists across sessions in a named volume.

Requirements

• Docker (running)
• Node.js or Bun to run the CLI

Install

npm i -g claudejail
# or
bun add -g claudejail

Usage

claudejail [options]

Mounts the current directory at /code, builds the image if needed, and drops you into Claude Code (or a shell with --shell).

Options

| Option | Description | |---|---| | --packages <pkg...> | Extra brew packages to install before launching (e.g. --packages ripgrep git) | | --from <dir> | Host folder to mount at /code (default: current directory) | | --prompt <text> | Custom system prompt passed to Claude Code | | --volume <name> | Name of the persistent volume mounted at /home/claude (default: claudejail) | | --networks <net...> | Docker networks to attach | | --shell | Drop into an interactive shell instead of launching Claude Code |

Examples

# Launch Claude Code on the current directory
claudejail

# Open a shell in the same container instead
claudejail --shell

# Mount a specific project
claudejail --from /path/to/project

# Pre-install extra tools
claudejail --packages ripgrep fd jq

# Custom system prompt
claudejail --prompt "You are a Python refactoring assistant."

How it works

• Image: built locally from a bundled Dockerfile (debian:latest + claude user at /home/claude + Homebrew at /home/linuxbrew/.linuxbrew). The tag is content-addressed, so the image rebuilds only when the Dockerfile changes; Docker's layer cache handles the rest.
• Volumes:
  • <host dir>:/code — your project, bind-mounted read/write.
  • claudejail:/home/claude — claude user home, persisted in a named Docker volume. Holds Claude Code auth (.claude/.credentials.json) and anything else written under /home/claude.
• Brew location: /home/linuxbrew/.linuxbrew (baked into the image, not in the volume). claude-code, uv, bun, and any extra --packages are installed at container start with brew install.
• Sudo: not used. The claude user is created first and /home/linuxbrew is pre-chowned to it, then install.sh runs as claude. With no /usr/bin/sudo present, have_sudo_access returns 1 and execute_sudo falls back to plain exec — every chown/chgrp/mkdir touches the prefix we already own, so the install completes without root or sudoers.
• PATH: brew shellenv is dropped into /etc/profile.d/homebrew.sh so brew is in PATH regardless of which user lands in the container, and the runtime volume on /home/claude cannot hide it.
• Auth: stored in /home/claude/.claude/.credentials.json. Lives in the named volume, so you log in once and stay logged in.
• Permissions: Claude Code runs with --dangerously-skip-permissions — the container is the sandbox.