Claude Code on Windows: Complete WSL2 + CodeGateway Setup Guide

Claude Code on Windows: WSL2 Setup + CodeGateway Configuration

TL;DR: Claude Code doesn't run natively on Windows — you'll need WSL2 (Windows Subsystem for Linux). Once you're inside Ubuntu on WSL2, install Claude Code, then swap the API endpoint to CodeGateway to resolve unsupported region and connection timeout errors immediately. The whole setup takes about 20 minutes.

Prerequisites

Before you begin, make sure you have:

Why WSL2? Claude Code is a Node.js CLI tool that relies on Unix-style process management and shell features that don't translate cleanly to Windows CMD or PowerShell. WSL2 gives you a real Linux kernel without dual-booting.

Step 1: Install WSL2 + Ubuntu

Option A: One-command install (recommended)

Open PowerShell as Administrator (right-click → Run as administrator) and run:

wsl --install

This single command:

• Enables the WSL and Virtual Machine Platform Windows features

• Downloads and installs Ubuntu (latest LTS)

• Sets WSL2 as the default version

Restart your machine when prompted. After restart, Ubuntu finishes setup automatically and asks you to create a Linux username and password (independent of your Windows credentials).

Option B: Install a specific Ubuntu version

# List available distributions
wsl --list --online

# Install Ubuntu 22.04 specifically
wsl --install -d Ubuntu-22.04

Verify WSL2 is active

wsl --list --verbose

Expected output:

  NAME      STATE           VERSION
* Ubuntu    Running         2

If VERSION shows 1, upgrade it:

wsl --set-default-version 2
wsl --set-version Ubuntu 2

Step 2: Install Node.js in WSL2

Open your Ubuntu terminal (search "Ubuntu" or "WSL" in the Windows Start menu), then run:

# Update package lists
sudo apt update && sudo apt upgrade -y

# Install curl (usually pre-installed)
sudo apt install -y curl

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload shell config
source ~/.bashrc

# Install the latest LTS Node.js
nvm install --lts
nvm use --lts

# Verify
node --version   # should print v22.x.x or later
npm --version    # should print 10.x.x or later

Quick test: We tested this on Ubuntu 22.04 running on WSL2. The nvm install --lts step completed in about 90 seconds on a standard home connection. Node reported v22.11.0 and npm 10.9.2.

Step 3: Install Claude Code

With Node.js ready, install Claude Code globally:

npm install -g @anthropic-ai/claude-code

# Verify
claude --version

Expected output:

@anthropic-ai/claude-code/1.x.x linux-x64 node-v22.x.x

Troubleshooting permission errors

If you see EACCES: permission denied, configure npm's global directory first:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Step 4: Sign Up for CodeGateway and Get Your API Key

1. Go to codegateway.dev and create an account (email or GitHub login)

2. You'll receive $2 in free credits automatically — enough to test dozens of Claude interactions

3. Navigate to Dashboard → API Keys → Create New Key

4. Copy the key (format: cgw-xxxxxxxxxx) — it's only shown once, so save it immediately

Pricing: Pay-as-you-go, no subscription. Top up in any whole dollar amount from $5 to $10,000. Billing is per token at 1.35× model cost (rate decreases with volume). Supports the full Claude and OpenAI model catalog.

Step 5: Configure Claude Code to Use CodeGateway

Claude Code reads two environment variables to determine where to send API requests:

• ANTHROPIC_API_KEY — your API key

• ANTHROPIC_BASE_URL — the API endpoint

Option A: Temporary (current terminal session only)

export ANTHROPIC_API_KEY="cgw-your-key-here"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
claude

Option B: Permanent (recommended)

Add these lines to ~/.bashrc:

nano ~/.bashrc

Append at the end:

# CodeGateway API configuration
export ANTHROPIC_API_KEY="cgw-your-key-here"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"

Save (Ctrl+O → Enter → Ctrl+X) and reload:

source ~/.bashrc

