feat: add configurable working directory with isolated default (#14)

- Default to temporary directory for security isolation
- Validate directory existence before use (fail gracefully)
- Support CLAUDE_CWD environment variable for custom directories
- Add comprehensive cross-platform tests
- Update Docker configuration for workspace mounting
- Add clear documentation for all configuration options

This prevents Claude Code from accessing the wrapper's source code
by default, enhancing security while maintaining flexibility.

Co-authored-by: George Elphick <george.elphick@talieisin.co.uk>

Author: aquabubble

README.md

@@ -143,8 +143,40 @@ MAX_TIMEOUT=600000
 
 # CORS origins
 CORS_ORIGINS=["*"]
+
+# Working directory for Claude Code (optional)
+# If not set, uses an isolated temporary directory for security
+# CLAUDE_CWD=/path/to/your/workspace
 ```
 
+### 📁 **Working Directory Configuration**
+
+By default, Claude Code runs in an **isolated temporary directory** to prevent it from accessing the wrapper's source code. This enhances security by ensuring Claude Code only has access to the workspace you intend.
+
+**Configuration Options:**
+
+1. **Default (Recommended)**: Automatically creates a temporary isolated workspace
+   ```bash
+   # No configuration needed - secure by default
+   poetry run python main.py
+   ```
+
+2. **Custom Directory**: Set a specific workspace directory
+   ```bash
+   export CLAUDE_CWD=/path/to/your/project
+   poetry run python main.py
+   ```
+
+3. **Via .env file**: Add to your `.env` file
+   ```env
+   CLAUDE_CWD=/home/user/my-workspace
+   ```
+
+**Important Notes:**
+- The temporary directory is automatically cleaned up when the server stops
+- This prevents Claude Code from accidentally modifying the wrapper's own code
+- Cross-platform compatible (Windows, macOS, Linux)
+
 ### 🔐 **API Security Configuration**
 
 The server supports **interactive API key protection** for secure remote access:
@@ -246,7 +278,7 @@ RATE_LIMIT_HEALTH_PER_MINUTE=30
 
 This guide provides a comprehensive overview of building, running, and configuring a Docker container for the Claude Code OpenAI Wrapper. Docker enables isolated, portable, and reproducible deployments of the wrapper, which acts as an OpenAI-compatible API server routing requests to Anthropic's Claude models via the official Claude Code Python SDK (v0.0.14+). This setup supports authentication methods like Claude subscriptions (e.g., Max plan via OAuth for fixed-cost quotas), direct API keys, AWS Bedrock, or Google Vertex AI.
 
-By containerizing the application, you can run it locally for development, deploy it to remote servers or cloud platforms, and customize behavior through environment variables and volumes. This guide assumes you have already cloned the repository and have the `Dockerfile` in the root directory. For general repository setup (e.g., Claude Code CLI authentication), refer to the sections above.
+By containerizing the application, you can run it locally for development, deploy it to remote servers or cloud platforms, and customise behaviour through environment variables and volumes. This guide assumes you have already cloned the repository and have the `Dockerfile` in the root directory. For general repository setup (e.g., Claude Code CLI authentication), refer to the sections above.
 
 ## Prerequisites
 Before building or running the container, ensure the following:
@@ -255,7 +287,7 @@ Before building or running the container, ensure the following:
 - **Hardware and Software**:
   - OS: macOS (10.15+), Linux (e.g., Ubuntu 20.04+), or Windows (10+ with WSL2 for optimal volume mounting).
   - Resources: At least 4GB RAM and 2 CPU cores (Claude requests can be compute-intensive; monitor with `docker stats`).
-  - Disk: ~500MB for the image, plus space for volumes.
+  - Disc: ~500MB for the image, plus space for volumes.
   - Network: Stable internet for builds (dependency downloads) and runtime (API calls to Anthropic).
 - **Optional**:
   - Docker Compose: For multi-service or easier configuration management. Install via Docker Desktop or your package manager (e.g., `sudo apt install docker-compose`).
@@ -283,7 +315,7 @@ The `Dockerfile` in the root defines a lightweight Python 3.12-based image with
 4. Advanced Build Options:
    - No Cache (for fresh builds): `docker build --no-cache -t claude-wrapper:latest .`.
    - Platform-Specific (e.g., ARM for Raspberry Pi): `docker build --platform linux/arm64 -t claude-wrapper:arm .`.
-   - Multi-Stage for Smaller Size: If optimizing, modify the Dockerfile to use multi-stage builds (e.g., separate build and runtime stages).
+   - Multi-Stage for Smaller Size: If optimising, modify the Dockerfile to use multi-stage builds (e.g., separate build and runtime stages).
 
 If using Docker Compose (see below), build with `docker-compose build`.
 
@@ -301,6 +333,20 @@ docker run -d -p 8000:8000 \
 - `-d`: Detached mode (runs in background).
 - `-p 8000:8000`: Maps host port 8000 to the container's 8000 (change left side for host conflicts, e.g., `-p 9000:8000`).
 - `-v ~/.claude:/root/.claude`: Mounts your host's authentication directory for persistent subscription tokens (essential for Claude Max access).
+- **Working Directory**: By default, Claude Code uses an isolated temp directory inside the container.
+
+### Running with Custom Workspace
+To give Claude Code access to a specific directory:
+```bash
+docker run -d -p 8000:8000 \
+  -v ~/.claude:/root/.claude \
+  -v /path/to/your/project:/workspace \
+  -e CLAUDE_CWD=/workspace \
+  --name claude-wrapper-container \
+  claude-wrapper:latest
+```
+- `-v /path/to/your/project:/workspace`: Mounts your project directory into the container.
+- `-e CLAUDE_CWD=/workspace`: Sets Claude's working directory to the mounted workspace.
 - `--name claude-wrapper-container`: Names the container for easy management.
 
 ### Development Run with Hot Reload
@@ -345,20 +391,21 @@ services:
 - Cleanup: `docker system prune` to remove unused images/volumes.
 
 ## Custom Configuration Options
-Customize the container's behavior through environment variables, volumes, and runtime flags. Most changes don't require rebuilding—just restart the container.
+Customise the container's behaviour through environment variables, volumes, and runtime flags. Most changes don't require rebuilding—just restart the container.
 
 ### Environment Variables
-Env vars override defaults and can be set at runtime with `-e` flags or in `docker-compose.yml` under `environment`. They control auth, server settings, and SDK behavior.
+Env vars override defaults and can be set at runtime with `-e` flags or in `docker-compose.yml` under `environment`. They control auth, server settings, and SDK behaviour.
 
 - **Core Server Settings**:
   - `PORT=9000`: Changes the internal listening port (default: 8000; update port mapping accordingly).
   - `MAX_TIMEOUT=600`: Sets the request timeout in seconds (default: 300; increase for complex Claude queries).
+  - `CLAUDE_CWD=/path/to/workspace`: Sets Claude Code's working directory (default: isolated temp directory for security).
 
 - **Authentication and Providers**:
   - `ANTHROPIC_API_KEY=sk-your-key`: Enables direct API key auth (overrides subscription; generate at console.anthropic.com).
   - `CLAUDE_CODE_USE_VERTEX=true`: Switches to Google Vertex AI (requires additional vars like `GOOGLE_APPLICATION_CREDENTIALS=/path/to/creds.json`—mount the file as a volume).
   - `CLAUDE_CODE_USE_BEDROCK=true`: Enables AWS Bedrock (set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, etc.).
-  - `CLAUDE_USE_SUBSCRIPTION=true`: Forces subscription mode (default behavior; set to ensure no API fallback).
+  - `CLAUDE_USE_SUBSCRIPTION=true`: Forces subscription mode (default behaviour; set to ensure no API fallback).
 
 - **Security and API Protection**:
   - `API_KEYS=key1,key2`: Comma-separated list of API keys required for endpoint access (clients must send `Authorization: Bearer <key>`).
@@ -375,7 +422,7 @@ docker run ... -e PORT=9000 -e ANTHROPIC_API_KEY=sk-your-key ...
 
 For persistence across runs, use a `.env` file in the root (e.g., `PORT=8000`) and mount it: `-v $(pwd)/.env:/app/.env`. Load vars in code if required.
 
-### Volumes for Data Persistence and Customization
+### Volumes for Data Persistence and Customisation
 Volumes mount host directories/files into the container, enabling persistence and config overrides.
 
 - **Authentication Volume (Required for Subscriptions)**: `-v ~/.claude:/root/.claude` – Shares tokens and `settings.json` (edit on host for defaults like `"max_tokens": 8192`; restart container to apply).
@@ -401,7 +448,7 @@ For remote access (e.g., from other machines or production deployment), extend t
 ### Exposing Locally for Remote Access
 - Bind to All Interfaces: Already done with `--host 0.0.0.0`.
 - Firewall: Open port 8000 on your host (e.g., `ufw allow 8000` on Ubuntu).
-- Tunneling: Use ngrok for temporary exposure: Install ngrok, run `ngrok http 8000`, and use the public URL.
+- Tunnelling: Use ngrok for temporary exposure: Install ngrok, run `ngrok http 8000`, and use the public URL.
 - Security: Always add `API_KEYS` and use HTTPS (via reverse proxy).
 
 ### Deploying to a Remote Server or VPS
@@ -512,7 +559,7 @@ response = client.chat.completions.create(
 )
 
 print(response.choices[0].message.content)
-# Output: Fast response without tool usage (default behavior)
+# Output: Fast response without tool usage (default behaviour)
 
 # Enable tools when you need them (e.g., to read files)
 response = client.chat.completions.create(
@@ -600,7 +647,7 @@ curl -X POST http://localhost:8000/v1/chat/completions \
   -H "Content-Type: application/json" \
   -d '{
     "model": "claude-3-5-sonnet-20241022",
-    "messages": [{"role": "user", "content": "My favorite color is blue."}],
+    "messages": [{"role": "user", "content": "My favourite color is blue."}],
     "session_id": "my-session"
   }'
 
@@ -609,7 +656,7 @@ curl -X POST http://localhost:8000/v1/chat/completions \
   -H "Content-Type: application/json" \
   -d '{
     "model": "claude-3-5-sonnet-20241022", 
-    "messages": [{"role": "user", "content": "What's my favorite color?"}],
+    "messages": [{"role": "user", "content": "What's my favourite color?"}],
     "session_id": "my-session"
   }'
 ```
@@ -748,9 +795,9 @@ All tests should show:
 - **Real cost tracking** (e.g., $0.001-0.005 per test call)
 - **Accurate token counts** from SDK metadata
 
-## License
+## Licence
 
-MIT License
+MIT Licence
 
 ## Contributing
 

claude_cli.py

@@ -1,6 +1,9 @@
 import asyncio
 import json
 import os
+import tempfile
+import atexit
+import shutil
 from typing import AsyncGenerator, Dict, Any, Optional, List
 from pathlib import Path
 import logging
@@ -13,7 +16,27 @@
 class ClaudeCodeCLI:
     def __init__(self, timeout: int = 600000, cwd: Optional[str] = None):
         self.timeout = timeout / 1000  # Convert ms to seconds
-        self.cwd = Path(cwd) if cwd else Path.cwd()
+        self.temp_dir = None
+        
+        # If cwd is provided (from CLAUDE_CWD env var), use it
+        # Otherwise create an isolated temp directory
+        if cwd:
+            self.cwd = Path(cwd)
+            # Check if the directory exists
+            if not self.cwd.exists():
+                logger.error(f"ERROR: Specified working directory does not exist: {self.cwd}")
+                logger.error(f"Please create the directory first or unset CLAUDE_CWD to use a temporary directory")
+                raise ValueError(f"Working directory does not exist: {self.cwd}")
+            else:
+                logger.info(f"Using CLAUDE_CWD: {self.cwd}")
+        else:
+            # Create isolated temp directory (cross-platform)
+            self.temp_dir = tempfile.mkdtemp(prefix="claude_code_workspace_")
+            self.cwd = Path(self.temp_dir)
+            logger.info(f"Using temporary isolated workspace: {self.cwd}")
+            
+            # Register cleanup function to remove temp dir on exit
+            atexit.register(self._cleanup_temp_dir)
 
         # Import auth manager
         from auth import auth_manager, validate_claude_code_auth
@@ -233,4 +256,13 @@ def extract_metadata(self, messages: List[Dict[str, Any]]) -> Dict[str, Any]:
                     "model": message.get("model")
                 })
 
