Installation, Surfaces, and Environments

Before the Claude Code agentic loop takes its first step — reading a file, running a command, committing a change — it needs to be launched. That sounds trivial, but there are nuances: the installation method affects how quickly you receive updates, and the choice of surface determines which capabilities are available at your fingertips.

CLI Installation

Native Installer (Recommended)

macOS, Linux, WSL:

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

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

The main advantage of native installation is automatic background updates. You always stay on the latest version without any extra commands. On Windows without WSL, it is recommended to install Git for Windows: without it, Claude Code falls back to PowerShell instead of Bash tooling, which limits functionality.

Homebrew

brew install --cask claude-code

Homebrew offers two channels:

• claude-code — stable, slightly behind the bleeding edge (typically about a week), skips releases with critical regressions.
• claude-code@latest — receives new versions as soon as they are published.

There are no automatic updates: you need to run brew upgrade claude-code (or brew upgrade claude-code@latest) manually.

WinGet

winget install Anthropic.ClaudeCode

To update: winget upgrade Anthropic.ClaudeCode. Also without auto-updates.

Linux Package Managers

Debian/Ubuntu uses apt, Fedora/RHEL uses dnf, and Alpine uses apk. Details and repository setup are described in the advanced setup documentation.

npm

The @anthropic-ai/claude-code package is available in the npm registry — the same binary, convenient for CI scenarios or programmatic integration:

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

Five Surfaces, One Engine

Claude Code lives in five primary environments. The key detail is that all of them run on the same engine: CLAUDE.md, settings (settings.json), and MCP servers are shared regardless of which surface you use.

flowchart TB
    subgraph surf["Surfaces"]
        T["Terminal CLI"]
        VS["VS Code / Cursor"]
        JB["JetBrains"]
        DA["Desktop App"]
        WEB["Web (claude.ai/code)"]
    end

    E["Unified Claude Code Engine"]

    T --> E
    VS --> E
    JB --> E
    DA --> E
    WEB --> E

    subgraph shared["Shared Resources"]
        CM["CLAUDE.md"]
        ST["settings.json"]
        MCP["MCP Servers"]
    end

    subgraph prov["Model Providers"]
        AN["Anthropic API"]
        BR["Amazon Bedrock"]
        VX["Google Vertex AI"]
        FD["Microsoft Foundry"]
    end

    E --> shared
    E --> prov

Terminal (CLI)

The flagship and primary environment. This is where new features appear first. To launch in a project:

cd your-project
claude

The CLI supports headless mode (claude -p "...") for scripts and CI, pipes, and JSON output. See Headless Mode and CLI Scripting for more details.

VS Code / Cursor

The extension is installed via the marketplace (Cmd+Shift+X → search "Claude Code") or via direct links:

• VS Code: vscode:extension/anthropic.claude-code
• Cursor: cursor:extension/anthropic.claude-code

After installation: Command Palette → Claude Code: Open in New Tab. The extension adds inline diffs directly in the editor, @-mentions for files, plan review mode, and conversation history. Cursor is a fork of VS Code, and the extension works there without modification.

JetBrains

A plugin for IntelliJ IDEA, PyCharm, WebStorm, and the entire JetBrains family. Install it via JetBrains Marketplace ("Claude Code Beta"). Important: the plugin requires a separately installed CLI — it does not bundle it. A notable feature is interactive diff viewing and context passing from selected text.

Desktop App

A standalone application for macOS (Intel and Apple Silicon) and Windows (x64 and ARM64). No open terminal required: visual diff viewing, parallel sessions side by side on one screen, scheduled task execution, and cloud sessions. Requires a paid subscription. The app is available for download at claude.ai.

Web (claude.ai/code)

A browser-based option with no local installation. Ideal for long-running background tasks ("start and come back later"), working with repositories not available locally, or mobile access via the Claude iOS App. The claude --teleport command lets you transfer a web session to the terminal and continue there.

Navigating Between Surfaces

Surfaces are not isolated — you can switch between them without losing context:

Authentication

On first launch, the CLI opens a browser for authorization. Two paths are available:

claude.ai — personal subscription (Pro, Max) or team plan (Teams/Enterprise). This is also where access to the Desktop and Web surfaces lives.

Anthropic Console — an API key with PAYG billing for individual developers.

The CLI and VS Code are the only surfaces that support third-party model providers. Desktop and Web work exclusively through Anthropic.

Third-Party Model Providers

If your team operates within AWS, GCP, or Azure infrastructure — Claude Code supports native integration. The models are the same; billing goes through your cloud provider.

Amazon Bedrock

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# Standard AWS credentials: IAM role, ~/.aws/credentials, etc.

Authentication via IAM — no separate Anthropic keys required. CloudTrail auditing is enabled automatically.

Google Vertex AI

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
# gcloud auth application-default login — for dev environments

For production, use a Service Account with the required Vertex AI roles.

Microsoft Foundry

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key   # or omit it — then Microsoft Entra ID is used

Foundry supports both authentication options: an API key and Entra ID (formerly Azure AD) for SSO scenarios.

Claude Platform on AWS

Different from Bedrock: this is essentially the Anthropic API billed through AWS Marketplace. New model versions appear there faster than in Bedrock, and all Claude API features are preserved (for example, extended prompt caching capabilities).

Pinning Model Versions

When working through third-party providers, it is recommended to pin model versions using environment variables:

export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-5-20251101

Aliases such as claude-sonnet-latest may resolve to different versions across providers and often lag behind the latest releases. Pinning gives your team full control over when to migrate to a new model.

To check the active configuration, use the /status command directly in Claude Code.

See also

• What Is Claude Code: Agentic Coding in the Terminal — context on the agentic loop that all these surfaces run
• Settings and Configuration Hierarchy — how project, user, and enterprise settings relate to one another across all surfaces
• CLAUDE.md and the Memory System — the shared memory and instruction layer available on all surfaces
• Headless Mode and CLI Scripting — using the Terminal surface in automation and CI/CD
• Connecting MCP Servers in Claude Code — configuring shared MCP servers available across all surfaces
• Model Context Protocol: Architecture and Fundamentals — what MCP is and why it is surface-agnostic