Installing Claude Code on a remote VPS (Ubuntu 20+) guide

1

I’ll create a comprehensive guide for installing and configuring Claude Code on a remote Ubuntu 22+ VPS. This setup is particularly useful for persistent long-running tasks, team collaboration, or offloading heavy computational work from your local machine.

Claude Code Remote VPS Installation Guide

Prerequisites

  • Ubuntu 22.04 LTS or newer
  • SSH access with sudo privileges
  • Minimum 2GB RAM (4GB+ recommended for large codebases)
  • Node.js 18+ and npm

1. System Preparation

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install essential build tools
sudo apt install -y curl git build-essential python3 python3-pip

# Install Node.js 20.x (LTS)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version  # Should show v20.x.x
npm --version   # Should show 10.x.x

2. Install Claude Code CLI

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

# Verify installation
claude --version

3. Authentication Setup (Headless/Remote)

Since you’re on a remote VPS without browser access, use API key authentication:

# Set your Anthropic API key as environment variable
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# Add to ~/.bashrc for persistence
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"' >> ~/.bashrc
source ~/.bashrc

Alternative: Create a config file at ~/.anthropic/settings.json:

{
  "apiKey": "sk-ant-api03-your-key-here"
}

4. SSH Session Persistence (Critical for Remote)

Since Claude Code sessions can be long-running, set up persistent sessions:

# Install tmux
sudo apt install -y tmux

# Create new session
tmux new -s claude-session

# Inside tmux, run claude
claude

# Detach: Ctrl+B, then D
# Reattach later: tmux attach -t claude-session

Or use screen:

sudo apt install -y screen
screen -S claude
# Run claude, detach with Ctrl+A+D, reattach with screen -r claude

5. Project Setup & Workspace

# Create workspace directory
mkdir -p ~/workspace
cd ~/workspace

# Clone your repository (example)
git clone https://github.com/your-org/your-project.git
cd your-project

# Launch Claude Code in project directory
claude

6. Security Hardening (Essential for VPS)

# Create dedicated user for Claude Code (don't run as root)
sudo adduser claude-user
sudo usermod -aG sudo claude-user
su - claude-user

# Set proper permissions
chmod 600 ~/.bashrc
chmod 600 ~/.anthropic/settings.json 2>/dev/null || true

# If using tmux, secure socket
chmod 700 ~/.tmux

7. Systemd Service (Optional - Auto-restart)

Create a persistent service for 24/7 availability:

sudo tee /etc/systemd/system/claude-code@.service > /dev/null <<EOF
[Unit]
Description=Claude Code Session for %i
After=network.target

[Service]
Type=forking
User=%i
WorkingDirectory=/home/%i/workspace
ExecStart=/usr/bin/tmux new-session -d -s claude-%i -c /home/%i/workspace 'claude'
ExecStop=/usr/bin/tmux kill-session -t claude-%i
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable claude-code@claude-user
sudo systemctl start claude-code@claude-user

8. Remote Access Patterns

From your local machine, connect to VPS session:

# SSH with port forwarding (if needed for local browser preview)
ssh -L 3000:localhost:3000 user@vps-ip

# Attach to running Claude session
tmux attach -t claude-session

File Sync Strategy:

# Use rsync to sync project files between local and VPS
rsync -avz --exclude 'node_modules' --exclude '.git' ./ user@vps:~/workspace/project/

# Or set up SSHFS for real-time editing
sshfs user@vps:~/workspace/project ~/remote-project

9. Resource Monitoring

# Monitor Claude Code resource usage
htop

# Check disk space (Claude can generate large artifacts)
df -h

# Monitor network for API calls
sudo apt install -y iftop
sudo iftop -i eth0

10. Troubleshooting Common Issues

Node.js Version Too Old:

# If you get ESM module errors, ensure Node 18+
npm install -g n
n 20

Permission Denied on Global Install:

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

API Key Not Recognized:

# Verify environment variable
echo $ANTHROPIC_API_KEY

# Check if Claude Code config exists
cat ~/.config/claude/config.json

11. Optimization for VPS (Low Resource)

# Create swap file if RAM < 4GB
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

Quick Start Summary

# One-liner setup for fresh Ubuntu 22.04 VPS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && \
sudo apt install -y nodejs git tmux && \
npm install -g @anthropic-ai/claude-code && \
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.bashrc && \
source ~/.bashrc && \
tmux new -s claude

Security Checklist

  • Use dedicated non-root user
  • API key stored in environment variable (not hardcoded)
  • SSH key authentication only (disable password auth)
  • Firewall enabled (ufw) with only necessary ports open
  • Regular security updates (sudo apt update && sudo apt upgrade -y)
  • Consider VPN or jump host for additional access control

This setup gives you a persistent, secure Claude Code environment accessible from anywhere, ideal for your workflow involving OpenClaw integrations and long-running automation tasks.