Loading…
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.
Before you begin, make sure you have:
Requirement |
|---|
Details
Windows version | Windows 10 (Build 19041+) or Windows 11 |
Architecture | x64 or ARM64 |
RAM | 8 GB recommended (WSL2 uses ~1–2 GB overhead) |
Disk space | ~4–5 GB (Ubuntu image + Node.js + Claude Code) |
CodeGateway account | Register at codegateway.dev — free $2 credit on signup |
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.
Open PowerShell as Administrator (right-click → Run as administrator) and run:
wsl --installThis 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).
# List available distributions
wsl --list --online
# Install Ubuntu 22.04 specifically
wsl --install -d Ubuntu-22.04wsl --list --verboseExpected output:
NAME STATE VERSION
* Ubuntu Running 2If VERSION shows 1, upgrade it:
wsl --set-default-version 2
wsl --set-version Ubuntu 2Open 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 laterQuick 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.
With Node.js ready, install Claude Code globally:
npm install -g @anthropic-ai/claude-code
# Verify
claude --versionExpected output:
@anthropic-ai/claude-code/1.x.x linux-x64 node-v22.x.xIf 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-codeGo to codegateway.dev and create an account (email or GitHub login)
You'll receive $2 in free credits automatically — enough to test dozens of Claude interactions
Navigate to Dashboard → API Keys → Create New Key
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.
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
export ANTHROPIC_API_KEY="cgw-your-key-here"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
claudeAdd these lines to ~/.bashrc:
nano ~/.bashrcAppend 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 ~/.bashrcFor 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
EOFClaude Code automatically picks up .env files in the working directory.
Launch Claude Code from any directory:
claudeYou should see the Claude Code interactive UI start up. Try a quick test:
> Write a one-line Python hello worldIf 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/v1If 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.
# 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 -20If 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 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.devYou 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 claudeCheck your environment variable:
echo $ANTHROPIC_BASE_URLIf 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 errorThis 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.
ECONNRESETWSL2 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-codeYour 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.
Error | Cause | Fix |
|---|---|---|
| Official Anthropic endpoint selected | Set |
| Endpoint not overridden | Check env vars: |
| Invalid or expired API key | Regenerate key in CodeGateway Dashboard |
| Rate limit hit | Wait 10–60 seconds; see Rate Limits Guide |
| npm global prefix issue | Use nvm-installed Node.js instead of system Node |
| WSL2 DNS resolution failure | Add |
| WSL not installed or PATH missing | Run |
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.
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
HEREDOCCommit this file to git. Every teammate using Claude Code gets the same shared context automatically.
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.
Claude Code keeps session history. Pick up where you left off:
# Resume the most recent session
claude --continue
# Browse session history
claude --historyUseful for multi-day tasks — no need to re-explain context when you come back the next morning.
Based on real usage through CodeGateway (1.35x markup, Sonnet 4.6):
Task | Avg tokens | Approx cost |
|---|---|---|
Review a 200-line file | ~8K | ~$0.02 |
Write unit tests for a module | ~12K | ~$0.03 |
Full refactor of a class | ~20K | ~$0.05 |
Architecture discussion (30 min) | ~40K | ~$0.10 |
The $2 free credit covers roughly 30-50 typical interactions — enough to evaluate whether the workflow fits before committing.
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
}Add a safeguard to your project:
# .gitignore
.env
.env.local
.env.*.localAnd 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/v1In 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.
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 thresholdEach key shows up as a separate row in the Dashboard with its own usage graph.
Once your setup is complete, here are the workflows we use daily — all tested on WSL2 + Claude Code + CodeGateway.
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
claudeTypical 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 fileCodeGateway 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 reasoningAll 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.
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 scriptThe 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:
claudeThis means your editor, file system, and AI assistant all run in the same Linux environment — no path translation, no encoding issues, no surprises.
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:
Create a CLAUDE.md in your first real project — even three lines of context makes a noticeable difference in response quality
Try the quick setup script if you want a repeatable one-command install for future machines: Claude Code Quick Setup
Explore the advanced techniques guide once you are comfortable with the basics: Claude Code Advanced Techniques
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.
Step | Action | Time |
|---|---|---|
1 | Install WSL2 + Ubuntu | ~5 min |
2 | Install Node.js via nvm | ~2 min |
3 | Install Claude Code | ~1 min |
4 | Register CodeGateway + get API key | ~3 min |
5 | Set environment variables | ~1 min |
6 | Verify | ~1 min |
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).