How to Install Claude Code on a VPS: The Complete Expert Guide (2026)

Last updated: June 2026 · Tested on Ubuntu 22.04 / 24.04 / 26.04 · Claude Code native installer (2026)

Claude Code is Anthropic’s terminal-based AI coding agent. It reads your codebase, edits files, runs shell commands, and builds features from plain-language descriptions — all from a single claude command. Running it on a VPS turns it into a persistent, always-on AI developer: close your laptop, the agent keeps working. Reconnect from any device and pick up exactly where you left off.

This guide is the most complete reference for deploying Claude Code on a Linux VPS. It covers every installation method (native installer, apt, npm), all three headless authentication paths, tmux session persistence, security hardening, multi-agent workflows, and production-grade systemd service setup. No steps are skipped. Every command is copy-paste ready.

Table of Contents

1. Why run Claude Code on a VPS?
2. System requirements & VPS sizing
3. Installation: three methods
4. Authentication on a headless server
5. Session persistence with tmux
6. Configuration & CLAUDE.md
7. Security hardening
8. Run Claude Code as a systemd service
9. Multi-agent workflows on a VPS
10. MCP server integration
11. Updating & version pinning
12. Troubleshooting
13. Uninstalling cleanly
14. FAQ

1. Why Run Claude Code on a VPS?

Running Claude Code on your local machine works, but it has a fundamental limitation: the moment you close your terminal or your laptop goes to sleep, every running session dies. On a VPS, nothing stops. The agent runs 24/7, completes long tasks overnight, and is reachable from your phone, tablet, or any SSH client — all for $5–10/month in server costs on top of your existing Claude subscription.

The practical advantages:

• Session persistence. Long refactors, test suite runs, and multi-step agentic tasks finish even when you’re offline. tmux keeps every session alive indefinitely.
• Access from any device. Connect from your phone over SSH. Claude Code’s Remote Control feature (released February 2026) pairs naturally with a VPS setup.
• Consistent environment. No more “works on my machine” — the agent always operates in the same OS, same dependencies, same directory structure.
• Parallel agents. Run separate Claude Code sessions in separate tmux windows, each working on a different feature branch simultaneously. A 4-core / 8 GB VPS handles three to four concurrent sessions comfortably.
• Resource isolation. Move heavy AI workloads off your laptop. Your local machine stays responsive while the VPS does the heavy lifting.

The total cost: a $6/month VPS (Hetzner CX22, DigitalOcean Basic, or equivalent) plus your existing Claude Pro subscription ($20/month) equals $26/month for a persistent AI coding agent available 24/7 from any device.

2. System Requirements & VPS Sizing

Official system requirements

From the official Claude Code documentation (code.claude.com/docs/en/setup):

• Operating system: Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
• Hardware: 4 GB+ RAM, x64 or ARM64 processor
• Network: internet connection required
• Shell: Bash or Zsh
• Node.js: not required for the 2026 native installer (required only for the npm install path)

VPS sizing guide

Important note on RAM: Community reports confirm that 8 GB VMs can OOM-kill Claude Code under heavy orchestration loads. If you plan multi-agent workflows, provision 16 GB to be safe. Claude Code itself is lightweight, but the subprocesses it spawns (test runners, build tools, linters) add up quickly.

If you are below the 4 GB minimum, add swap space as a temporary buffer — it is not a substitute for RAM on compute-heavy tasks, but it prevents OOM kills during brief spikes:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Supported VPS providers

Claude Code works on all major VPS providers. Confirmed working setups have been reported on Hetzner, DigitalOcean, Vultr, Linode/Akamai, Hostinger, OVHcloud, and Fasthosts. The only known outlier is a single Contabo report that required a VPN, believed to be a Contabo-specific networking issue rather than a Claude Code limitation.

3. Installation: Three Methods

Claude Code offers three installation paths on Linux. The native installer is the recommended method for VPS use.

