How to install Claude Code on Windows, Mac, and Linux: API key without a subscription and payment with Satispay

Installing Claude Code requires only one command, which varies by terminal: the line with install.sh on macOS, Linux, and WSL, irm … | iex in PowerShell, and the line with install.cmd in Command Prompt. This is the method recommended by Anthropic; npm remains possible but requires Node.js 22 or later. Claude's free plan does not include Claude Code, so you need a Pro or higher subscription or an API key. Here you will take the second route: ANTHROPIC_BASE_URL=https://api.kunavo.com (without /v1), the key in ANTHROPIC_AUTH_TOKEN, four variables that pin the models, and /status for the final check. Credit is topped up with Satispay in euros from $10, and you pay only for the tokens you use.

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows – Prompt dei comandi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Da dove vengono questi comandi: la documentazione di Claude Code esiste anche in italiano e l'abbiamo riletta il October 3, 2026, in particolare le pagine su installation e LLM gateway. Prezzi e metodi di pagamento di Kunavo sono aggiornati al October 3, 2026. Anthropic serve l'Italia sia su Claude.ai sia con l'API (supported countries, letto il October 3, 2026).

What you need

I requisiti della official documentation (letta il October 3, 2026) sono bassi:

• macOS 13.0 or later; Windows 10 1809 or later, or Windows Server 2019 or later; Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+.
• At least 4 GB of RAM and an x64 or ARM64 processor. 32-bit Windows is excluded.
• A shell among Bash, Zsh, PowerShell, and CMD.
• A connection from a country supported by Anthropic: Italy is supported.
• Node.js only if you choose npm, and in that case version 22 or later.

Which command, in which terminal

Administrator privileges and WSL are not required: the official documentation says so explicitly, even though more than one guide suggests otherwise. Once installed, Claude Code updates itself in the background. If you prefer a package manager, you can use Homebrew or WinGet, knowing that you will launch the updates yourself:

# Homebrew – canale stable; non si aggiorna da solo
brew install --cask claude-code

# WinGet (Windows) – non si aggiorna da solo
winget install Anthropic.ClaudeCode

Before trying it, close the terminal and open a new one: only a new window rereads PATH. Then verify it. claude doctor will also be useful later, because it checks the installation and settings without opening a session and immediately tells you whether the problem is with one or the other.

claude --version   # stampa la versione, ad esempio 2.1.284 (Claude Code)
claude doctor      # diagnostica di installazione e impostazioni, senza aprire una sessione

Download blocked: 403 or an HTML page instead of the script

Quando lo script non arriva, il terminale non lo dice in modo chiaro: bash si lamenta con syntax error near unexpected token '<' (sta cercando di eseguire una pagina web), oppure curl si ferma su curl: (22) The requested URL returned error: 403. La official page about installation problems (in inglese, letta il October 3, 2026) distingue due casi. Se la pagina scaricata dice App unavailable in region, il server crede che ti colleghi da un paese escluso: dall'Italia capita quasi sempre per una VPN o un proxy che esce all'estero. Un 403 senza testo arriva più spesso da un proxy aziendale o da un firewall. Cambiare metodo di installazione non aiuta, perché Homebrew e WinGet scaricano dagli stessi server: prova da un'altra rete oppure chiedi all'IT di sbloccare quei domini.

With npm: Node.js 22, not 18

Se Node.js lo usi già tutti i giorni, npm sembra la scelta naturale. Funziona ed è tra i metodi documentati, con una condizione che molte guide in italiano non hanno aggiornato: ci vuole Node.js 22 o successivo. Con un Node più vecchio vedrai l'avviso EBADENGINE, però l'installazione arriva in fondo e claude parte lo stesso (official documentation, letta il October 3, 2026). Le versioni aggiornate di Node sono su nodejs.org.

node -v                                    # serve v22 o successiva
npm install -g @anthropic-ai/claude-code   # senza sudo

# aggiornamento: @latest, non npm update -g
npm install -g @anthropic-ai/claude-code@latest

Three habits to avoid:

• sudo before npm install -g. The documentation advises against it, both because of conflicting permissions and for security reasons.
• npm update -g to update. Instead, repeat the installation with @latest, as in the last line above.
• Skipping optional dependencies. Il binario di Claude Code arriva proprio come dipendenza facoltativa, un pacchetto @anthropic-ai/claude-code-* per ogni piattaforma. Con --omit=optional, o con optional=false nel file .npmrc, non viene scaricato e su macOS o Linux claude risponde claude native binary not installed (installation problems, in inglese, letta il October 3, 2026).

