Remote Claude Code on VPS

Run Claude Code on a VPS and access it from your phone, tablet, or any device with a terminal app. Code from anywhere.

Tested on Ubuntu 20.04+ / Debian 10+. Other distros may require adjustments.

What You'll Need

• A VPS (Hostinger, Hetzner, DigitalOcean, etc.) - $5/mo tier is plenty
• 4GB RAM minimum, 8GB+ recommended
• A mobile SSH client (Termius recommended)

---

Quick Start

1. Spin Up Your VPS

If using Hostinger, select the "Claude Code" app template during setup - it comes pre-installed.

For manual installation on any VPS:

# SSH into your VPS
ssh root@your-vps-ip

# Install Claude Code (native installer - recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Ensure the native install symlink is on your PATH
export PATH="$HOME/.local/bin:$PATH"

# Make it persistent for future logins
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
claude doctor

# Start Claude Code
claude

Note: The native installer is the recommended path. npm install is deprecated and requires Node.js 18+ only for that legacy method.

---

2. Secure Your VPS (Important!)

Before accessing from mobile, lock down your server:

# Make sure you have a non-root user with an SSH key before doing this

# Add a clear SSH hardening drop-in (SSH keys only)
sudo mkdir -p /etc/ssh/sshd_config.d
sudo tee /etc/ssh/sshd_config.d/99-claude-hardening.conf >/dev/null <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
EOF

# Test SSH config before restarting
sudo sshd -t && sudo systemctl restart ssh

# Install fail2ban to block brute force attacks
sudo apt install fail2ban -y

# Enable firewall - only allow SSH
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Tip: Run Claude Code as a non-root user. Avoid working as root.

---

3. Set Up Mobile Access

1. Download Termius on your phone (iOS/Android) - it's free
2. Add a new host with your VPS IP address
3. Connect using your SSH key (passwords disabled)

---

4. Session Persistence with tmux

Keep your Claude Code session alive even when your phone disconnects:

# Install tmux
sudo apt install tmux -y

# Start a new named session
tmux new -s claude

# Run Claude Code inside the session
claude

Enable mouse scrolling (so you can scroll with your finger):

echo "set -g mouse on" >> ~/.tmux.conf && tmux source-file ~/.tmux.conf

Reconnect to your session after disconnect:

tmux attach -t claude

---

5. Optional: Claude Code Self-Hardening (Recommended)

Create a project-level .claude/settings.json to block access to common secret files:

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}
EOF

This uses Claude Code permissions to make those files invisible to the tool. Commit the file for team-wide safety, or use .claude/settings.local.json if you want it to stay local.

---

Quick Reference

Command	What it does
tmux new -s claude	Start a new tmux session named "claude"
tmux attach -t claude	Reconnect to your session
tmux ls	List all sessions
Ctrl+B, D	Detach from session (leave it running)

---

Troubleshooting

OAuth/Authentication Issues on Headless VPS

If Claude Code can't complete OAuth login:

# If the browser doesn't open, press "c" to copy the OAuth URL
# Paste it into your browser and finish login there

If login gets stuck, try:

1. /logout
2. Exit Claude
3. Run claude again

claude Command Not Found / PATH Issues

The native installer creates a symlink at ~/.local/bin/claude. Make sure ~/.local/bin is on your PATH, then run:

claude doctor

Can't Scroll in tmux on Mobile

Make sure mouse mode is enabled:

echo "set -g mouse on" >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

Session Dies When Phone Sleeps

This is why we use tmux! Your session keeps running. Just reconnect with:

tmux attach -t claude

Memory Issues on Long Sessions

Claude Code can use significant memory. Use /compact to reduce context size and restart between major tasks if needed. If you're on a 4GB VPS and hit memory pressure, consider enabling swap.

---

VPS Recommendations

Provider	Price	Notes
Hostinger	~$5/mo	Has Claude Code pre-installed template
Hetzner	~$5/mo	Great value, Europe-focused
Vultr	~$12/mo	Fast performance
DigitalOcean	~$6/mo	Developer-friendly

---

Resources

Resource	Notes
Claude Code Documentation	Official docs
Termius	Mobile SSH client
tmux Cheat Sheet	tmux reference

---

Security Note

Treat Claude Code as a powerful local agent. Review permissions, avoid running as root, and audit .claude/settings.json in shared repos.

---

License

MIT - Do whatever you want with this.