Claude Code on macOS: Complete Homebrew + CodeGateway Setup Guide

Claude Code Mac Setup: Full Guide with CodeGateway Configuration

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.

Prerequisites

Note: Claude Code runs natively on macOS — no virtual machines, no emulation layers. Apple Silicon users get full native arm64 support without Rosetta 2.

Step 1: Install Node.js

Claude Code is a Node.js CLI tool, so Node.js goes in first. Three options:

Option A: Homebrew (recommended)

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)"' >> ~/.zshrc

Then install Node.js:

brew install node

Verify:

node --version   # expect v22.x.x or later
npm --version    # expect 10.x.x or later

Option B: nvm (best for multi-version setups)

If 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 --lts

Option C: Direct download from nodejs.org

Visit nodejs.org, download the macOS .pkg installer, and run it. Straightforward, but you lose easy version management later.

Step 2: 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 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.

Fix permission errors

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-code

Step 3: Sign Up for CodeGateway and Get an API Key

1. Visit codegateway.dev and create an account (email or GitHub)

2. $2 in free credits are added to your account automatically — no payment method required to start

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

4. 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.

Step 4: Configure Claude Code to Use CodeGateway

Claude Code checks two environment variables:

• ANTHROPIC_API_KEY — your API key

• ANTHROPIC_BASE_URL — API endpoint (defaults to official Anthropic; override with CodeGateway)

Permanent configuration (recommended)

macOS defaults to zsh. Edit ~/.zshrc:

nano ~/.zshrc

Add 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 ~/.zshrc

Using bash? (older macOS or manual shell change): Add the same lines to ~/.bash_profile or ~/.bashrc instead.

Temporary (current terminal window only)

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

Per-project .env file

For 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
EOF

Claude Code reads .env files automatically from the working directory.

Step 5: Verify the Setup

Launch Claude Code:

claude

When 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-xx

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

Homebrew installer asks to install Xcode Command Line Tools

This is expected — Homebrew depends on git and other Unix tools that ship with Xcode CLT:

xcode-select --install

Click "Install" in the popup and wait a few minutes. Then re-run the Homebrew install command.

Apple Silicon: brew command not found after installation

Homebrew installs to /opt/homebrew/ on Apple Silicon (not /usr/local/ like Intel). Fix:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

claude hangs after launch with no output

Most 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_URL

If empty, the variable isn't loaded. Run source ~/.zshrc and retry.

unsupported region error on startup

You'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 Code installed but claude command not found

The 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 binary

Add the bin path to ~/.zshrc:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Configuration disappears after opening a new terminal

You 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.

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

Multiple Keys for Multiple Projects

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/v1

When you cd into a project and run claude, it picks up that project's .env. Clean per-project billing.

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 on macOS

Workflow 1: Terminal + Claude Code Keyboard-First Development

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 Principle

Measured 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.

Workflow 2: Homebrew Package Audit

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.

Workflow 3: Xcode + Claude Code

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 equivalent

Workflow 4: Shell Script Automation

claude
> 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 completes

Workflow 5: Multi-Model Strategy

CodeGateway 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):

Higher usage unlocks lower multiplier tiers — see Tiered Pricing Explained.

Summary

Quick Reference: Setup Checklist

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.

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.

Related Reading

• Claude Code Complete Configuration Guide

• Claude Code Connection Timeout Fix

• Claude Code Advanced Techniques: Sub-Agents & MCP

• Billing Guide