From d45c1c7739ee43c47c64b735ebb15532900ecc6b Mon Sep 17 00:00:00 2001 From: Willem van den Ende Date: Sat, 29 Nov 2025 15:49:50 +0000 Subject: [PATCH] Add README and simplify CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move user-facing setup instructions to new README.md and reduce CLAUDE.md to essential project context for Claude Code. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 133 +++++------------------------------------------------- README.md | 48 ++++++++++++++++++++ 2 files changed, 59 insertions(+), 122 deletions(-) create mode 100644 README.md diff --git a/CLAUDE.md b/CLAUDE.md index a77662e..8024cf3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,133 +1,22 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Instructions for Claude Code when working on this repository. -## Development Container Setup +## Project Overview -This repository is configured with a secure development container based on Anthropic's reference devcontainer setup. The container provides: +This is a secure devcontainer configuration for running Claude Code in a sandboxed environment with network restrictions. -- **Isolated environment**: Containerized Claude Code CLI with firewall restrictions -- **Security features**: Network access limited to whitelisted domains (GitHub, npm, Anthropic APIs, etc.) -- **Pre-configured tools**: Node.js 20, Claude Code CLI, git-delta, zsh with powerline10k, fzf, and more -- **Persistent storage**: Volumes for bash history and Claude configuration - -### Opening in DevContainer - -**Option 1: Using run-container.sh script (easiest for non-interactive usage)** - -The repository includes a helper script for running Claude Code non-interactively: - -```bash -# Make the script executable (first time only) -chmod +x run-container.sh - -# Run with a prompt -./run-container.sh "explain the fibonacci sequence" - -# Run with stdin -echo "create a hello world function in Python" | ./run-container.sh - -# Analyze a file -./run-container.sh "explain this code" < myfile.js -``` - -The script automatically: -- Builds the Docker image if needed -- Creates persistent volumes for history and config -- Initializes the firewall -- Runs claude with streaming output and --dangerously-skip-permissions -- Cleans up the container after execution - -**Option 2: Using devcontainer CLI (recommended for interactive development)** - -Install the devcontainer CLI: -```bash -npm install -g @devcontainers/cli -``` - -Build and run the container: -```bash -# Build the container -devcontainer build --workspace-folder . - -# Run the container and execute a command -devcontainer exec --workspace-folder . claude -p "your prompt" --dangerously-skip-permissions - -# Or open an interactive shell -devcontainer exec --workspace-folder . zsh -``` - -**Option 3: Using Docker directly** - -Build and run manually: -```bash -# Build the image -docker build -t claude-dev-container .devcontainer - -# Create volumes for persistence -docker volume create claude-code-bashhistory -docker volume create claude-code-config - -# Run interactively -docker run -it --rm \ - --cap-add=NET_ADMIN \ - --cap-add=NET_RAW \ - -v "$(pwd):/workspace" \ - -v claude-code-bashhistory:/commandhistory \ - -v claude-code-config:/home/node/.claude \ - -e NODE_OPTIONS="--max-old-space-size=4096" \ - -e CLAUDE_CONFIG_DIR="/home/node/.claude" \ - -w /workspace \ - --user node \ - claude-dev-container zsh - -# Inside the container, initialize the firewall: -sudo /usr/local/bin/init-firewall.sh - -# Then use Claude Code: -claude -p "your prompt" --dangerously-skip-permissions -``` - -**Option 4: VS Code** -1. Install the "Dev Containers" extension -2. Open this repository in VS Code -3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container") -4. Wait for the container to build and the firewall to initialize - -**First-time setup:** -- You'll need to authenticate Claude Code on first use -- Run `claude` in the container terminal and follow the authentication prompts - -### Running Claude Code Non-Interactively - -The devcontainer's firewall allows running Claude Code with `--dangerously-skip-permissions` for non-interactive operation: - -```bash -# Stream output in non-interactive mode -claude -p "your prompt here" --dangerously-skip-permissions - -# Example: Analyze a file -claude -p "explain this code" --dangerously-skip-permissions < myfile.js - -# Example: Generate code with streaming output -echo "create a fibonacci function" | claude -p --dangerously-skip-permissions -``` - -**Security notes:** -- The `--dangerously-skip-permissions` flag bypasses permission prompts -- This is safe within the devcontainer due to firewall restrictions -- Network access is limited to: GitHub, npm registry, Anthropic APIs, VS Code services -- All other outbound connections are blocked - -### Container Configuration Files +## Key Files - `.devcontainer/devcontainer.json` - Container and VS Code configuration - `.devcontainer/Dockerfile` - Container image definition -- `.devcontainer/init-firewall.sh` - Network security rules (runs on container start) +- `.devcontainer/init-firewall.sh` - Network security rules (iptables whitelist) +- `run-container.sh` - Helper script for non-interactive usage -### Environment Setup (Outside Container) +## Development -This repository uses [mise](https://mise.jdx.dev/) for tool version management. +Uses [mise](https://mise.jdx.dev/) for tool versioning. Run `mise install` to set up Node.js 24. -- Node.js version: 24 (configured in `mise.toml`) -- Install tools: `mise install` +## Security Model + +The container uses iptables to whitelist only essential domains (GitHub, npm, Anthropic APIs, VS Code services). This allows safe use of `--dangerously-skip-permissions`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b3eb5af --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ +# Claude Code Devcontainer + +A secure, sandboxed development container for running Claude Code with network restrictions. + +## Quick Start + +### Option 1: VS Code (Interactive) + +1. Copy the `.devcontainer/` folder to your project root +2. Open your project in VS Code +3. Press `Ctrl+Shift+P` → "Dev Containers: Reopen in Container" +4. Run `claude` in the terminal to authenticate and start + +### Option 2: Command Line (Non-Interactive) + +Copy both `.devcontainer/` and `run-container.sh` to your project, then: + +```bash +# Make executable (first time only) +chmod +x run-container.sh + +# Run with a prompt +./run-container.sh "explain the fibonacci sequence" + +# Pipe input +echo "write a hello world function" | ./run-container.sh + +# Analyze a file +./run-container.sh "explain this code" < myfile.js + +# Interactive mode (no prompt) +./run-container.sh +``` + +## Requirements + +- Docker +- VS Code with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (for Option 1) + +## Security + +The container runs with a firewall that only allows connections to: +- GitHub +- npm registry +- Anthropic APIs +- VS Code services + +All other outbound traffic is blocked, making it safe to use `--dangerously-skip-permissions`.