Claude Code on Windows: where things get stuck

Su Windows Claude Code gira in modo nativo, e l'installazione in sé è la parte facile. I problemi nascono dall'ambiente. Il primo è il terminale: se incolli in PowerShell la riga per CMD, PowerShell protesta per il &&; se incolli in CMD la riga per PowerShell, CMD non sa cosa sia irm; e la riga curl … | bash del Mac in PowerShell non funziona proprio. Su un Windows in italiano alcuni di questi messaggi possono comparire tradotti. In ogni caso la soluzione è tornare alla tabella qui sopra e prendere la riga del terminale che hai davanti (i messaggi in inglese sono nella tabella degli errori in fondo; fonte: documentation, letta il October 3, 2026).

Also watch the Start menu: “Windows PowerShell (x86)” opens a 32-bit process, and Claude Code stops with Claude Code does not support 32-bit Windows, even if the PC is 64-bit. Choose the entry without (x86).

Git for Windows non è obbligatorio. Se è installato, Claude Code esegue i comandi attraverso Git Bash; se manca, usa PowerShell. Quando Git c'è ma Claude Code non trova bash.exe, indicagli il percorso con CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json, di solito C:\Program Files\Git\bin\bash.exe. E WSL? Serve solo in un caso preciso:

With WSL, everything happens inside Linux: run the install.sh line in the WSL shell, and launch claude from there.

“claude” not found

If after installation the terminal responds with command not found: claude or 'claude' is not recognized, the program is present but its folder is not in PATH. The native installer copies it to ~/.local/bin/claude on macOS and Linux and to %USERPROFILE%\.local\bin\claude.exe on Windows. First try: a new terminal. If that is not enough on Windows, these are the PowerShell commands from the documentation to check and add the folder to the user's PATH:

# 1. Controlla se la cartella di installazione è già nel PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Nessun risultato? Aggiungila al PATH utente, poi chiudi e riapri il terminale
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Nel nuovo terminale
claude --version

npm.ps1 cannot be loaded in PowerShell

This applies only to those who install with npm: PowerShell's execution policy blocks the .ps1 script created by npm, and the full message contains running scripts is disabled on this system. The documentation gives three ways out: allow the current user to run local scripts with the command below, run npm.cmd and claude.cmd instead of the PowerShell scripts, or abandon npm and use the native installer.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Without a subscription: Claude account or API key

Installato non vuol dire pronto: al primo avvio Claude Code chiede di autenticarsi, e il piano gratuito di Claude.ai non basta (documentation, letta il October 3, 2026). Le due strade a confronto:

Esiste anche la chiave della Console di Anthropic, sempre a consumo. Lì però i crediti prepagati scadono dopo un anno e non si rimborsano (Anthropic support, letto il October 3, 2026); si paga con carta, mentre il bonifico ACH è riservato agli account API con fatturazione mensile (Anthropic support). Il credito Kunavo non ha scadenza.

Configuring the API key: six variables

Che Claude Code parli con un endpoint diverso da quello di Anthropic è previsto: la documentazione ufficiale ha una pagina, tradotta anche in italiano, su come connect it to an LLM gateway. Nessun plugin, nessuna versione modificata. Bastano queste variabili:

On macOS and Linux, add them at the end of ~/.zshrc or ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # solo il dominio, senza /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

On Windows, for a quick test that lasts as long as the PowerShell window:

# Vale solo in questa finestra di PowerShell: chiusa la finestra, sparisce
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

To avoid setting them again every time, the right place is the env block in ~/.claude/settings.json (on Windows %USERPROFILE%\.claude\settings.json): it applies to all your projects. If the file already contains other settings, add only env:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

AUTH_TOKEN or API_KEY?

Kunavo legge la chiave da tutti e due gli header, Authorization: Bearer e x-api-key, quindi in teoria vanno bene entrambe le variabili. La differenza la fa Claude Code. Con ANTHROPIC_API_KEY, inviata come x-api-key, la sessione interattiva ti chiede una volta se approvare la chiave; se rispondi no, la ignora senza dire nulla finché non la riattivi da /config → Use custom API key. ANTHROPIC_AUTH_TOKEN non chiede niente, ed è anche la variabile che la gateway documentation (letta il October 3, 2026) suggerisce quando non sai quale scegliere.

Why pin the models