Method 1: Native installer (recommended)

The native installer is the fastest path. It does not require Node.js and sets up auto-updates automatically:

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

The installer places the claude binary at ~/.local/bin/claude and version files at ~/.local/share/claude. It adds ~/.local/bin to your PATH automatically by updating your shell profile.

To install the stable release channel (recommended for production — approximately one week behind latest, skips releases with major regressions):

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

To install a specific version:

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

Method 2: apt repository (Debian / Ubuntu)

The apt method integrates Claude Code into your system’s standard package management workflow. Updates arrive through apt upgrade rather than Claude Code’s built-in auto-updater:

# Step 1: Install the signing key
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc

# Step 2: Verify the GPG key fingerprint before trusting it
# Output must include: 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE
gpg --show-keys /etc/apt/keyrings/claude-code.asc

# Step 3: Add the repository
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list

# Step 4: Install
sudo apt update
sudo apt install claude-code

To upgrade later: sudo apt update && sudo apt upgrade claude-code

To use the rolling latest channel instead of stable, replace both occurrences of stable in the deb line with latest.

Method 3: npm (when Node.js is already present)

Use the npm path if your project already requires Node.js 18+ and you prefer a single package manager for tooling:

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

Critical: do not use sudo npm install -g. This leads to permission issues and security risks. If you encounter permission errors with global npm installs, configure npm to use a user-local directory instead:

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

To upgrade an npm installation: npm install -g @anthropic-ai/claude-code@latest. Do not use npm update -g — it respects the semver range from the original install and may not move you to the newest release.

Verify the installation

claude --version

For a comprehensive installation health check:

claude doctor

claude doctor shows the installed version, current auto-update status, most recent update attempt result, authentication state, and any configuration warnings. Run it after every fresh install and after every major upgrade.

Verify binary integrity (production environments)

For production deployments, verify the binary against Anthropic’s signed manifest before trusting it. This step is optional for personal setups but mandatory in any environment where supply chain integrity matters:

# Import Anthropic's release signing key
curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import

# Confirm the fingerprint
gpg --fingerprint security@anthropic.com
# Must include: 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE

# Download the manifest and its detached signature for your version
REPO=https://downloads.claude.ai/claude-code-releases
VERSION=2.1.89  # replace with your installed version
curl -fsSLO "$REPO/$VERSION/manifest.json"
curl -fsSLO "$REPO/$VERSION/manifest.json.sig"

# Verify the signature — must report "Good signature"
gpg --verify manifest.json.sig manifest.json

4. Authentication on a Headless Server

This is where most VPS setups fail. Claude Code defaults to a browser-based OAuth flow. A headless server has no browser, so the standard claude command hangs or errors out on first launch. You have three clean paths forward.

Authentication method comparison

Path A: API key authentication (recommended for most VPS setups)

Generate an API key at console.anthropic.com → API Keys → Create Key. API keys use pay-per-token billing through the Anthropic Console — separate from any Claude.ai subscription you hold.

Set the key as an environment variable on your VPS. Store it in a restricted file, not in .bashrc (which is world-readable by other processes and appears in shell history):

# Create a secure environment file
sudo mkdir -p /etc/claude-code
sudo tee /etc/claude-code/env <<'EOF'
ANTHROPIC_API_KEY=sk-ant-api03-YOUR-KEY-HERE
EOF
sudo chmod 600 /etc/claude-code/env
sudo chown $USER:$USER /etc/claude-code/env

Load it in your session:

set -a
source /etc/claude-code/env
set +a

To load it automatically on every login, add to ~/.profile (not .bashrc — .profile is sourced by login shells and picked up by tmux):

echo 'set -a; source /etc/claude-code/env; set +a' >> ~/.profile

Verify Claude Code accepts the key:

claude /status

