Here’s a current guide for getting Claude Code running on a remote Ubuntu VPS.
Prerequisites
You need a VPS with at least 4 GB RAM (8 GB recommended), running Ubuntu 24.04+, and an Anthropic account with a paid plan — Claude Code requires a Pro, Max, Teams, Enterprise, or Console account; the free Claude.ai plan does not include Claude Code access. You’ll also need SSH access to your server and tmux for session persistence.
Step 1: Secure your server
SSH in as root and create a non-root user:
ssh root@your-server-ip
adduser deploy
usermod -aG sudo deploy
# Set up SSH key auth (run from your LOCAL machine)
ssh-copy-id deploy@your-server-ip
Then disable password authentication and set up a firewall:
sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd
sudo apt install ufw fail2ban -y
sudo ufw allow OpenSSH
sudo ufw enable
sudo systemctl enable fail2ban
Step 2: Install Claude Code
As of March 2026, the recommended installation method is the native CLI installer, which requires zero dependencies, auto-updates in the background, and works on Linux. No Node.js needed.
SSH in as your deploy user and run:
curl -fsSL https://claude.ai/install.sh | sh
Verify it installed:
claude --version
Run the built-in diagnostic to check your environment:
claude doctor
Step 3: Authenticate (headless — no browser)
This is the trickiest part on a VPS since the standard login flow requires opening a local web browser, which isn’t available on a headless server. You have two options:
Option A: API key (simplest for headless)
If you have a Claude Console account (API-based billing), set the ANTHROPIC_API_KEY environment variable. Generate a key at console.anthropic.com, then on your VPS:
# Store the key securely
mkdir -p ~/.config/claude-code
echo 'ANTHROPIC_API_KEY=sk-ant-api03-your-key-here' > ~/.config/claude-code/.env
chmod 600 ~/.config/claude-code/.env
# Load it in your shell profile
echo 'set -a; source ~/.config/claude-code/.env; set +a' >> ~/.bashrc
source ~/.bashrc
Option B: OAuth token (for Pro/Max subscription users)
Run claude setup-token on your local machine (one with a browser) to create a one-year OAuth token. Then set it on your VPS:
export CLAUDE_CODE_OAUTH_TOKEN="your-token-here"
echo 'export CLAUDE_CODE_OAUTH_TOKEN="your-token-here"' >> ~/.bashrc
Do not set ANTHROPIC_API_KEY at the same time, as having both variables active can cause conflicts.
Option C: SSH port forwarding
If you prefer the browser-based OAuth flow, forward the port from the remote machine to your local browser:
# From your LOCAL machine
ssh -L 8080:localhost:8080 deploy@your-server-ip
Then in the SSH session, run claude and complete the /login flow — the auth URL will open in your local browser via the forwarded port.
Step 4: Set up tmux for persistent sessions
tmux creates terminal sessions that persist on the server independently of your SSH connection. Close your laptop, reconnect later — Claude Code is still running.
sudo apt install tmux -y
# Start a named session
tmux new-session -s claude
# Inside tmux, start Claude Code
cd ~/your-project
claude
When you need to disconnect, press Ctrl+B then D to detach. Reconnect later with:
tmux attach -t claude
A helpful tmux config to add to ~/.tmux.conf:
set -g mouse on
set -g default-terminal "screen-256color"
set -g history-limit 50000
Step 5: Add swap (recommended for 4 GB VPS)
Multi-agent sessions that spawn many sub-agents consume memory per agent. Adding swap prevents OOM kills:
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
Step 6: Verify everything works
tmux attach -t claude # or start a new session
claude
/status # check auth and model
/doctor # run diagnostics
Quick reference
| Item | Detail |
|---|---|
| Min specs | 2 vCPU, 4 GB RAM, 20 GB disk |
| Installer | curl -fsSL https://claude.ai/install.sh | sh |
| Auth (API) | export ANTHROPIC_API_KEY=sk-ant-... |
| Auth (OAuth) | claude setup-token locally, then set CLAUDE_CODE_OAUTH_TOKEN on VPS |
| Persist sessions | tmux |
| Auto-updates | Native installations automatically update in the background |
| Credentials on Linux | Stored in ~/.claude/.credentials.json, written with mode 0600 |
For the full official docs, see code.claude.com/docs/en/setup and code.claude.com/docs/en/authentication.