Option C: Per-project .env file

For projects where you want isolated configuration:

cd /your/project/directory
cat > .env << 'EOF'
ANTHROPIC_API_KEY=cgw-your-key-here
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1
EOF

Claude Code automatically picks up .env files in the working directory.

Step 6: Verify the Setup

Launch Claude Code from any directory:

claude

You should see the Claude Code interactive UI start up. Try a quick test:

> Write a one-line Python hello world

If you get a response, you're live.

To confirm you're actually routing through CodeGateway (not the official endpoint), check what your environment variables resolve to:

echo "Key prefix: ${ANTHROPIC_API_KEY:0:6}"
echo "Endpoint: $ANTHROPIC_BASE_URL"

Expected:

Key prefix: cgw-xx
Endpoint: https://api.codegateway.dev/v1

Troubleshooting

Deep Dive

Diagnosing Slow Response Times

If Claude Code feels slow, run a quick latency check:

time curl -s -o /dev/null https://api.codegateway.dev/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY"

Under 300ms is normal. If you see 1000ms+, your network path to the nearest Cloudflare PoP may be suboptimal — try on a different network (e.g., mobile hotspot) to isolate whether it's your ISP.

Verifying the Correct Endpoint is Active

# Should print your CodeGateway key details, not Anthropic's
curl https://api.codegateway.dev/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" | python3 -m json.tool | head -20

If you see {"error": "invalid_api_key"}, double-check that ANTHROPIC_API_KEY is set to a cgw- prefixed key, not an sk-ant- Anthropic key.

WSL2 Network Isolation Issues

WSL2 runs in a lightweight VM with its own network stack. Occasionally DNS or routing can drift from Windows settings. If you hit connection issues only in WSL2:

# Check DNS resolution
nslookup api.codegateway.dev

# If DNS fails, temporarily override
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# Verify connectivity
curl -I https://api.codegateway.dev

"Virtualization is not enabled in firmware"

You need to enable Intel VT-x or AMD SVM in your BIOS/UEFI.

• Restart and press F2, Del, or F10 (varies by motherboard) to enter BIOS

• Look for "Virtualization Technology", "VT-x", or "SVM Mode"

• Set it to Enabled

• Save and exit

connection timeout or no response after running claude

Check your environment variable:

echo $ANTHROPIC_BASE_URL

If it's empty or shows https://api.anthropic.com, the variable isn't set or wasn't reloaded. Run source ~/.bashrc and retry.

unsupported region error

This is a geographic restriction from the official Anthropic API. Switching to ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1 resolves it completely — CodeGateway handles routing.

npm install fails with ECONNRESET

WSL2 inherits Windows' network stack. If you have a proxy configured on Windows, you may need to pass it through to WSL2:

# Replace with your actual proxy address
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
npm install -g @anthropic-ai/claude-code

Files between Windows and WSL2

Your Windows C:\ drive is accessible in WSL2 at /mnt/c/. For example, your Windows Desktop is at /mnt/c/Users/YourName/Desktop.

Performance tip: Keep your project files inside the WSL2 filesystem (~/projects/) rather than /mnt/c/. I/O across the WSL boundary is significantly slower for large codebases.

Full Error Reference

Frequently Asked Questions

Q: Is CodeGateway just a proxy? Will Anthropic's features still work?

A: CodeGateway routes your requests through Cloudflare AI Gateway to Anthropic's API. From Claude Code's perspective, it's talking to a fully compatible endpoint. All Claude features — streaming, tool use, vision, prompt caching — work exactly as documented. The only difference you'll notice is that regional connection issues disappear.

Q: What happens if CodeGateway has an outage?

A: Cloudflare's network has a strong uptime record. In the unlikely event of an outage, the CodeGateway status page shows current incidents. You can also temporarily revert to the official endpoint by unsetting ANTHROPIC_BASE_URL while you wait — your API key format and calls don't change.

Q: How does the 1.35x markup compare to using Anthropic directly?

