Merge pull request #7 from lroolle/fix/env-vars-and-auth-improvements

Environment variables, authentication improvements, and critical security fix

Author: lroolle

DEV-LOGS.md

@@ -1,12 +1,144 @@
 # Development Logs
+- Prepend new entries with `## Issue Analysis: YYYY-MM-DD`.
+- We write or explain to the damn point. Be clear, be super concise - no fluff, no hand-holding, no repeating.
+- Minimal markdown markers, no unnecessary formatting, minimal unicode emojis.
+
+## Issue Analysis: 2025-06-22
+
+### [problem-discovered] GitHub CLI auth fails in containers
+
+**Problem**: Mounting `~/.config/gh/` doesn't work for GitHub CLI authentication in containers.
+
+**Root Cause**: Modern `gh` uses secure keyring storage instead of plain text files:
+- **Host**: Tokens stored in macOS Keychain/Linux Secret Service/Windows Credential Manager
+- **Container**: No keyring access, auth fails even with mounted config directory
+- **Split State**: Config files present but tokens inaccessible
+
+**Technical Details**:
+```bash
+# Host auth state:
+~/.config/gh/config.yml     # Configuration
+~/.config/gh/hosts.yml      # May contain tokens OR keyring references
+System Keyring              # Actual tokens (secure storage)
+
+# Container reality:
+/root/.config/gh/config.yml # ✅ Mounted successfully
+/root/.config/gh/hosts.yml  # ✅ Mounted but may reference unavailable keyring
+No System Keyring          # ❌ DBus/keyring services not available
+```
+
+**Why This Matters**: Current codebase has complete auth system for Claude/AWS/GCloud but GitHub CLI missing.
+
+**Immediate Impact**: Cannot create PRs or manage GitHub repos from within containers.
+
+**Solutions Research**:
+1. **Environment Variable**: `GH_TOKEN="ghp_xxx"` - simple, headless-friendly
+2. **Insecure Storage**: `gh auth login --insecure-storage` on host, then mount works
+3. **Token Injection**: `echo $TOKEN | gh auth login --with-token` in container
+4. **Mount Strategy**: Add explicit GitHub CLI auth mounting to claude.sh
+
+**Status**: Research complete, need implementation decision.
+
+---
+
+## Issue Analysis: 2025-06-22
+
+### [enhancement] Controlled auth directory mounting
+
+**Problem**: Symlinking all /root/* was too broad and risky.
+
+**Better approach**: Explicit, controlled mounts with proper permissions:
+```bash
+# claude.sh mounts:
+~/.claude → /root/.claude          # read-write (auth tokens)
+~/.config → /root/.config:ro       # read-only (XDG tools)
+~/.aws → /root/.aws:ro            # read-only
+~/.ssh → /root/.ssh:ro            # read-only
+~/.gitconfig → /root/.gitconfig:ro # read-only
+
+# docker-entrypoint.sh:
+- Symlinks specific directories to /home/claude
+- Sets XDG_CONFIG_HOME=/root/.config
+- Maintains controlled access list
+```
+
+**Benefits**:
+- ✅ Security: Read-only where appropriate
+- ✅ XDG compliance: Entire .config dir for gh/gcloud/etc
+- ✅ Explicit: Clear what's accessible
+- ✅ Safe: No unexpected file exposure
+
+**Status**: -> **IMPLEMENTED**
+
+### [enhancement-implemented] Consolidate auth options to --auth-with pattern
+
+**Problem**: Auth flags conflict with common conventions (-v for volumes vs Vertex).
+
+**Current mess**:
+- `-c/--claude` → Claude app (OAuth)
+- `-a/--api-key` → Anthropic API
+- `-b/--bedrock` → AWS Bedrock
+- `-v/--vertex` → Google Vertex AI (blocks -v for volumes!)
+
+**Solution**: Single `--auth-with` parameter:
+```bash
+claude.sh --auth-with vertex .     # Explicit auth method
+claude.sh -v ~/.ssh:/root/.ssh .   # -v now free for volumes
+```
+
+**Implementation**:
+1. ✅ Added `--auth-with METHOD` parsing in claude.sh
+2. ✅ Kept old flags for backward compatibility (with deprecation warnings)
+3. ✅ Freed up `-v` for volume mounting (Docker convention)
+4. ✅ Updated claude-yolo to use `-v` instead of `--mount`
+
+**Benefits**:
+- ✅ Follows Docker convention (-v for volumes)
+- ✅ Cleaner, extensible auth interface
+- ✅ No more flag conflicts
+- ✅ Better CLI UX
+
+**Status**: ✅ **IMPLEMENTED**
+
+### [enhancement-implemented] Generalized config mounting
+
+**Problem**: Hardcoding each tool's config mount doesn't scale.
+
+**Root cause**: Mount to /root, run as claude user -> symlink hell.
+
+**Initial Proposal**: Mount entire ~/.config, use XDG standards.
+
+**Implemented Solution**: Added flexible volume mounting via `-v` argument in claude-yolo.
+
+```bash
+# New usage - users can mount any config they need:
+claude-yolo -v ~/.gitconfig:/root/.gitconfig .
+claude-yolo -v ~/.ssh:/root/.ssh:ro .
+claude-yolo -v ~/tools:/tools -v ~/data:/data .
+
+# Implementation in claude-yolo:
+- Parse -v/--mount arguments, collect in array
+- Pass to claude.sh via CLAUDE_EXTRA_VOLUMES env var
+- claude.sh adds these volumes to Docker run command
+```
+
+**Benefits**:
+- ✅ **Flexible**: Mount any config/directory as needed
+- ✅ **Familiar**: Uses Docker's -v syntax
+- ✅ **Secure**: Users control what to expose
+- ✅ **Extensible**: No hardcoded tool list to maintain
+
+**Result**: Zero maintenance. New tools work via explicit mounting.
+
+**Status**: ✅ **IMPLEMENTED** - Added -v/--mount support to claude-yolo
 
 ## Issue Analysis: 2025-06-22
 
 ### [bug-fixed] --trace flag doesn't pass --dangerously-skip-permissions in YOLO mode
 
 **Problem**: `claude-yolo --trace .` fails to add `--dangerously-skip-permissions` to the claude command.
 
-**Root Cause Found**: 
+**Root Cause Found**:
 - In `claude.sh:562`, when `--trace` is used, the command was incorrectly constructed as:
   ```bash
   claude-trace --include-all-requests --run-with .
@@ -17,11 +149,7 @@
 
 1. **Fixed command construction** in `claude.sh:562`:
    ```bash
-   # Before (broken):
-   DOCKER_ARGS+=("claude-trace" "--include-all-requests" "--run-with" "${CLAUDE_ARGS[@]}")
-   
-   # After (fixed):
-   DOCKER_ARGS+=("claude-trace" "--include-all-requests" "--run-with" "claude" "${CLAUDE_ARGS[@]}")
+   claude-trace --include-all-requests --run-with claude .
    ```
 
 2. **Enhanced argument injection** in `docker-entrypoint.sh`:
@@ -36,7 +164,7 @@
        done
    ```
 
-**Result**: 
+**Result**:
 - Input: `claude-yolo --trace .`
 - Command: `claude-trace --include-all-requests --run-with claude .`
 - Executed: `claude-trace --include-all-requests --run-with claude --dangerously-skip-permissions .`
@@ -49,7 +177,7 @@
 
 **Problem**: All dev tools are baked into Dockerfile, requiring full image rebuild for new tools.
 
-**Current State**: 
+**Current State**:
 - Tools installed in Dockerfile:92-117 (gh, delta, claude, claude-trace)
 - Static installation makes customization inflexible
 - Image size grows with every tool added
@@ -103,7 +231,7 @@ Cons: Multiple package manager complexity
 
 **Current Auth State**:
 - ✅ **Claude**: Auto-mounted via `~/.claude` → `/root/.claude` → `/home/claude/.claude` (symlink)
-- ✅ **AWS**: Auto-mounted via `~/.aws` → `/root/.aws` → `/home/claude/.aws` (symlink) 
+- ✅ **AWS**: Auto-mounted via `~/.aws` → `/root/.aws` → `/home/claude/.aws` (symlink)
 - ✅ **Google Cloud**: Auto-mounted via `~/.config/gcloud` → `/root/.config/gcloud` → `/home/claude/.config/gcloud` (symlink)
 - ❌ **GitHub CLI**: Requires manual `gh auth login` or token pasting into `/home/claude/.config/gh/`
 - ❌ **Docker Hub**: No auth mounting for `docker login`
@@ -118,7 +246,7 @@ Cons: Multiple package manager complexity
 ```bash
 # In claude.sh, add more auth directories
 [ -d "$HOME/.config/gh" ] && DOCKER_ARGS+=("-v" "$HOME/.config/gh:/root/.config/gh")
-[ -f "$HOME/.npmrc" ] && DOCKER_ARGS+=("-v" "$HOME/.npmrc:/root/.npmrc") 
+[ -f "$HOME/.npmrc" ] && DOCKER_ARGS+=("-v" "$HOME/.npmrc:/root/.npmrc")
 [ -d "$HOME/.docker" ] && DOCKER_ARGS+=("-v" "$HOME/.docker:/root/.docker")
 [ -d "$HOME/.terraform.d" ] && DOCKER_ARGS+=("-v" "$HOME/.terraform.d:/root/.terraform.d")
 ```
@@ -167,13 +295,13 @@ AUTH_PATHS=(
 
 ---
 
-### [enhancement-resolved] Multiple Claude instances workflow 
+### [enhancement-resolved] Multiple Claude instances workflow
 
 **Original Problem**: Users wanted multiple Claude instances in same project without container name conflicts.
 
 **Original Goal Misunderstanding**: We thought users wanted shared containers, but they actually just wanted **multiple simultaneous instances**.
 
-**Simple Solution Implemented**: 
+**Simple Solution Implemented**:
 - **Reverted to process-based naming**: `claude-code-yolo-${CURRENT_DIR_BASENAME}-$$`
 - **Keep `--rm` for auto-cleanup**: Each instance gets its own container
 - **No complexity needed**: Each process gets unique container name via `$$`
@@ -183,7 +311,7 @@ AUTH_PATHS=(
 # Terminal 1:
 claude-yolo .  # → claude-code-yolo-myproject-12345
 
-# Terminal 2: 
+# Terminal 2:
 claude-yolo .  # → claude-code-yolo-myproject-67890
 
 # Both run simultaneously, both auto-cleanup
@@ -213,7 +341,7 @@ claude-yolo .  # → claude-code-yolo-myproject-67890
 
 **Features Added**:
 - `claude-yolo --inspect`: Auto-find and enter container as claude user
-- `claude-yolo --ps`: List all containers for current project  
+- `claude-yolo --ps`: List all containers for current project
 - **Smart selection**: Auto-select single container, prompt for multiple
 - **Project-aware**: Only shows containers matching current directory pattern
 
@@ -241,7 +369,7 @@ fi
 **Before** (painful):
 ```bash
 docker ps                                    # Find container
-docker exec -it claude-code-yolo-proj-12345 /bin/zsh  # Enter container  
+docker exec -it claude-code-yolo-proj-12345 /bin/zsh  # Enter container
 su - claude                                  # Switch to proper user
 ```
 
@@ -256,7 +384,7 @@ claude-yolo --inspect
 
 Multiple containers found for this project:
   1) claude-code-yolo-myproject-12345 (Up 5 minutes)
-  2) claude-code-yolo-myproject-67890 (Up 2 minutes) 
+  2) claude-code-yolo-myproject-67890 (Up 2 minutes)
 
 Select container to inspect (1-2): 1
 Entering container claude-code-yolo-myproject-12345 as claude user...
@@ -269,68 +397,3 @@ Entering container claude-code-yolo-myproject-12345 as claude user...
 **Status**: ✅ **COMPLETED** - Issue #4 resolved
 
 ---
-
-## Current Implementation Summary
-
-### What We've Built
-
-**Issue #1**: ✅ Fixed `--trace` flag not passing `--dangerously-skip-permissions`
-- **Solution**: Added explicit `claude-trace` detection in `docker-entrypoint.sh:167,182`
-- **Result**: `claude-yolo --trace .` now works correctly in YOLO mode
-
-**Issue #4**: ✅ Added container inspection shortcuts
-- **Solution**: Enhanced `claude-yolo` with `--inspect` and `--ps` commands
-- **Result**: One-command container access with smart multi-container selection
-
-**Multiple Instances**: ✅ Simplified approach for concurrent Claude instances  
-- **Solution**: Reverted to process-based naming `$$` for unique containers
-- **Result**: Multiple `claude-yolo .` commands work simultaneously, auto-cleanup
-
-### Current Architecture
-
-**claude.sh** (578 lines):
-- Main Docker wrapper with authentication, environment setup, and container creation
-- Process-based container naming: `claude-code-yolo-${CURRENT_DIR_BASENAME}-$$`
-- Always uses `--rm` for auto-cleanup
-- Supports 4 auth modes: Claude app, API key, AWS Bedrock, Google Vertex AI
-
-**docker-entrypoint.sh** (194 lines):
-- Container initialization with environment reporting
-- Non-root user setup with proper UID/GID alignment
-- Authentication symlink creation (`/root/.claude` → `/home/claude/.claude`)
-- Fixed pattern matching for Claude commands (including `claude-trace`)
-
-**claude-yolo** (75 lines):
-- Enhanced wrapper with container inspection shortcuts
-- Smart container discovery and selection
-- Simple fallback to `claude.sh --yolo` for normal operations
-
-### Key Design Principles Applied
-
-1. **Simplicity over complexity**: Chose unique container names over shared containers
-2. **User experience focus**: One-command access for common operations
-3. **Pattern matching**: Project-aware container management
-4. **Auto-cleanup**: Containers remove themselves when done
-5. **Smart defaults**: Auto-select single containers, prompt for multiple
-
----
-
-## Technical Details
-
-### File Locations
-- Main wrapper: `claude.sh:559` (YOLO trace command)
-- Entrypoint logic: `docker-entrypoint.sh:167-169, 181-183` (dangerous permissions logic)
-- Tool installation: `Dockerfile:92-117` (static tool setup)
-
-### Key Functions
-- `claude.sh` line 557-562: Trace command construction
-- `docker-entrypoint.sh` line 156-189: Command execution with permission handling
-- `docker-entrypoint.sh` line 11-64: Environment reporting
-
----
-
-## Next Steps
-1. Create GitHub issues for both problems
-2. Implement trace flag fix (simple pattern matching)
-3. Design runtime tool installation system
-4. Consider adding `.claude-tools` config support

README.md

@@ -47,18 +47,56 @@ claude-yolo .                       # Run in current directory
 # Using claude.sh for more control
 claude.sh --yolo .                  # YOLO mode
 claude.sh .                         # Local mode (no Docker)
-claude.sh -a .                      # Use API key
-claude.sh -b .                      # Use AWS Bedrock
+claude.sh --auth-with api-key .     # Use API key
+claude.sh --auth-with bedrock .     # Use AWS Bedrock
+claude.sh --auth-with vertex .      # Use Google Vertex AI
 claude.sh --shell                   # Open shell in container
 claude.sh --help                    # Show all options
 ```
 
 ## Authentication Methods
 
-- **Claude App** (default): Uses `~/.claude` OAuth
-- **API Key** (`-a`): Set `ANTHROPIC_API_KEY` environment variable
-- **AWS Bedrock** (`-b`): Uses `~/.aws` credentials
-- **Google Vertex** (`-v`): Uses `~/.config/gcloud` credentials
+- **Claude App** (default): Uses `~/.claude` OAuth - `--auth-with claude`
+- **API Key**: Set `ANTHROPIC_API_KEY` environment variable - `--auth-with api-key`
+  - If OAuth exists, use `/login` in Claude to switch to API key auth
+- **AWS Bedrock**: Uses `~/.aws` credentials - `--auth-with bedrock`
+- **Google Vertex**: Uses `~/.config/gcloud` credentials - `--auth-with vertex`
+
+## GitHub CLI Authentication
+
+For GitHub operations (creating PRs, managing repos), set the `GH_TOKEN` environment variable:
+
+```bash
+# Set your GitHub token
+export GH_TOKEN="ghp_xxxxxxxxxxxx"
+
+# Now gh commands work in containers
+claude-yolo .
+# Inside container: gh pr create, gh issue list, etc.
+```
+
+**Note**: This avoids mounting `~/.config/gh/` which fails due to secure keyring storage in modern GitHub CLI versions.
+
+## Custom Volume Mounting
+
+You can mount additional configuration files or directories using the `-v` flag:
+
+```bash
+# Mount Git configuration
+claude-yolo -v ~/.gitconfig:/root/.gitconfig .
+
+# Mount SSH keys (read-only)
+claude-yolo -v ~/.ssh:/root/.ssh:ro .
+
+# Multiple mounts
+claude-yolo -v ~/tools:/tools -v ~/data:/data .
+
+# Mount custom tool configs
+claude-yolo -v ~/.config/gh:/root/.config/gh .
+claude-yolo -v ~/.terraform.d:/root/.terraform.d .
+```
+
+**Note**: Volumes mounted to `/root/*` are automatically symlinked to `/home/claude/*` for non-root user access.
 
 ## Key Features
 
@@ -88,3 +126,4 @@ make build
 - **[meal/claude-code-cli](https://github.com/meal/claude-code-cli)** - Containerized Claude Code with ready-to-use Docker setup
 - **[gagarinyury/claude-code-root-runner](https://github.com/gagarinyury/claude-code-root-runner)** - Root privilege bypass for Claude Code using temporary users
 - **[textcortex/claude-code-sandbox](https://github.com/textcortex/claude-code-sandbox)** - Full sandbox environment with web UI and autonomous workflows
+