Cách cài Claude Code lên VPS Ubuntu 24.04 trong 10 phút

Claude Code 2026 là agent terminal mạnh nhất hiện tại của Anthropic. Cài trên VPS Ubuntu rồi vibe code qua SSH từ điện thoại, laptop, iPad - vô cùng tiện. Bài này hướng dẫn cài từng bước, troubleshoot lỗi thường gặp, và setup nâng cao với tmux + MCP. Phù hợp dev VN mới làm quen Claude Code hoặc đang chuyển từ Cursor/Aider.

Mình test trên VPS Cloud TND gói Basic 2GB RAM Ubuntu 24.04.2 mới fresh install. Tổng thời gian từ SSH lần đầu tới chạy được câu prompt đầu tiên: 10 phút (gồm tải Node.js + login). Không cần kiến thức Linux nâng cao, copy paste là chạy được.

Mục tiêu cuối bài: bạn có Claude Code chạy trên VPS, login subscription hoặc API key, hiểu cách dùng tmux để task chạy nền, biết troubleshoot lỗi npm phổ biến, và setup MCP server đầu tiên (Filesystem).

1. Vì sao cài Claude Code trên VPS thay vì laptop?

• Vibe code từ mobile: SSH qua Termius/Tabby, agent chạy trên VPS, bạn chỉ là client - viết code từ điện thoại Android cũng được.
• Network ổn định: VPS có uptime 99.9%, không lo wifi nhà bị mất, không lo battery laptop hết.
• Background agent: tmux + Claude headless chạy 8h đêm, sáng review PR.
• Tách môi trường dev: VPS có tools sẵn (Docker, DB, n8n), không làm bẩn laptop personal.
• Latency tốt: VPS HCM/HN tới Anthropic us-east ~200ms, tương đương laptop nhà.

2. Yêu cầu VPS

VPS Cloud TND gói Basic 2GB/2vCPU/40GB SSD CEPH chạy thoải mái Claude Code + project Next.js/Python + tmux 4 session. Giá ~250k/tháng, ROI cực cao so với pricing Claude Code subscription.

3. SSH vào VPS lần đầu

# Từ máy local
ssh [email protected]
# Hoặc dùng SSH key
ssh -i ~/.ssh/vps-key [email protected]

# Update system trước
apt update && apt upgrade -y
apt install -y curl git build-essential

# Tạo user dev (không nên dùng root chạy Claude)
useradd -m -s /bin/bash dev
usermod -aG sudo dev
passwd dev
su - dev

Luôn tạo user thường để chạy Claude Code, không dùng root. Lý do: agent có thể chạy shell command, root quyền cao có thể vô tình xoá hệ thống. User dev có sudo password, an toàn hơn.

4. Cài Node.js 22 LTS

Claude Code yêu cầu Node.js 22 trở lên (npm 10+). Ubuntu 24.04 mặc định có Node 20, cần update.

# Cài qua NodeSource (khuyến nghị)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Kiểm tra
node --version  # v22.x.x
npm --version   # 10.x.x

Cách thay thế: dùng nvm (Node Version Manager) nếu cần nhiều version Node song song. Mình hay dùng nvm vì quản lý dễ:

# Cài nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

# Cài Node 22
nvm install 22
nvm use 22
nvm alias default 22

5. Cài Claude Code

# Cài global
npm install -g @anthropic-ai/claude-code

# Kiểm tra
claude --version
# Output: claude-code 1.x.x

Lỗi phổ biến lúc này: EACCES: permission denied khi npm install global. Lý do: npm prefix mặc định /usr/lib/node_modules thuộc root. Fix bằng cách đổi prefix sang home user:

mkdir -p ~/.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

6. Login Claude Code: subscription hay API key

Claude Code có 2 cách auth:

• Subscription (Pro 20$/Max 100-200$): chạy claude, nó in URL, copy URL paste vào browser laptop để login, claude.ai redirect về token. Quota chia sẻ với web Claude.
• API key (pay-as-you-go): tạo key tại console.anthropic.com, export ANTHROPIC_API_KEY=$YOUR_KEY. Tính phí theo token, đắt hơn nếu dùng nhiều nhưng linh hoạt cho team share key.

# Cách 1: subscription
claude
# Mở URL hiện ra trong browser, login claude.ai, copy token paste vào terminal

# Cách 2: API key
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx' >> ~/.bashrc
source ~/.bashrc
claude

Khuyến nghị cho dev cá nhân: subscription Pro 20$ là sweet spot. Quota đủ cho 4-5 giờ/ngày làm việc. Nâng Max 5x khi nào hay bị "context limit reached" 2-3 lần/ngày.

7. Chạy prompt đầu tiên

# Tạo project test
mkdir -p ~/projects/hello-claude
cd ~/projects/hello-claude
echo "# Hello Claude project" > README.md
git init && git add . && git commit -m "init"

# Khởi động Claude
claude
# Prompt: "Tạo file index.js in 'Hello Claude Code'"
# Agent sẽ tạo file, hỏi confirm, save

Nếu thấy file index.js xuất hiện, Claude in "Hello Claude Code" - bạn đã setup thành công. Bây giờ thử task thật:

# Prompt advanced
"Tạo Express API server port 3000 với endpoint /hello trả JSON {message: 'hi'}, viết test với supertest, chạy npm test"
# Claude tự npm init, install express + supertest, viết code, chạy test

8. tmux: giữ session không bị mất khi SSH disconnect

Vấn đề: SSH disconnect (wifi rớt, đóng laptop) thì Claude Code đang chạy bị kill. Giải pháp: tmux - terminal multiplexer.

sudo apt install -y tmux

# Tạo session mới tên 'claude'
tmux new -s claude

# Trong tmux, chạy claude
cd ~/projects/myapp
claude