Senza variabili Claude Code ragiona per alias, e gli alias seguono le uscite di Anthropic. Oggi, secondo la model configuration documentation (letta il October 3, 2026), per chi usa l'API opus corrisponde a Opus 5.5 e sonnet a Sonnet 5.5. Kunavo, al October 3, 2026, non offre Sonnet 5.5: senza ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase esecutiva di opusplan e i subagent con model: sonnet chiederebbero un modello che su Kunavo non c'è e tornerebbero 404. Con claude-sonnet-5 in quella variabile l'alias punta a Claude Sonnet 5, lo stesso modello di ANTHROPIC_MODEL. Quest'ultima decide invece il modello della sessione: senza, Claude Code partirebbe dal suo predefinito, oggi Opus 5.5. Opus 5.5 è disponibile, e fissare opus su claude-opus-5-5 serve a un'altra cosa: evitare che modello e tariffa cambino da un giorno all'altro quando l'alias passerà a un Opus successivo. Claude Opus 5.5 richiede Claude Code 2.1.280 o successivo; con una versione più vecchia, lancia prima claude update.

Kunavo's rates for the three models in the configuration, per million tokens (input / output): Claude Sonnet 5 $1,40 / $7,00 (Anthropic list price: $2,00 / $10,00); Claude Opus 5.5 $2,80 / $14,00; Claude Haiku 4.5 $0,70 / $3,50, which also works behind the scenes.

Where not to put it, and which setting takes precedence

Il .claude/settings.json dentro il progetto viene committato: una chiave scritta lì finisce nel repository e arriva a chiunque lo cloni (gateway documentation). Se una variabile compare sia nella shell sia nel blocco env di un file di impostazioni, prevale il file: quando una modifica a ~/.zshrc sembra ignorata, il motivo è quasi sempre lì. Il campo model del file di impostazioni, invece, cede il passo ad ANTHROPIC_MODEL. Nell'estensione di Claude Code per VS Code le stesse variabili vanno in claudeCode.environmentVariables, nelle impostazioni utente di VS Code. L'app desktop di Claude resta fuori da tutto questo: non legge né ANTHROPIC_BASE_URL né settings.json (gateway documentation, letta il October 3, 2026).

First launch and check with /status

Se la chiave è al suo posto, claude parte without a login screen: restano solo la configurazione iniziale e la domanda se ti fidi della cartella. Se invece compare il login, Claude Code non ha trovato la chiave. Il caso tipico è la chiave scritta solo nel .claude/settings.json o nel .claude/settings.local.json del progetto: in modalità interattiva quel blocco env entra in gioco solo dopo la configurazione iniziale e la conferma di fiducia (gateway documentation, letta il October 3, 2026), quindi al primo avvio non c'è ancora. Spostala nella shell o nel file utente. Un vecchio login Pro o Max non dà fastidio, perché la variabile ha la precedenza sull'accesso salvato; se vuoi cancellarlo, c'è /logout.

Inside the session, type /status. The two lines that matter are:

• Anthropic base URL, which appears only when a gateway is configured: it should say https://api.kunavo.com. If it is missing, ANTHROPIC_BASE_URL did not reach the session.
• Auth token with the name ANTHROPIC_AUTH_TOKEN: you are using the key. If instead you find Login method with a claude.ai account, the variable was ignored.