A: You pay 35% above Anthropic's list price in exchange for stable access, no region restrictions, and pay-as-you-go top-up without a US/international credit card requirement. For most developers, the convenience and reliability are worth it. The tiered multiplier also decreases as your monthly usage grows.

Q: Can I use CodeGateway with other tools besides Claude Code?

A: Yes. Anything that accepts an OpenAI-compatible or Anthropic-compatible base URL works: Cursor, Continue.dev, LangChain, LlamaIndex, custom scripts, Jupyter notebooks. Just swap the base URL and key — the rest of your code stays the same.

Q: Is my API key safe passing through CodeGateway?

A: Your key is sent over HTTPS to Cloudflare's edge, which terminates TLS before forwarding to Anthropic. CodeGateway's infrastructure is hosted on Cloudflare Workers — your key is never logged or stored in plaintext. You can revoke and rotate keys in the Dashboard at any time.

Q: Does CodeGateway support OpenAI models too?

A: Yes. The same key and endpoint also routes to OpenAI's GPT-4o, GPT-4.1, o1, and o3 series. Switch models in Claude Code with /model gpt-4o or use the OpenAI API format directly:

curl https://api.codegateway.dev/v1/chat/completions \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Q: What's the minimum top-up amount?

A: $5 USD minimum, any integer amount up to $10,000. No subscription, no monthly commitment. Top up when you need it, and unused credit doesn't expire.

Q: How do I check my remaining balance?

A: Log in to the CodeGateway Dashboard. Your balance appears on the home screen and updates after each API call. You can also set email alerts at any balance threshold you choose.

Advanced

Configuration

Project Memory with CLAUDE.md

Claude Code reads a CLAUDE.md file from your project root on every startup. Use it to capture project context once so you never repeat yourself:

cat > CLAUDE.md << 'HEREDOC'
# Project Context
Next.js 14 + TypeScript, Tailwind CSS, Prisma ORM.

# Code Conventions
- Functional components only — no class components
- Every async operation needs try/catch with typed errors
- All DB access goes through /lib/db.ts — never import prisma directly
- Environment variables must have comments in .env.example

# Current Focus
Sprint 4: user auth flow and billing integration
HEREDOC

Commit this file to git. Every teammate using Claude Code gets the same shared context automatically.

Monitor Usage in the Dashboard

The CodeGateway dashboard shows real-time token consumption, per-model breakdowns, and cost estimates. Set a low-balance email alert (we recommend $2-5 threshold) so you top up before your session gets interrupted mid-task.

Resume Previous Sessions

Claude Code keeps session history. Pick up where you left off:

# Resume the most recent session
claude --continue

# Browse session history
claude --history

Useful for multi-day tasks — no need to re-explain context when you come back the next morning.

Cost Benchmarks from Our Usage

Based on real usage through CodeGateway (1.35x markup, Sonnet 4.6):

The $2 free credit covers roughly 30-50 typical interactions — enough to evaluate whether the workflow fits before committing.

Shell Function: Project-Aware Launch

Add to ~/.zshrc or ~/.bashrc to get a reminder when entering a Claude Code project:

function cdp() {
  cd "$@"
  if [[ -f CLAUDE.md ]]; then
    echo "Claude Code project detected. Run 'claude' to start."
  fi
}

Security Best Practices for Your API Key

Never Commit Your API Key

Add a safeguard to your project:

# .gitignore
.env
.env.local
.env.*.local

And document the expected format in .env.example (committed to git, no real values):

# Get your API key from https://dashboard.codegateway.dev
ANTHROPIC_API_KEY=cgw-your-key-here
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1

Rotate Keys Periodically

In CodeGateway Dashboard, you can generate a new key and revoke the old one at any time. We recommend rotating keys whenever a team member leaves or if you suspect a key has been exposed.

Separate Keys Per Environment

Use different keys for local development, staging, and CI:

# Local dev: personal key with no spending cap needed
# CI/CD: dedicated key with optional usage monitoring
# Production: tightly controlled, alerts at $10 threshold

Each key shows up as a separate row in the Dashboard with its own usage graph.

Real-World Workflows in WSL2

Once your setup is complete, here are the workflows we use daily — all tested on WSL2 + Claude Code + CodeGateway.

Workflow 1: Code Review and Refactoring

Clone your project directly into the WSL2 filesystem (3–5× faster than working under /mnt/c/):

cd ~
git clone https://github.com/your-account/your-project.git
cd your-project
claude

Typical prompts that work well:

> Review src/auth.ts and identify potential security issues
> Refactor utils/helpers.js to replace all var declarations with const or let
> Write Jest unit tests for every exported function in this file

Workflow 2: Multi-Model Cost Optimization

CodeGateway routes to Claude's full model lineup. Switch models based on task complexity:

# Inside Claude Code, use /model to switch
/model claude-haiku-4-5     # Quick tasks, lowest cost
/model claude-sonnet-4-6    # Default: best price-to-quality
/model claude-opus-4-7      # Complex architecture, deep reasoning

All model usage is billed per-token and reflected in your CodeGateway dashboard in real time. Our internal benchmark: a typical code review of a 300-line file costs under $0.01 on Haiku.

Workflow 3: File Exchange Between Windows and WSL2

WSL2 mounts your Windows drives under /mnt/. Pass Windows-side files to Claude Code seamlessly:

# Copy a file from Windows Desktop to your WSL2 project
cp "/mnt/c/Users/YourName/Desktop/data.csv" ~/projects/my-project/

# Then ask Claude Code to process it
claude
> Analyze data.csv, identify the top 3 months by revenue, and output a pandas script

Workflow 4: VS Code + WSL + Claude Code

The most productive setup we've found: VS Code with the Remote - WSL extension opens your WSL2 project natively, and Claude Code runs in the integrated terminal:

# From WSL2 terminal, in your project directory
code .  # Opens VS Code connected to WSL2
# Then in VS Code's integrated terminal:
claude

This means your editor, file system, and AI assistant all run in the same Linux environment — no path translation, no encoding issues, no surprises.

Summary

Next Steps

You now have Claude Code running on your machine with a stable, reliable API connection through CodeGateway. Here is what you have set up:

• Claude Code installed and accessible from any terminal session

• API calls routed through CodeGateway's Cloudflare edge network

• Environment variables persisted so configuration survives reboots

• $2 free credit already available in your account to start experimenting

From here, the most productive next steps are:

1. Create a CLAUDE.md in your first real project — even three lines of context makes a noticeable difference in response quality

2. Try the quick setup script if you want a repeatable one-command install for future machines: Claude Code Quick Setup

3. Explore the advanced techniques guide once you are comfortable with the basics: Claude Code Advanced Techniques

4. Watch your token usage for the first week in the Dashboard to calibrate which model tier makes sense for your workflow

If anything in this guide did not work on your specific setup, the Error Troubleshooting docs cover every error code you are likely to see, and the CodeGateway feedback page accepts bug reports directly.

This guide is updated as Claude Code and CodeGateway evolve. Check back for new model support, updated pricing tiers, and platform-specific tips. If you find anything outdated or broken, use the feedback page to let us know — we iterate quickly based on real developer reports.

Total: ~13 minutes, one-time setup. After that, Claude Code starts with claude from any WSL2 terminal.

CodeGateway's endpoint (https://api.codegateway.dev/v1) is fully compatible with Anthropic's API spec — Claude Code has no idea it's talking to a gateway rather than the origin. You get the exact same feature set with none of the regional restrictions and with measured latency around 150–300ms (we measured round-trip from WSL2 on a typical home connection).

Related Reading

• Claude Code Complete Configuration Guide

• Claude Code Connection Timeout Fix

• Claude API Rate Limits Explained

• Billing Guide: Pay-As-You-Go & Credits