Loading…
TL;DR: macOS is the smoothest platform for Claude Code. Install Node.js via Homebrew (or nvm), install Claude Code with npm, then set two environment variables to point at CodeGateway's endpoint. That's it — unsupported region and connection timeouts are gone. Both Intel and Apple Silicon Macs are supported natively. Setup time: ~15 minutes.
Requirement |
|---|
Details
macOS version | macOS 12 Monterey or later (macOS 14 Sonoma recommended) |
Chip | Intel Core or Apple Silicon (M1/M2/M3/M4 all supported natively) |
RAM | 8 GB recommended (Claude Code itself is lightweight; more RAM helps with larger codebases) |
Disk space | ~1–2 GB (Node.js + Claude Code + dependencies) |
Terminal | Default Terminal.app, iTerm2, Warp, or any modern terminal emulator |
CodeGateway account | codegateway.dev — $2 free credit on signup |
Note: Claude Code runs natively on macOS — no virtual machines, no emulation layers. Apple Silicon users get full native arm64 support without Rosetta 2.
Claude Code is a Node.js CLI tool, so Node.js goes in first. Three options:
If you don't have Homebrew installed:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Apple Silicon users: After installation, run this command and add it to ~/.zshrc:
eval "$(/opt/homebrew/bin/brew shellenv)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrcThen install Node.js:
brew install nodeVerify:
node --version # expect v22.x.x or later
npm --version # expect 10.x.x or laterIf you work on multiple projects that need different Node.js versions:
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reload your shell
source ~/.zshrc
# Install and use the current LTS
nvm install --lts
nvm use --ltsVisit nodejs.org, download the macOS .pkg installer, and run it. Straightforward, but you lose easy version management later.
With Node.js ready, install Claude Code globally:
npm install -g @anthropic-ai/claude-codeVerify:
claude --versionExpected output:
@anthropic-ai/claude-code/1.x.x darwin-arm64 node-v22.x.x(Intel Macs show darwin-x64, Apple Silicon shows darwin-arm64)
Real-world test: Tested on an M2 MacBook Air running macOS 14.5 with a standard home connection. The npm install -g step completed in about 45 seconds. No compilation step — Claude Code ships as pure JavaScript, so Apple Silicon requires no Rosetta 2 translation. The binary ran immediately after install.
If you see EACCES: permission denied:
# Check current npm global directory
npm config get prefix
# If it's /usr/local, redirect to a user-owned path
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# Reinstall
npm install -g @anthropic-ai/claude-codeVisit codegateway.dev and create an account (email or GitHub)
$2 in free credits are added to your account automatically — no payment method required to start
Go to Dashboard → API Keys → Create New Key
Copy the key (format: cgw-xxxxxxxxxx) — it's only shown once
Pricing model: Pay-as-you-go with no subscription fee. Top up in any whole dollar amount from $5 to $10,000. Billing is per token at 1.35× model cost (the multiplier decreases at higher usage tiers). Supports the full Claude model family plus OpenAI-compatible models.
Claude Code checks two environment variables:
ANTHROPIC_API_KEY — your API key
ANTHROPIC_BASE_URL — API endpoint (defaults to official Anthropic; override with CodeGateway)
macOS defaults to zsh. Edit ~/.zshrc:
nano ~/.zshrcAdd these lines 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 ~/.zshrcUsing bash? (older macOS or manual shell change): Add the same lines to ~/.bash_profile or ~/.bashrc instead.
export ANTHROPIC_API_KEY="cgw-your-key-here"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
claudeFor project-level isolation (useful for teams where each member uses their own key):
cd /your/project/directory
cat > .env << 'EOF'
ANTHROPIC_API_KEY=cgw-your-key-here
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1
EOFClaude Code reads .env files automatically from the working directory.
Launch Claude Code:
claudeWhen the interactive UI appears, run a quick sanity check:
> Write a Python one-liner that prints "hello world"If you get a response, you're good.
Confirm the environment variables are active:
echo "Endpoint: $ANTHROPIC_BASE_URL"
echo "Key prefix: ${ANTHROPIC_API_KEY:0:6}"Expected:
Endpoint: https://api.codegateway.dev/v1
Key prefix: cgw-xxIf 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.devThis is expected — Homebrew depends on git and other Unix tools that ship with Xcode CLT:
xcode-select --installClick "Install" in the popup and wait a few minutes. Then re-run the Homebrew install command.
brew command not found after installationHomebrew installs to /opt/homebrew/ on Apple Silicon (not /usr/local/ like Intel). Fix:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrcclaude hangs after launch with no outputMost likely cause: ANTHROPIC_BASE_URL isn't set, so Claude Code is trying to reach the official API endpoint and timing out.
echo $ANTHROPIC_BASE_URLIf empty, the variable isn't loaded. Run source ~/.zshrc and retry.
unsupported region error on startupYou're hitting the official Anthropic API's geographic restriction. Set ANTHROPIC_BASE_URL to https://api.codegateway.dev/v1 — CodeGateway routes your request through infrastructure without regional blocks.
claude command not foundThe npm global bin directory isn't in your PATH. Check:
npm config get prefix
# Example output: /Users/yourname/.npm-global
ls $(npm config get prefix)/bin/claude
# Should show the binaryAdd the bin path to ~/.zshrc:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcYou set it with export in a terminal session without saving to ~/.zshrc. Open ~/.zshrc with any text editor and add the two export lines permanently.
Error | Cause | Fix |
|---|---|---|
| Official Anthropic endpoint | Set |
| PATH not updated |
|
| Wrong API key | Regenerate in Dashboard; check key prefix |
| Rate limit hit | Wait and retry; check Rate Limits Guide |
| Node.js version mismatch |
|
| Homebrew permission issue (Intel) |
|
| macOS Python SSL certs | 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.
If you work on projects that should use separate CodeGateway accounts (e.g., personal vs. client work):
# ~/projects/personal-app/.env
ANTHROPIC_API_KEY=cgw-personal-key
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1
# ~/projects/client-work/.env
ANTHROPIC_API_KEY=cgw-client-key
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1When you cd into a project and run claude, it picks up that project's .env. Clean per-project billing.
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.
macOS's native terminal (or iTerm2) pairs naturally with Claude Code:
cd ~/projects/my-app
claude
# Examples of what works well:
> Write unit tests for this TypeScript interface using Jest
> Find every async function in this file that lacks error handling
> Refactor this class to follow the Single Responsibility PrincipleMeasured latency: On an M2 MacBook Pro, Claude Code responses through CodeGateway's Cloudflare edge typically arrive in 2–4 seconds — more consistent than direct API calls in our testing.
brew bundle dump --file=Brewfile
claude
> Analyze this Brewfile. Flag any packages that might conflict, and suggest a leaner alternative setup for a TypeScript backend developer.For iOS and macOS development:
cd ~/projects/MyiOSApp
claude
> Check AppDelegate.swift for memory management issues — particularly retain cycles in closures
> Convert this Objective-C delegate method to Swift 6 concurrency-safe equivalentclaude
> Write a launchd plist that runs a cleanup script every morning at 9am on macOS
> Create a shell script using osascript to show a macOS notification when git push completesCodeGateway gives you access to Claude's full model range under a single API key. Set up shell aliases for quick switching:
# Add to ~/.zshrc
alias cc-fast='CLAUDE_MODEL=claude-haiku-4-5 claude'
alias cc-default='CLAUDE_MODEL=claude-sonnet-4-6 claude'
alias cc-deep='CLAUDE_MODEL=claude-opus-4-7 claude'Cost guidance (via CodeGateway 1.35× markup):
Use case | Model | Cost tier |
|---|---|---|
Autocomplete, quick Q&A | claude-haiku-4-5 | Lowest |
Code review, daily dev | claude-sonnet-4-6 | Medium |
Architecture, deep reasoning | claude-opus-4-7 | Higher |
Higher usage unlocks lower multiplier tiers — see Tiered Pricing Explained.
Step | Command / Action | Time |
|---|---|---|
Install Homebrew (if needed) |
| ~3 min |
Install Node.js |
| ~1 min |
Install Claude Code |
| ~1 min |
Sign up CodeGateway | ~3 min | |
Add env vars to |
| ~1 min |
Reload & verify |
| ~1 min |
macOS is Claude Code's native habitat. No virtualization, no compatibility shims, no WSL2. Apple Silicon users get full arm64 performance. Once your CodeGateway API key is in ~/.zshrc, the setup survives reboots, shell upgrades, and new terminal windows — set it once and forget it.
The real-world latency we measured through CodeGateway from a macOS client was ~150–300ms round-trip, which is on par with direct API access from supported regions. The difference: it actually works, every time.
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.