Known interactive-mode issue: In some versions, Claude Code’s interactive mode may prompt for OAuth login even when ANTHROPIC_API_KEY is set. The documented workaround is to approve the key once on first interactive launch. After approval, your choice is remembered. You can also change it later under /config → “Use custom API key”.

Path B: OAuth token via claude setup-token (Pro / Max subscribers)

This method lets Pro and Max subscribers use their existing subscription on the VPS without paying per token. Run setup-token on your local machine (where you have a browser), then transfer the token to the VPS:

On your local machine:

claude setup-token

This generates a one-year OAuth token and prints it to stdout. Copy the full token string.

On the VPS:

# Store in the same secure env file
echo 'CLAUDE_CODE_OAUTH_TOKEN=your-token-here' | sudo tee -a /etc/claude-code/env
sudo chmod 600 /etc/claude-code/env

# Do NOT set ANTHROPIC_API_KEY at the same time
# Having both variables active causes conflicts

Reload the environment and verify:

source /etc/claude-code/env
claude /status

The token expires after one year. Set a calendar reminder to regenerate it with claude setup-token on your local machine approximately one week before expiry.

Path C: SSH-forwarded OAuth (one-time or testing)

If you need the browser OAuth flow without a setup-token, forward the authentication callback over SSH. On the VPS, run:

claude --no-browser

Claude Code prints a URL instead of trying to open a browser. Copy that URL and paste it into any browser on any device where you are logged into your Claude account. Complete the authorization. The VPS CLI picks up the token automatically.

This produces a session-scoped token, not a persistent credential. Suitable for testing; use Path A or B for production.

Skipping the onboarding prompts

On a fresh install, Claude Code shows onboarding screens on first launch. Skip them by pre-creating the config file:

cat > ~/.claude.json <<'EOF'
{
  "hasCompletedOnboarding": true,
  "lastShownAnnouncement": 99
}
EOF

5. Session Persistence with tmux

tmux is the single most important tool for running Claude Code on a VPS. Without it, any SSH disconnection — a dropped connection, a closed browser tab, a network hiccup — kills every running Claude Code session instantly. With tmux, sessions continue running on the server indefinitely regardless of your connection state.

Install tmux

sudo apt install tmux -y           # Ubuntu / Debian
# sudo dnf install tmux -y         # Fedora / RHEL
# sudo apk add tmux                # Alpine

Basic workflow

# Start a named tmux session
tmux new -s claude-main

# Inside the session: launch Claude Code
claude

# Detach from the session (session keeps running)
# Press: Ctrl+B, then D

# List all running sessions
tmux ls

# Reattach to your session (from any SSH connection, any device)
tmux attach -t claude-main

That is the entire core workflow. The session lives on the server, not in your terminal. Close your laptop. The agent is still running. Open your phone’s SSH client. Run tmux attach -t claude-main. You are back inside the exact session, exactly as you left it.

Essential tmux keybindings

Multi-agent pattern: one session per agent

# Start a backend refactor agent
tmux new -s claude-backend
# cd /path/to/backend && claude
# Ctrl+B, D to detach

# Start a frontend agent simultaneously
tmux new -s claude-frontend
# cd /path/to/frontend && claude
# Ctrl+B, D to detach

# Check on both agents any time
tmux ls
# claude-backend: 1 windows (created ...)
# claude-frontend: 1 windows (created ...)

# Jump to either agent
tmux attach -t claude-backend

Multi-agent pattern: multiple windows in one session

# Start a single session with multiple windows
tmux new -s agents

# Window 0 is created automatically — start the first agent
claude

# Create window 1 for the second agent
# Ctrl+B, then C
claude

# Switch between agents with Ctrl+B, N (next) or Ctrl+B, P (previous)
# Or by number: Ctrl+B, 0 / Ctrl+B, 1

Ensuring environment variables are available inside tmux

A common failure mode: you set ANTHROPIC_API_KEY in ~/.bashrc, but tmux starts sessions as login shells using ~/.profile, so the variable is not present inside Claude Code. The fix:

# Add your env to both files to cover all cases
echo 'set -a; source /etc/claude-code/env; set +a' >> ~/.profile
echo 'set -a; source /etc/claude-code/env; set +a' >> ~/.bashrc

Or pass the variable explicitly when creating a tmux session:

ANTHROPIC_API_KEY="sk-ant-api03-..." tmux new-session -d -s agent 'claude'

Optional: tmux configuration for comfort

cat > ~/.tmux.conf <<'EOF'
# Enable mouse support (click to select panes/windows)
set -g mouse on

# Increase scrollback buffer
set -g history-limit 50000

# Use Vim keybindings in copy mode
setw -g mode-keys vi

# Renumber windows when one is closed
set -g renumber-windows on

# Status bar: show session name and clock
set -g status-right '%H:%M %d-%b'
EOF

# Reload config without restarting tmux
tmux source-file ~/.tmux.conf

6. Configuration & CLAUDE.md

settings.json

Claude Code reads its configuration from ~/.claude/settings.json (user-level, applies to all projects) and from .claude/settings.json inside each project (project-level, overrides user settings for that project).

Create a sensible user-level configuration:

mkdir -p ~/.claude
cat > ~/.claude/settings.json <<'EOF'
{
  "autoUpdatesChannel": "stable",
  "env": {
    "DISABLE_AUTOUPDATER": "0"
  }
}
EOF

For servers where you want to lock to a specific release and prevent any automatic updates (useful in CI/CD environments where you control the version explicitly):

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.89",
  "env": {
    "DISABLE_UPDATES": "1"
  }
}

CLAUDE.md — the most important file you will create

CLAUDE.md is a Markdown file at the root of your project that Claude Code reads at the start of every session. It is how you give the agent persistent context about your project: architecture, conventions, commands to run before touching code, things to never do. Every minute you invest in writing a good CLAUDE.md pays back in every future session.

A minimal but effective CLAUDE.md:

# Project: my-app

## Stack
- Node.js 20, Express, PostgreSQL 16
- Tests: Vitest. Run with: `npm test`
- Lint: ESLint + Prettier. Run with: `npm run lint`
- Build: `npm run build` (outputs to ./dist)

## Before making any changes
1. Run `npm test` and confirm all tests pass.
2. Read the relevant module README in ./docs/.

## Conventions
- All database queries go through ./src/db/queries.ts — never raw SQL elsewhere.
- Environment variables are defined in .env.example. Never hardcode secrets.
- Commit messages: Conventional Commits format (feat:, fix:, chore:).

## Never do
- Never run `npm run db:reset` — this drops the production database.
- Never commit changes to .env or .env.production.
- Never push directly to main — always use a feature branch.

Claude Code also checks parent directories for CLAUDE.md files, which lets you create organization-wide or monorepo-wide conventions at the top-level directory that apply to every sub-project.

7. Security Hardening

Claude Code runs shell commands on your server. This is its power — and a meaningful attack surface if not configured carefully. Apply these hardening measures before exposing any Claude Code session to real work.

API key protection

# Store API keys in a restricted file, never in .bashrc or shell history
sudo mkdir -p /etc/claude-code
sudo tee /etc/claude-code/env <<'EOF'
ANTHROPIC_API_KEY=sk-ant-api03-YOUR-KEY-HERE
EOF
sudo chmod 600 /etc/claude-code/env
sudo chown $USER:$USER /etc/claude-code/env

# Verify permissions
ls -la /etc/claude-code/env
# -rw------- 1 youruser youruser

# Prevent API keys from appearing in shell history
export HISTIGNORE="*ANTHROPIC*:*API_KEY*:*TOKEN*"

Never store secrets in project files

Claude Code reads and modifies files in your working directory. If you store API keys, database passwords, or tokens in plain text files in your project, Claude Code will encounter them — and so will anyone who gains access to those files. Use environment variables and verify your .gitignore:

