SSH Remote Development Intermediate

Running Claude Code on remote servers via SSH opens up powerful workflows - from debugging production issues to developing on high-powered cloud machines. Learn how to set up persistent sessions, forward connections, and integrate with VS Code Remote.

Running Claude Code on Remote Servers

The simplest way to use Claude Code remotely is to SSH into a server where Claude Code is installed:

Terminal

# SSH into your server
$ ssh user@your-server.com

# Set up API key on the remote machine
$ export ANTHROPIC_API_KEY="sk-ant-..."

# Navigate to your project and start Claude Code
$ cd /home/user/my-project
$ claude

# Or use one-shot mode
$ claude -p "Fix the memory leak in the worker process"

Install on Remote: Make sure Node.js and Claude Code are installed on the remote server. Use npm install -g @anthropic-ai/claude-code to install Claude Code globally.

SSH Forwarding and Tunnels

If your remote server cannot directly access the Anthropic API (e.g., behind a corporate firewall), you can use SSH tunneling:

Terminal

# Forward agent for key-based auth on remote
$ ssh -A user@your-server.com

# SSH config for persistent settings (~/.ssh/config)
Host dev-server
    HostName your-server.com
    User developer
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

# Connect using the config alias
$ ssh dev-server

Persistent Sessions with tmux/screen

SSH connections can drop. Use tmux or screen to keep Claude Code sessions running even if your connection is interrupted:

Terminal

# Using tmux (recommended)
$ ssh user@server
$ tmux new -s claude-session

# Inside tmux, start Claude Code
$ cd /project
$ claude

# Detach from tmux: Ctrl+B, then D
# Your Claude session keeps running!

# Reattach later (even from a different SSH session)
$ ssh user@server
$ tmux attach -t claude-session

# Using screen (alternative)
$ screen -S claude-session
$ claude
# Detach: Ctrl+A, then D
# Reattach: screen -r claude-session

tmux Tips: Create a ~/.tmux.conf file on your remote server to customize the experience. Set set -g mouse on for mouse support, and set -g history-limit 50000 for longer scrollback to review Claude's output.

Remote File Editing

Claude Code on a remote server edits files directly on that server - no file syncing needed:

Terminal

# On the remote server, Claude edits files in place
$ ssh user@production-server
$ cd /var/www/my-app
$ claude -p "Fix the N+1 query in app/models/user.rb"

# Changes are made directly on the server
$ git diff  # See what Claude changed
$ git stash # Revert if needed

Working with Remote Git Repos

Claude Code works seamlessly with git repositories on remote servers:

Terminal

# Clone and work on a remote server
$ ssh user@dev-server
$ git clone git@github.com:team/project.git
$ cd project
$ claude

# Claude can create branches, commit, and push
> Create a feature branch, implement the user avatar upload feature, and commit the changes

# Or use one-shot for quick git operations
$ claude -p "Review the last 5 commits and create a summary"

Authentication on Remote Machines

Setting up authentication properly on remote servers is critical:

Bash

# Option 1: Add to .bashrc or .zshrc on the remote server
export ANTHROPIC_API_KEY="sk-ant-..."

# Option 2: Use a .env file (add to .gitignore!)
echo 'ANTHROPIC_API_KEY=sk-ant-...' > ~/.claude-env
source ~/.claude-env

# Option 3: Use a secrets manager
export ANTHROPIC_API_KEY=$(vault kv get -field=api_key secret/claude)

# Option 4: Pass via SSH environment (add to ~/.ssh/environment on server)
# Requires PermitUserEnvironment yes in sshd_config
ANTHROPIC_API_KEY=sk-ant-...

VS Code Remote SSH + Claude

Combine VS Code's Remote SSH extension with Claude Code for the best of both worlds:

Install Remote - SSH extension in VS Code
Search for "Remote - SSH" in the VS Code extensions marketplace and install it.
Connect to your remote server
Use Ctrl+Shift+P → "Remote-SSH: Connect to Host" and enter your server address.
Open the integrated terminal
The terminal in VS Code Remote SSH runs on the remote server. Start Claude Code here.
Use Claude Code in the terminal
Claude Code runs on the remote machine, edits remote files, and you see the changes in VS Code instantly.

Best Combo: VS Code Remote SSH lets you browse and edit files visually, while Claude Code in the integrated terminal handles complex, multi-file refactoring. Use both together for maximum productivity.

Performance Considerations

Factor	Impact	Mitigation
Network latency	Adds delay to each API call	Choose a server close to Anthropic's API endpoints
SSH connection drops	Can interrupt Claude sessions	Use tmux/screen; set SSH keepalive
Server resources	Claude Code uses Node.js, needs RAM	Ensure at least 512MB free RAM
Large codebases	File reading over SSH is already local	Actually faster than local for large repos on fast servers

Try It Yourself

SSH into a remote server, install Claude Code, and try running a simple claude -p command. Use tmux to keep your session alive. Next up: running Claude Code inside Docker containers.

Next: Docker Integration →

← Headless Mode Docker Integration →

Ready to Go Deeper?

Live instructor-led courses from our partners. Affiliate disclosure.

🧠

AI & ML Courses - 30% Off

Live instructor-led AI, machine learning, data science, and cloud courses for working professionals. Use code Limited30 at checkout.

Edureka

📊

DataCamp - AI & Data Science

Hands-on Python, machine learning, and AI courses with interactive exercises and real projects.

DataCamp

🎓

edX - Top AI Courses

University-level AI courses from MIT, Harvard, Stanford. Earn certificates that employers recognize.

edX