Claude Code Proxy Installer

A bash script that installs sing-box to automatically route Claude Code traffic through your proxy server using TUN-level interception. Works seamlessly with 1Password integration or manual credential entry.

Repository: github.com/AbdelElrafa/claude-code-proxy-installer

Features

• 🔐 1Password Integration: Automatically pulls proxy credentials from 1Password
• 🔒 Manual Mode: Option to enter credentials manually (stored securely)
• 🎯 Per-Application Routing: Only Claude traffic goes through proxy, other apps unaffected
• 🚀 Auto-Start: Wrapper script automatically starts proxy if not running
• 🛡️ TUN-Level Interception: Uses sing-box for reliable traffic interception (works even when Claude ignores env vars)
• 📊 Logging: View Claude traffic logs in real-time
• 🔄 Automatic PATH Setup: Adds ~/bin to your PATH automatically

How It Works

1. sing-box: Installs and configures sing-box, a universal proxy platform
2. TUN Interface: Creates a virtual network interface that intercepts traffic at the system level
3. Process Matching: Routes only Claude processes (claude, com.anthropic.claude-code) through proxy
4. Auto-Start: Wrapper script ensures proxy is running before launching Claude

Prerequisites

• macOS (Linux support coming soon)
• Claude Code installed at ~/.local/bin/claude
• Homebrew (for installing sing-box)
• For 1Password mode: 1Password CLI (op) installed and signed in
• For manual mode: No additional requirements

Quick Start

Option 1: Using 1Password (Recommended)

1. Create a 1Password item named Claude Code Proxy with these custom fields:

   • host - Proxy server hostname/IP (required)
   • port - Proxy server port number (required)
   • username - Proxy username (optional)
   • password - Proxy password (optional)
   • type - Proxy type: socks5 or http (optional, defaults to socks5)

2. Install:

   curl -fsSL https://raw.githubusercontent.com/AbdelElrafa/claude-code-proxy-installer/main/install-claude-code-proxy.sh | bash

3. Restart your terminal or run:

   source ~/.zshrc

4. Use Claude:

   claude

   The proxy will automatically start if not running (may prompt for sudo password).

Option 2: Manual Credentials

1. Install with manual mode:

   curl -fsSL https://raw.githubusercontent.com/AbdelElrafa/claude-code-proxy-installer/main/install-claude-code-proxy.sh | bash -s -- --manual

2. Enter your proxy credentials when prompted:

   • Proxy type (socks5 or http, defaults to socks5)
   • Host
   • Port
   • Username (optional)
   • Password (optional)

3. Restart your terminal or run:

   source ~/.zshrc

4. Use Claude:

   claude

Installation Options

Auto-install 1Password CLI

If you don't have 1Password CLI installed:

# macOS (requires Homebrew)
curl -fsSL https://raw.githubusercontent.com/AbdelElrafa/claude-code-proxy-installer/main/install-claude-code-proxy.sh | bash -s -- --install-op

# With auto-yes (no prompts)
curl -fsSL https://raw.githubusercontent.com/AbdelElrafa/claude-code-proxy-installer/main/install-claude-code-proxy.sh | bash -s -- --install-op --yes

Proxy Management

The installer creates a claude-proxy command for managing the proxy:

# Start proxy (foreground, shows logs)
claude-proxy start

# Start proxy in background
claude-proxy start-bg

# Stop proxy
claude-proxy stop

# Restart proxy
claude-proxy restart

# Check if proxy is running
claude-proxy status

# View Claude traffic logs
claude-proxy logs

# View all logs
claude-proxy logs-all

# Test proxy connection
claude-proxy test

# Regenerate config from 1Password (1Password mode only)
claude-proxy regenerate

Updating Credentials

1Password Mode

Update the fields in your 1Password item "Claude Code Proxy", then regenerate the config:

claude-proxy regenerate

Or restart the proxy:

claude-proxy restart

Manual Mode

Option 1: Edit the config file directly:

nano ~/.claude-proxy-config

Then restart the proxy:

claude-proxy restart

Option 2: Re-run installer with --manual:

curl -fsSL https://raw.githubusercontent.com/AbdelElrafa/claude-code-proxy-installer/main/install-claude-code-proxy.sh | bash -s -- --manual

Troubleshooting

"Claude binary not found"

The script expects Claude at ~/.local/bin/claude. If it's elsewhere, you'll need to modify the installer script.

"1Password item not found"

1. Ensure you're signed into 1Password CLI: op signin
2. Create an item named exactly Claude Code Proxy
3. Add custom fields: host, port (required), username, password, type (optional)

"op not found"

Install 1Password CLI:

• macOS: brew install --cask 1password-cli
• Linux: Follow 1Password CLI installation guide

Proxy not starting

1. Check config validity:

   sing-box check --config ~/.config/sing-box/config.json

2. Check logs:

   cat ~/.config/sing-box/sing-box.log

3. Try starting manually:

   sudo sing-box run --config ~/.config/sing-box/config.json

Claude traffic not going through proxy

1. Verify proxy is running:

   claude-proxy status

2. Check logs for Claude process detection:

   claude-proxy logs

3. Verify process name matches:

   • Check if Claude binary path matches: ~/.local/share/claude/versions/*
   • The config matches processes named claude or com.anthropic.claude-code

Wrapper not found after installation

1. Ensure ~/bin is in your PATH:

   echo $PATH | grep -q "$HOME/bin" && echo "✅ In PATH" || echo "❌ Not in PATH"

2. Restart your terminal or source your shell config:

   source ~/.zshrc

3. Verify:

   which claude  # Should show ~/bin/claude

Permission denied (sudo)

The proxy requires sudo to create the TUN interface. You'll be prompted for your password when:

• Starting the proxy manually: claude-proxy start
• Auto-starting via the wrapper: claude

Files Created

• ~/bin/claude - Wrapper script (auto-starts proxy)
• ~/bin/claude-proxy - Proxy management script
• ~/.config/sing-box/config.json - sing-box configuration
• ~/.config/sing-box/sing-box.log - Proxy logs
• ~/.claude-proxy-config - Manual credentials (manual mode only)

Uninstallation

To remove everything:

# Stop proxy
claude-proxy stop

# Remove scripts
rm ~/bin/claude
rm ~/bin/claude-proxy

# Remove config and logs
rm -rf ~/.config/sing-box

# Remove manual credentials (if using manual mode)
rm ~/.claude-proxy-config

# Uninstall sing-box (optional)
brew uninstall sing-box

Security Notes

• ✅ Proxy credentials are stored securely:
  • 1Password mode: Credentials stay in 1Password (encrypted)
  • Manual mode: Config file has 600 permissions (owner read/write only)
• ✅ Only Claude traffic is routed through proxy (other apps unaffected)
• ✅ TUN-level interception works even when apps ignore environment variables
• ⚠️ Manual credentials are stored in plaintext (but with restricted permissions)
• ⚠️ Proxy requires sudo to create TUN interface (standard for VPN-like tools)

Technical Details

• sing-box: Universal proxy platform using TUN interface for system-level interception
• Process Matching: Uses process_name and process_path_regex to match Claude processes
• DNS Hijacking: Intercepts DNS requests to prevent leaks
• Strict Routing: Only matched processes go through proxy, everything else uses direct connection

Support

For issues or questions, contact your team lead or IT support.

License

Internal use only.