cat >> .gitignore <<'EOF'
.env
.env.local
.env.production
.env.*.local
*.key
*.pem
secrets/
EOF

CVE-2026-21852: trust prompt bypass (patched)

A vulnerability fixed in Claude Code 2.0.65 allowed malicious repositories to exfiltrate API keys before the trust prompt appeared. The attack vector: a repository’s settings file could set ANTHROPIC_BASE_URL to an attacker-controlled endpoint, and Claude Code would issue API requests before showing the “do you trust this repository?” prompt.

All users on auto-updates received this fix automatically. If you disabled auto-updates or installed via package manager, verify your version:

claude --version
# Must be 2.0.65 or later

If below 2.0.65:

# Native install
claude update

# apt
sudo apt update && sudo apt upgrade claude-code

The trust prompt — never skip it

When you open a new project directory, Claude Code asks whether you trust it. This prompt exists specifically to prevent the class of attack described above. Always read it. Never run --dangerously-skip-permissions on a repository you did not write yourself.

Firewall: lock down the VPS

# Allow only SSH and your application ports
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp      # SSH
sudo ufw allow 80/tcp      # HTTP (if serving web)
sudo ufw allow 443/tcp     # HTTPS (if serving web)
sudo ufw enable
sudo ufw status verbose

Run Claude Code as a dedicated non-root user

Never run Claude Code as root. Create a dedicated user for each project if you run multiple agents:

# Create a dedicated user
sudo useradd -m -s /bin/bash claude-agent
sudo passwd claude-agent

# Grant only necessary permissions
sudo usermod -aG sudo claude-agent  # only if agent needs sudo for build tools

# Switch to the dedicated user for Claude Code sessions
su - claude-agent

Restrict Claude Code’s working directory

Create a project-level .claude/settings.json that explicitly defines which tools are allowed. This reduces the blast radius if an agent is ever fed a malicious prompt:

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(git:*)",
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}
EOF

8. Run Claude Code as a systemd Service

For production CI/CD agents or automation pipelines that need to survive server reboots and restart automatically on failure, wrap Claude Code in a systemd service. This is the correct approach for long-running, non-interactive agentic workloads — not for interactive development sessions (use tmux for those).

sudo tee /etc/systemd/system/claude-agent.service <<'EOF'
[Unit]
Description=Claude Code Agent
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=simple
User=claude-agent
WorkingDirectory=/opt/my-project
EnvironmentFile=/etc/claude-code/env
ExecStart=/home/claude-agent/.local/bin/claude -p "your-task-description-here"
Restart=on-failure
RestartSec=10s

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/opt/my-project

# Logging
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable claude-agent
sudo systemctl start claude-agent
sudo systemctl status claude-agent

# Watch live logs
sudo journalctl -u claude-agent -f

Note: The -p flag runs Claude Code in non-interactive “print” mode with a single prompt. This is the correct mode for systemd services. Interactive sessions belong in tmux, not in service units.

9. Multi-Agent Workflows on a VPS

One of the most powerful patterns available on a VPS is running multiple Claude Code agents simultaneously, each working on a different task. The VPS’s persistent environment makes this practical in a way that a laptop never can be.

Git worktrees for agent isolation

When running multiple agents on the same repository, use Git worktrees to give each agent its own working tree. Changes in one agent’s tree do not affect others until explicitly merged — no race conditions, no conflicting file edits:

cd /opt/my-project

# Create isolated worktrees for two parallel agents
git worktree add ../my-project-feature-auth feature/auth
git worktree add ../my-project-feature-api feature/api

# List all worktrees
git worktree list

# Start Agent 1 in a tmux session
tmux new -s agent-auth
cd /opt/my-project-feature-auth
claude
# Ctrl+B, D to detach

# Start Agent 2 in another tmux session
tmux new -s agent-api
cd /opt/my-project-feature-api
claude
# Ctrl+B, D to detach

