Claude CLI on Linux and macOS: Install and Connect to the Gateway

Claude CLI on Linux and macOS installs with one command, but then the small stuff begins: where the binary ends up, which file takes your variables and why the agent "cannot be found" after installation. This article takes you from a clean system to the first model reply through the Zukko gateway and covers the common failures.

What you need

According to Anthropic's documentation, Claude Code runs on macOS 13 and later, Ubuntu 20.04+, Debian 10+ and Alpine Linux 3.19+. You need at least 4 GB of RAM and an x64 or ARM64 processor. Bash and Zsh are supported. The main installation method does not need Node.js: the native installer ships a ready-made binary. Node is only required if you choose npm.

Besides the machine you need a gateway key: create it in the dashboard↗. The full key with the fetch_ prefix is shown only once.

Claude CLI on Linux: installation methods

Native installer (recommended). Works on macOS, Linux and WSL:

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

The installer shows no progress, so do not worry about the silence. Then open a new terminal window and check:

claude --version
claude doctor

claude doctor prints installation and settings diagnostics without starting a session. Native installs update themselves in the background.

Homebrew on macOS:

brew install --cask claude-code

There are two casks: claude-code follows the stable channel and claude-code@latest gets releases immediately. Homebrew does not update the package automatically; run brew upgrade claude-code.

Linux package managers. Anthropic publishes signed repositories for apt, dnf and apk. On Ubuntu and Debian you first download the repository key, check its fingerprint, then add a line to sources.list.d and run sudo apt install claude-code. Take the exact commands and key fingerprint from the official installation page rather than from third-party articles: the key is something you should verify with your own eyes.

npm. An option for those who already have Node.js:

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

The documentation asks for Node.js 22 or newer, although on an older version npm only prints an EBADENGINE warning and the binary itself does not use Node. To update: npm install -g @anthropic-ai/claude-code@latest. Do not use sudo npm install -g: it causes permission problems and is unsafe.

Alpine. You need the bash, curl, libgcc, libstdc++ and ripgrep packages, plus USE_BUILTIN_RIPGREP set to 0 in settings.json:

apk add bash curl libgcc libstdc++ ripgrep

The "command not found: claude" error

The most common problem after installation. The native installer puts claude into ~/.local/bin, and if that folder is not in PATH, the shell does not see the command. Check:

ls -la ~/.local/bin/claude
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

If the first command finds the file and the second prints nothing, add the folder to your profile. For Zsh (the macOS default):

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

For Bash on Linux use ~/.bashrc, and for Bash on macOS use ~/.bash_profile. Then open a new terminal window: an already open window keeps the old PATH. A terminal inside an editor takes its PATH from the editor, so restart the editor too.

If echo reports permission denied, the profile file is not owned by your user or is not writable. Fix the file ownership instead of running the command as root.

Permissions and EACCES

With npm installs you may meet EACCES: permission denied: the global npm directory belongs to root. Instead of sudo, set up a user-level npm prefix or switch to the native installer, which writes only to your home directory. Concrete steps for fixing permissions are in the installation troubleshooting section of the Claude Code documentation.

Connecting the Zukko gateway

Now two parameters: the address and the token. For Claude Code the address has no /v1, and the token must be passed through ANTHROPIC_AUTH_TOKEN. Add to ~/.zshrc or ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.zukko.pro
export ANTHROPIC_AUTH_TOKEN=fetch_your_key
export ANTHROPIC_MODEL=claude-sonnet-5-5

Apply the changes with source ~/.zshrc. An alternative to the profile is the env block in ~/.claude/settings.json: it applies everywhere Claude Code runs, including from an IDE that does not read your .zshrc. Do not put the token into .claude/settings.json inside a repository, since that file is usually committed.

Before launching the agent, test the gateway with a direct request:

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

A reply starting with {"id":"msg_ and status 200 mean the address and key are right. Then run claude and type /status: check which API address and which authentication method the session uses. If it shows an account login rather than your token and the gateway address, the variables did not reach the session.

Reading the response codes

If variables holding an Anthropic key are left over in your environment from old experiments, remove them so the credential sources do not get mixed up.

What it costs

Prices as of October 18, 2026: claude-sonnet-5-5 is $0.4 per 1M input tokens and $2 per 1M output, cache read $0.05, cache write $0.5. An example for a small session: 300,000 fresh input tokens, 700,000 cache read, 50,000 cache write and 30,000 output:

0.3 × 0.4 + 0.7 × 0.05 + 0.05 × 0.5 + 0.03 × 2 = 0.12 + 0.035 + 0.025 + 0.06 = $0.24.

The cache discount comes from the Anthropic format that Claude Code uses. For the current price list call GET https://api.zukko.pro/v1/models or open the Models page in the dashboard. If you want to run the agent on a remote server, see the article on Claude Code over SSH↗, and the general workflow is covered in the setup from scratch↗. Connection parameters are also collected in the Zukko documentation↗.

FAQ

Do I need Node.js for Claude Code on Linux?

Not for the native installer, Homebrew or the apt, dnf and apk packages. It is only required when installing through npm.

Why is the claude command not found right after installation?

Usually ~/.local/bin is not in the PATH of the current terminal window. Add it to your shell profile and open a new window.

How do I update Claude Code?

A native install updates itself in the background, and claude update works manually. Homebrew and the Linux package managers update with their own commands.

How do I pay from Russia?

Through the gateway: top up the balance from $1 via SBP (the payment page adds an 8.5% fee), with a MasterCard card or with cryptocurrency.