Install Claude Code on macOS and Linux with a Gateway

macOS and Linux are Claude Code's home turf — the official docs assume one of them. Even so, first-time setups fail in predictable places: npm throws a permissions error, environment variables land in the wrong shell file, a new terminal "forgets" the configuration, or Claude Code keeps asking for an Anthropic login even though a gateway is configured. This guide walks through a clean install, two ways to route Claude Code through the Zivv gateway (shell variables and settings.json), and a verification checklist that proves traffic is actually going where you think it is. On Windows? Use the Windows setup guide instead.

Before You Start

You need:

• A recent macOS release or a mainstream Linux distribution (Ubuntu, Debian, Fedora and so on)
• Network access to the installer source
• A Zivv API key — register, then create a key on the API tokens page of the console. Heavy Claude Code users should pick the Claude MAX group when creating it

Then check which shell you are actually running, because it decides which file you edit later:

echo $SHELL

/bin/zsh means zsh (the macOS default); /bin/bash means bash (the default on most Linux distributions). Writing variables into ~/.bashrc while your terminal runs zsh is the single most common reason these setups "don't work".

Step 1: Install Claude Code

Option A: The Native Installer (Recommended)

No Node.js required:

curl -fsSL https://claude.ai/install.sh | bash

It installs into your user directory (typically ~/.local/bin) without sudo. If the shell then reports command not found, that directory is not on your PATH — see the troubleshooting section below. On macOS you can also install through Homebrew (the cask is named claude-code) if you manage all your tools with brew.

Option B: npm

If you already have Node.js 18 or newer:

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

Do not use sudo npm install -g. Files installed as root break later updates. If the plain install fails with EACCES, move npm's global prefix into your home directory:

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

(Use ~/.bashrc on bash.) If your Node comes from nvm or fnm, the global directory is already user-owned and this problem rarely appears.

Which One?

Pick one, not both. Two installs fight over PATH and produce the classic "I upgraded but the version didn't change" mystery. Check with:

which -a claude
claude --version

More than one line from which -a means you have duplicate installs — remove the one you do not use.

Step 2: Route Claude Code Through Zivv

Claude Code reads two environment variables:

• ANTHROPIC_BASE_URL=https://zivv.pro
• ANTHROPIC_AUTH_TOKEN= your sk- key

Two details trip people up. The Anthropic-protocol base URL is the root domain with no `/v1` — adding it gives you 404s. And the variable is ANTHROPIC_AUTH_TOKEN; do not mix in instructions written for other variable names.

Quick Test in the Current Shell

export ANTHROPIC_BASE_URL=https://zivv.pro
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here
claude -p "Reply with OK"

claude -p runs one non-interactive prompt and exits, which makes it the ideal connectivity test. A response means both the install and the routing work.

Persist It in zsh

cat >> ~/.zshrc <<'EOF'
export ANTHROPIC_BASE_URL=https://zivv.pro
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here
EOF
source ~/.zshrc

Persist It in bash

bash reads different files depending on how it starts: interactive non-login shells read ~/.bashrc, while login shells (an SSH session, for example) read ~/.bash_profile or ~/.profile. Put the variables in ~/.bashrc and make sure the profile sources it:

echo 'export ANTHROPIC_BASE_URL=https://zivv.pro' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-your-key-here' >> ~/.bashrc
grep -q bashrc ~/.bash_profile 2>/dev/null || echo '[ -f ~/.bashrc ] && . ~/.bashrc' >> ~/.bash_profile
source ~/.bashrc

fish users can use universal variables: set -Ux ANTHROPIC_BASE_URL https://zivv.pro.

Alternative: the env Block in settings.json

If you would rather keep the key out of your shell environment entirely, put it in Claude Code's own settings. The user-level file is ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://zivv.pro",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key-here"
  }
}

Variables in env are injected every time Claude Code starts, but other programs cannot see them. Settings come in layers:

A handy pattern: keep your default key in the user file, and when one client project needs separate billing, override ANTHROPIC_AUTH_TOKEN in that project's settings.local.json. Double-check it is git-ignored before your first commit. The shared project file should only carry team-wide things like permissions.

Optional: Pin a Default Model

You can switch models any time with /model. To set a default, add ANTHROPIC_MODEL (for example claude-sonnet-5). Confirm exact ids in the Model Hub or via GET /v1/models; a wrong id returns 404, covered in the model-not-found fix guide.

Step 3: Verify

Open a new terminal so you test the persisted configuration, then:

1. echo $ANTHROPIC_BASE_URL prints https://zivv.pro (skip if you used settings.json)
2. claude --version prints a version
3. claude -p "Reply with OK" answers
4. Start claude in a project and run /status to review the active configuration
5. Open the usage page in the Zivv console and find the request you just made

Step 5 is the real proof — usage in the console means traffic went through Zivv. If you previously signed in with an Anthropic account, run /logout inside Claude Code so two credentials are not competing. claude doctor is also useful for checking the installation and updater health.

Troubleshooting

The PATH fix for zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

For status codes in depth, see the 401 fix guide and the error reference.

Servers and Remote Development

Running Claude Code on a Linux dev box over SSH is common. A few habits help:

• SSH gives you a login shell — make sure ~/.bash_profile sources ~/.bashrc, or the variables will be missing
• Run long sessions inside tmux or screen so a dropped connection does not kill the session
• On shared machines, every person uses their own system account and their own key; never put a key in a global file like /etc/profile
• Behind a corporate proxy, set HTTPS_PROXY

For teams, Team mode issues a key per member with daily and monthly budgets and usage broken down by member, key and model. The team budget guide covers the setup.

FAQ

Do I need Node.js to install Claude Code on a Mac? No. The native installer does not depend on Node.js. Only the npm route requires Node.js 18 or newer.

What is the difference between ~/.zshrc and settings.json for the variables? ~/.zshrc exposes them to every program in your terminal; the env block in ~/.claude/settings.json applies only to Claude Code. Choose one location so troubleshooting stays simple.

How do I fix EACCES when running npm install -g? Do not reach for sudo. Point npm's prefix at a directory in your home folder and add its bin to PATH, or switch to the native installer.

Why does Claude Code still ask me to sign in after configuring the gateway? The current terminal is not seeing the variables. Check with echo $ANTHROPIC_BASE_URL; usually the variables went into the wrong shell file or the terminal was not reopened.

Can I use the Claude MAX group on a Linux server? Yes. It serves the native Anthropic protocol and is platform-independent — choose the group on the key and configure the server exactly like your laptop.

How do I switch back to my Anthropic account? Comment out the two variables (or remove the env block) and open a new terminal. For a one-off switch, unset both variables in a single shell.

Wrap-Up

On macOS and Linux the whole job is three decisions: one install method (and only one copy), the right file for two variables, and a usage check in the console to confirm the routing. For staying productive in long sessions, read the rate limit guide and keep the Claude Code docs handy. Create your key and you can be running in a few minutes.