Harden proxy auth, storage, and conversation access

README.md

@@ -21,6 +21,13 @@ Claude Code Proxy serves three main purposes:
 - **Conversation Analysis**: View full conversation threads with tool usage
 - **Easy Setup**: One-command startup for both services
 
+## Security Defaults
+
+- The proxy binds to `127.0.0.1` by default for local-only access.
+- CORS defaults are restricted to localhost origins.
+- If you want to expose the proxy on a public interface, you must set `AUTH_ENABLED=true` and provide `AUTH_TOKEN`.
+- When auth is enabled, the proxy accepts either `Authorization: Bearer <token>` or `X-API-Key: <token>`.
+
 ## Quick Start
 
 ### Prerequisites
@@ -75,16 +82,25 @@ Claude Code Proxy serves three main purposes:
    # Build the image
    docker build -t claude-code-proxy .
    
-   # Run with default settings
-   docker run -p 3001:3001 -p 5173:5173 claude-code-proxy
+   # Run locally without publishing ports
+   docker run claude-code-proxy
+
+   # Run with published ports
+   docker run -p 3001:3001 -p 5173:5173 \
+     -e SERVER_HOST=0.0.0.0 \
+     -e AUTH_ENABLED=true \
+     -e AUTH_TOKEN=change-me \
+     claude-code-proxy
    ```
 
 4. **Run with persistent data and custom configuration**
    ```bash
    # Create a data directory for persistent SQLite database
    mkdir -p ./data
-   
+
    # Option 1: Run with config file (recommended)
+   # If you expose the container with `-p`, set server.host to 0.0.0.0
+   # and enable auth in the mounted config file.
    docker run -p 3001:3001 -p 5173:5173 \
      -v ./data:/app/data \
      -v ./config.yaml:/app/config.yaml:ro \
@@ -93,9 +109,11 @@ Claude Code Proxy serves three main purposes:
    # Option 2: Run with environment variables
    docker run -p 3001:3001 -p 5173:5173 \
      -v ./data:/app/data \
+     -e SERVER_HOST=0.0.0.0 \
      -e ANTHROPIC_FORWARD_URL=https://api.anthropic.com \
+     -e AUTH_ENABLED=true \
+     -e AUTH_TOKEN=change-me \
      -e PORT=3001 \
-     -e WEB_PORT=5173 \
      claude-code-proxy
    ```
 
@@ -113,9 +131,11 @@ Claude Code Proxy serves three main purposes:
          - ./data:/app/data
          - ./config.yaml:/app/config.yaml:ro  # Mount config file
        environment:
+         - SERVER_HOST=0.0.0.0
          - ANTHROPIC_FORWARD_URL=https://api.anthropic.com
+         - AUTH_ENABLED=true
+         - AUTH_TOKEN=change-me
          - PORT=3001
-         - WEB_PORT=5173
          - DB_PATH=/app/data/requests.db
    ```
    
@@ -169,6 +189,7 @@ make help       # Show all commands
 Create a `config.yaml` file (or copy from `config.yaml.example`):
 ```yaml
 server:
+  host: 127.0.0.1
   port: 3001
 
 providers:
@@ -180,6 +201,32 @@ providers:
 
 storage:
   db_path: "requests.db"
+
+auth:
+  enabled: false
+  token: ""
+```
+
+### Auth
+
+To expose the proxy beyond localhost, enable auth and provide a token:
+
+```yaml
+auth:
+  enabled: true
+  token: "change-me"
+```
+
+Then send either:
+
+```bash
+curl -H "Authorization: Bearer change-me" http://localhost:3001/v1/models
+```
+
+or:
+
+```bash
+curl -H "X-API-Key: change-me" http://localhost:3001/v1/models
 ```
 
 ### Subagent Configuration (Optional)
@@ -241,6 +288,11 @@ Use case: Different specialists for different tasks, optimizing for speed/cost/q
 
 Override config via environment:
 - `PORT` - Server port
+- `SERVER_HOST` - Server bind host
+- `AUTH_ENABLED` - Enable auth for non-health endpoints
+- `AUTH_TOKEN` - Shared auth secret
+- `AUTH_API_KEY_HEADER` - Header name for API key auth
+- `AUTH_ALLOW_LOCALHOST_BYPASS` - Allow localhost requests to bypass auth
 - `OPENAI_API_KEY` - OpenAI API key
 - `DB_PATH` - Database path
 - `SUBAGENT_MAPPINGS` - Comma-separated mappings (e.g., `"code-reviewer:gpt-4o,data-analyst:o3"`)
@@ -251,22 +303,27 @@ All environment variables can be configured when running the Docker container:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
+| `SERVER_HOST` | `127.0.0.1` | Proxy bind host |
 | `PORT` | `3001` | Proxy server port |
-| `WEB_PORT` | `5173` | Web dashboard port |
 | `READ_TIMEOUT` | `600` | Server read timeout (seconds) |
 | `WRITE_TIMEOUT` | `600` | Server write timeout (seconds) |
 | `IDLE_TIMEOUT` | `600` | Server idle timeout (seconds) |
 | `ANTHROPIC_FORWARD_URL` | `https://api.anthropic.com` | Target Anthropic API URL |
 | `ANTHROPIC_VERSION` | `2023-06-01` | Anthropic API version |
 | `ANTHROPIC_MAX_RETRIES` | `3` | Maximum retry attempts |
+| `AUTH_ENABLED` | `false` | Enable auth for non-health endpoints |
+| `AUTH_TOKEN` | `""` | Shared auth token |
+| `AUTH_API_KEY_HEADER` | `x-api-key` | Header name for API-key style auth |
+| `AUTH_ALLOW_LOCALHOST_BYPASS` | `true` | Allow loopback requests to bypass auth |
 | `DB_PATH` | `/app/data/requests.db` | SQLite database path |
 
 Example with custom configuration:
 ```bash
 docker run -p 3001:3001 -p 5173:5173 \
   -v ./data:/app/data \
-  -e PORT=8080 \
-  -e WEB_PORT=3000 \
+  -e SERVER_HOST=0.0.0.0 \
+  -e AUTH_ENABLED=true \
+  -e AUTH_TOKEN=change-me \
   -e ANTHROPIC_FORWARD_URL=https://api.anthropic.com \
   -e DB_PATH=/app/data/custom.db \
   claude-code-proxy