# Clean up a worktree when done
git worktree remove ../my-project-feature-auth

Memory limits per agent (preventing OOM)

With multiple agents running simultaneously, monitor and limit memory usage to prevent one misbehaving agent from OOM-killing the others:

# Check current memory per tmux session
# First get the PID of the claude process in each session
tmux list-panes -a -F "#{session_name} #{pane_pid}"

# Check memory usage
ps -o pid,rss,comm -p PID_HERE

# Set a memory limit with systemd-run for a new session (optional)
systemd-run --scope -p MemoryMax=2G tmux new -s limited-agent

10. MCP Server Integration

Claude Code supports the Model Context Protocol (MCP), allowing you to connect it to external data sources, tools, and APIs. On a VPS, MCP servers run as persistent processes alongside Claude Code — a natural fit for the always-on environment.

Configure MCP servers

Add MCP servers to ~/.claude/settings.json (user-level, available in all projects) or to .mcp.json at the project root (project-level):

# .mcp.json (project root — committed to version control for team sharing)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/opt/my-project"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    }
  }
}

List active MCP servers in a running Claude Code session:

/mcp

Security note: MCP server definitions loaded from a cloned repository are subject to the same trust prompt as the repository itself. Never approve an MCP server configuration from an untrusted source.

11. Updating & Version Pinning

Update immediately

claude update

Check current version and update status

claude doctor

Configure release channel

# In ~/.claude/settings.json
{
  "autoUpdatesChannel": "stable"    # "stable" or "latest"
}

Or via the interactive config menu: run claude, then type /config, then navigate to “Auto-update channel”.

Pin a minimum version (CI/CD and enterprise)

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.89"
}

This prevents auto-updates from installing any version below your pinned floor, while still allowing updates above it. Useful when you have tested a specific version in staging and want to prevent unexpected regressions in production.

Disable auto-updates entirely

{
  "env": {
    "DISABLE_UPDATES": "1"
  }
}

Use DISABLE_UPDATES (not DISABLE_AUTOUPDATER) to block all update paths including manual claude update. Use this when you distribute Claude Code through your own internal channels and need users to stay on the version you have validated.

Upgrade with apt

sudo apt update && sudo apt upgrade claude-code

12. Troubleshooting

“command not found: claude” after installation

The native installer adds ~/.local/bin to your PATH, but the change only takes effect in new shell sessions. Either open a new terminal or reload your profile:

source ~/.bashrc
# or
source ~/.profile

If the issue persists, confirm the binary exists and check PATH:

ls -la ~/.local/bin/claude
echo $PATH

“Login required” / browser prompt on a headless server

The OAuth browser flow is not available on a headless VPS. Use one of the three authentication paths from Section 4: set ANTHROPIC_API_KEY, generate a token with claude setup-token, or use claude --no-browser to get a URL to paste into any browser.

Environment variable not picked up inside tmux

Add your environment to ~/.profile (for login shells) in addition to ~/.bashrc. See Section 5 for the complete fix.

Out-of-memory kills under heavy load

# Check available memory
free -h

# Check which processes are using the most memory
ps aux --sort=-%mem | head -20

# Add swap if not present (see Section 2)
sudo fallocate -l 4G /swapfile

SSH connection drops during long sessions

This is exactly what tmux solves — the Claude Code session continues running regardless of SSH state. If you haven’t set up tmux yet, do it now (Section 5). Additionally, reduce SSH timeout issues:

# In ~/.ssh/config on your LOCAL machine
Host your-vps-ip
  ServerAliveInterval 60
  ServerAliveCountMax 3

Authentication expired (CLAUDE_CODE_OAUTH_TOKEN)

OAuth tokens generated by claude setup-token expire after one year. Regenerate on your local machine and update /etc/claude-code/env on the VPS:

# On your LOCAL machine
claude setup-token
# Copy the new token