# Detach: Ctrl+B rồi D
# Reattach từ SSH session mới
tmux attach -t claude

# Liệt kê session
tmux ls
# Kill session
tmux kill-session -t claude

Mình có 3 session tmux cố định: claude (Claude Code chính), dev (terminal chạy npm/git), logs (tail logs). Mỗi lần SSH vào VPS chỉ cần tmux a -t claude là quay lại trạng thái cũ.

9. Vibe code từ mobile qua Termius/Tabby

• Termius (Android/iOS): free tier đủ dùng cá nhân, sync key giữa thiết bị.
• Tabby (Android): open source, UI hiện đại hơn.
• Cấu hình SSH key: generate trên VPS user dev, import private key vào app mobile.
• Mở tmux session claude, gõ prompt từ on-screen keyboard hoặc Bluetooth keyboard.
• Mẹo: bật "haptic feedback" và tăng font 16-18px cho dễ đọc.

Mình đã code Next.js prototype trên Pixel 8 + Logitech keys K580 trong quán cà phê, latency 250ms vẫn mượt. Tương lai của vibe coding là mobile + cloud + AI.

10. Tạo file CLAUDE.md cho project

CLAUDE.md là file Claude Code tự đọc đầu mỗi session, giúp agent hiểu rules của project. Tương đương .cursorrules.

# Tạo CLAUDE.md trong root project
cat > CLAUDE.md << "RULES"
# Project rules

## Stack
- Next.js 15 App Router, TypeScript strict
- Prisma + Postgres
- TailwindCSS + shadcn/ui

## Conventions
- File naming kebab-case
- Components PascalCase
- Server Actions trong app/actions/

## Don't
- Don't commit secrets
- Don't bypass type errors with any
RULES

Lưu ý: file CLAUDE.md không có heredoc trong bash code block (mình dùng quote khác). Tạo file lần đầu bằng nano nếu khó, sau đó Claude sẽ tự update khi bạn yêu cầu.

11. Gắn MCP server đầu tiên

MCP (Model Context Protocol) mở rộng Claude Code với tool ngoài (Filesystem, DB, browser, GitHub). Cài MCP Filesystem để Claude đọc file ngoài CWD:

# Cài MCP server filesystem
npm install -g @modelcontextprotocol/server-filesystem

# Đăng ký với Claude Code
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/dev/projects

# Liệt kê MCP đã có
claude mcp list

# Trong session claude, dùng tool
# Prompt: "Liệt kê file trong /home/dev/projects"

MCP popular khác: @modelcontextprotocol/server-postgres (query DB), @modelcontextprotocol/server-puppeteer (browser automation), @modelcontextprotocol/server-github (gh API).

12. Troubleshoot lỗi thường gặp

• "npm ERR! code EACCES": đổi npm prefix sang ~/.npm-global như bước 5.
• "Login failed, code expired": URL token chỉ valid 5 phút. Chạy claude /logout rồi login lại.
• "Context length exceeded": dùng /clear để reset context, hoặc /compact để giữ summary.
• "Rate limit reached": đợi 5 phút, hoặc upgrade subscription, hoặc switch sang API key billing riêng.
• Permission denied khi sửa file: chmod 755 thư mục project, hoặc chown dev:dev -R.
• Out of memory khi build: bật swap 4GB trên VPS 2GB: fallocate -l 4G /swap; chmod 600 /swap; mkswap /swap; swapon /swap.

FAQ

VPS 1GB RAM có chạy Claude Code được không?

Chạy được nhưng có giới hạn. Node.js + Claude idle ~400-500MB. Khi build project Next.js có thể peak 800MB-1GB, dễ OOM. Khuyến nghị bật swap 2-4GB nếu phải dùng VPS 1GB. Tốt nhất là VPS 2GB để chạy thoải mái cả Claude + npm install + DB local.

Subscription Pro 20$ có dùng được trên VPS không?

Có. Login qua browser laptop, paste token vào terminal VPS. Token lưu trong ~/.claude/credentials.json, valid 30 ngày. Sau đó refresh tự động khi gọi API. Một subscription dùng được trên nhiều thiết bị nhưng cùng tài khoản claude.ai, không share giữa users.

Có cần root để cài Claude Code không?

Không bắt buộc. Cài npm với prefix ~/.npm-global (user thường) là đủ. Khuyến nghị KHÔNG dùng root vì agent có thể chạy shell command, root quyền cao có thể vô tình xoá hệ thống. Luôn tạo user dev có sudo password, login bằng user đó.

Latency từ VN tới Anthropic API như thế nào?

VPS TND HCM tới Anthropic us-east-1 trung bình 200-230ms. First token thường 500-800ms (Sonnet 4.7). Stream sau đó mượt ~50ms/token. Đủ tốt cho vibe coding, hơi chậm cho autocomplete inline. Nếu cần latency thấp hơn, cân nhắc VPS region Asia (Tokyo/Singapore) - giảm còn 150ms nhưng đắt hơn.

Có thể chạy Claude Code song song với Aider trên cùng VPS?

Hoàn toàn được. Mỗi tool tách tmux session riêng. Khuyến nghị: mỗi session chỉ làm việc với 1 repo Git khác nhau (hoặc 1 branch khác), tránh xung đột edit cùng file. Cài cả hai trên VPS 4GB chạy đồng thời thoải mái, không tăng đáng kể RAM idle.

Làm thế nào để Claude Code không xoá nhầm file?

Mặc định Claude Code hỏi confirm trước mọi destructive command (rm, git reset, drop table). Đừng dùng flag --dangerously-skip-permissions trừ khi sandbox. Quy tắc: luôn git commit trước khi chạy task lớn để có thể revert. Pre-commit hook chạy lint giúp catch lỗi sớm.