Want to check before even opening Claude Code? The documentation suggests a minimal request, with 1 output token, which deducts a negligible amount from the credit. The command reads the variables from the current shell: if the key is only in settings.json, export it first in this terminal. If it returns JSON beginning with {"id":"msg_, you are set; 401 means the key was rejected.

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", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

In PowerShell, the same check is this, and the successful response contains an id that starts with msg_:

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

What you lose with the API key

• Remote Control and voice dictation. They require a claude.ai identity and do not work with ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY; starting with version 2.1.196, Remote Control is also disabled when ANTHROPIC_BASE_URL points to a host that is not Anthropic's.
• The /fast mode. With only the bearer token, Claude Code considers it disabled and does not even try to ask.
• MCP tool discovery at the start. Con un ANTHROPIC_BASE_URL personalizzato parte spenta (MCP documentation, in inglese, letta il October 3, 2026). Si riaccende con ENABLE_TOOL_SEARCH=true se il gateway inoltra i blocchi tool_reference; con Kunavo non l'abbiamo provato.
• The accuracy of /context. Kunavo non espone /v1/messages/count_tokens, un endpoint facoltativo secondo la gateway specification (letta il October 3, 2026); senza, Claude Code stima i token a partire dai caratteri.

For more details, in English: the Claude Code integration documentation, the page about ANTHROPIC_BASE_URL edge cases, and the Install Claude Code guide.

Pay with Satispay, without a credit card

Prima una precisazione, perché è la domanda più frequente: Satispay non paga l'abbonamento Claude. Per Pro e Max comprati sul web Anthropic accetta solo carte di credito o di debito (Anthropic support) e non accetta PayPal (Anthropic support), entrambi letti il October 3, 2026. Su Kunavo Satispay ricarica invece il credito API che Claude Code consuma con la chiave configurata sopra. Tutti i dettagli, compresi i costi per caricare la Disponibilità, sono nella guida pay for Claude with Satispay. Per Claude Code la sequenza è questa:

1. Sign up for Kunavo with an email address or Google account: no card required.
2. Open Billing and choose how much to top up: minimum $10, no subscription fee. There is a bonus above certain thresholds: $100 diventano $110, $1.000 diventano $1.200, $5.000 diventano $6.250 in credit.
3. Nel checkout di Stripe, che mostra l'importo in euro, scegli Satispay. Si passa alla pagina di Satispay (Stripe documentation): numero di cellulare o QR code dall'app, poi conferma con Submit (Satispay support, letto il October 3, 2026). Meglio avere già abbastanza Disponibilità prima di cominciare.
4. The credit appears in Billing as soon as Stripe confirms the payment. If you do not see it immediately, refresh the page instead of paying again: a second payment is added to the credit; it does not replace the first one.
5. In API Keys, generate the key sk-kn-… and copy it immediately into ANTHROPIC_AUTH_TOKEN: it is shown only once.

Kunavo fissa i prezzi in dollari e Stripe li converte in euro con una 2–4% currency conversion fee a carico di chi paga (Stripe, Adaptive Pricing, letto il October 3, 2026): sulla ricarica minima da $10 sono tra $0,20 e $0,40. In dollari la commissione sparisce, ma sparisce anche Satispay, che esiste solo nel checkout in euro; se il checkout ti appare in dollari, spesso c'entra una VPN. L'importo esatto in euro è quello che leggi nel checkout prima di confermare.

Con Satispay le ricariche si fanno a mano: la ricarica automatica di Kunavo addebita solo una carta salvata o Link. Chi ha la carta Satispay, una Mastercard di debito per i piani Plus, Metal e Velvet (Satispay support, letto il October 3, 2026), può salvarla e usarla come qualsiasi carta. Il credito non scade e le richieste fallite non vengono addebitate. Kunavo non emette fatture, né con IVA né elettroniche via SDI; lo storico delle ricariche resta in Billing.

An honest note: Satispay has been in Kunavo's checkout since October 3, 2026, and Stripe offers it for euro payments, but no top-up has gone through it yet. If you do not find it, card, Apple Pay, Google Pay, and Link do the same job.

How much a work session costs

With the API key, the cost is in tokens, and Claude Code sends quite a lot of them: on every step it resends the entire context. However, the part that does not change can be read from the cache at a much lower rate. Here is a deliberately constructed example, with the assumptions made explicit: it is not a measurement and not a spending cap.

• 40.000 input tokens per request, of which 36.000 (90%) are read from the cache and 4.000 are written to the cache;
• 1.000 output tokens per request;
• 50 requests in a session, excluding background calls to Claude Haiku 4.5;
• cache reads at 10% of the input rate and writes at 1,25× the input rate: these are Kunavo's ratios for Claude Sonnet 5, and each table row uses those for its own model.

Long contexts, few cache reads, and lengthy responses increase the bill; a /clear between tasks reduces it. You can find whether a subscription or the API is more worthwhile for you in how much Claude Code costs; rates for all Claude models are in Claude API pricing and on the pricing page. To recalculate it with your own numbers, use the Claude token cost calculator (in English).

Errors: message, cause, remedy

What this configuration does not do

• It does not activate a Claude Pro or Max subscription: Kunavo credit pays for the API and Claude Code with a key, not claude.ai or the Claude app.
• It does not issue invoices: neither VAT invoices nor electronic invoices through SDI.
• It does not automatically top up with Satispay: automatic top-up requires a saved card or Link.
• It does not work without the model variables until Kunavo offers Sonnet 5.5 (as of October 3, 2026): the sonnet alias would return 404, as would /model sonnet, the execution phase of opusplan, and subagents with model: sonnet.
• It has no Kunavo documentation in Italian: the integration guide and the page on balance and payments are in English, while Anthropic's Claude Code page is translated.

For the broader picture of developing with Claude from Italy, see the guide to the Claude API in Italy. Where to start: create an account, top up $10 with Satispay, set the six variables, and check with /status.

Frequently asked questions