-        return metadata
+        return metadata
+    
+    def _cleanup_temp_dir(self):
+        """Clean up temporary directory on exit."""
+        if self.temp_dir and os.path.exists(self.temp_dir):
+            try:
+                shutil.rmtree(self.temp_dir)
+                logger.info(f"Cleaned up temporary workspace: {self.temp_dir}")
+            except Exception as e:
+                logger.warning(f"Failed to clean up temp directory {self.temp_dir}: {e}")

docker-compose.yml

@@ -6,5 +6,11 @@ services:
       - "8000:8000"
     volumes:
       - ~/.claude:/root/.claude
+      # Optional: Mount a specific workspace directory
+      # Uncomment and modify the line below to use a custom workspace
+      # - ./workspace:/workspace
     environment:
       - PORT=8000
+      # Optional: Set Claude's working directory (defaults to isolated temp dir)
+      # Uncomment and modify the line below to set a custom working directory
+      # - CLAUDE_CWD=/workspace

test_docker_workspace.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Test script to verify working directory configuration in Docker
+
+echo "Testing Docker workspace configuration..."
+echo "========================================="
+
+# Test 1: Default (temp directory)
+echo -e "\n1. Testing default configuration (isolated temp dir):"
+docker run --rm \
+  -v ~/.claude:/root/.claude \
+  claude-wrapper:test \
+  poetry run python -c "from claude_cli import ClaudeCodeCLI; cli = ClaudeCodeCLI(); print(f'Working directory: {cli.cwd}'); print(f'Is temp dir: {cli.temp_dir is not None}')"
+
+# Test 2: With CLAUDE_CWD environment variable
+echo -e "\n2. Testing with CLAUDE_CWD environment variable:"
+docker run --rm \
+  -v ~/.claude:/root/.claude \
+  -e CLAUDE_CWD=/app \
+  claude-wrapper:test \
+  poetry run python -c "import os; from claude_cli import ClaudeCodeCLI; cli = ClaudeCodeCLI(cwd=os.getenv('CLAUDE_CWD')); print(f'Working directory: {cli.cwd}'); print(f'Is temp dir: {cli.temp_dir is not None}')"
+
+# Test 3: With mounted workspace
+echo -e "\n3. Testing with mounted workspace:"
+mkdir -p /tmp/test_workspace
+docker run --rm \
+  -v ~/.claude:/root/.claude \
+  -v /tmp/test_workspace:/workspace \
+  -e CLAUDE_CWD=/workspace \
+  claude-wrapper:test \
+  poetry run python -c "import os; from claude_cli import ClaudeCodeCLI; cli = ClaudeCodeCLI(cwd=os.getenv('CLAUDE_CWD')); print(f'Working directory: {cli.cwd}'); print(f'Directory exists: {os.path.exists(cli.cwd)}')"
+
+echo -e "\n========================================="
+echo "Docker workspace tests complete!"