# On the VPS — update the token in the env file
sudo nano /etc/claude-code/env
# Replace the old CLAUDE_CODE_OAUTH_TOKEN value with the new one
sudo chmod 600 /etc/claude-code/env

# Reload
source /etc/claude-code/env
claude /status

Multiple Claude Code installations conflicting

If claude doctor shows unexpected behavior or version mismatches, check for multiple installations:

which -a claude
# Should show only one path

If multiple paths appear, remove all but the one you intend to use. Start with a clean uninstall (Section 13) and reinstall from a single method.

13. Uninstalling Cleanly

Native installation

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

apt installation

sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc

npm installation

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

Remove all configuration and session data

Warning: this permanently deletes all settings, allowed tools, MCP server configurations, and session history.

rm -rf ~/.claude
rm -f ~/.claude.json
# Also remove the env file if you are fully decommissioning
sudo rm -rf /etc/claude-code

14. FAQ

Do I need a paid Claude subscription to use Claude Code on a VPS?

Yes. Claude Code requires a paid Claude Pro ($20/month), Max, Teams, Enterprise, or a Anthropic Console account with API credits. The free Claude.ai plan does not include Claude Code access.

Is it against Anthropic’s Terms of Service to run Claude Code on a VPS?

No. Running Claude Code on a VPS is explicitly supported and documented by Anthropic. Confirmed working setups exist on Hetzner, DigitalOcean, Vultr, Linode, and other major providers.

API key billing vs. subscription: which is cheaper for VPS use?

It depends on your usage pattern. Subscriptions (Pro at $20/month, Max at $100/month) are flat-rate and include Claude Code. API keys are pay-per-token and use separate Console billing. Heavy agentic workloads with many long context windows can easily exceed subscription costs on API billing — some developers report that a month of intensive Claude Code use would have cost over $1,000 at API rates. For most individual VPS users, a Pro or Max subscription with the OAuth token method (Path B) is the more predictable option. For automation pipelines and CI/CD where you need precise cost control and per-token visibility, API key billing makes more sense.

Can I run Claude Code on Alpine Linux?

Yes, but Alpine requires additional packages before installation. Alpine uses musl libc rather than glibc, which requires extra dependencies:

apk add libgcc libstdc++ ripgrep

Then set USE_BUILTIN_RIPGREP=0 in your settings.json and run the standard native installer.

How many concurrent Claude Code sessions can one VPS handle?

On a 4 GB RAM / 4 vCPU VPS, three concurrent sessions is the practical ceiling before noticeable memory pressure. At 8 GB RAM, four to six sessions are comfortable for typical codebases. At 16 GB RAM, you have significant headroom. The bottleneck is almost always RAM, not CPU — each session’s context window and spawned subprocesses (test runners, linters, build tools) are the dominant memory consumers.

Does Claude Code work on ARM64 VPS instances?

Yes. ARM64 is a fully supported architecture. The native installer automatically downloads the correct binary for your architecture. This covers Ampere-based instances on Oracle Cloud, AWS Graviton, Hetzner’s ARM Cloud servers (CAX line), and Raspberry Pi 5.

Can I use Claude Code on a VPS without a public IP?

Yes. Claude Code only needs outbound internet access to reach Anthropic’s API (api.anthropic.com). It does not need to be reachable from the public internet. A VPS behind NAT or in a private network with outbound access works fine. For inbound SSH access from your devices, consider Tailscale as a zero-configuration private network — it gives you a stable private IP for your VPS without exposing SSH to the public internet.

References

• Claude Code official setup documentation — Anthropic
• Claude Code authentication documentation — Anthropic
• Claude Code download page — Anthropic
• Anthropic Console — API key management and usage
• Anthropic supported countries

This guide reflects Claude Code’s native installer (2026) and the official documentation as of June 2026. Claude Code is developed by Anthropic PBC. All trademarks are the property of their respective owners.