Remote Claude Code and SSH Sessions
Run Claude Code on any remote machine — EC2, VPS, your home server. SSH + tmux keeps sessions alive across disconnections. Full tool access on the remote filesystem. Here is the complete setup.
Claude Code is not local-only. It runs anywhere Node.js runs — which means EC2 instances, VPS servers, your Mac Mini in the home lab, cloud workspaces. When the code and data are on a remote machine, running Claude Code locally and pointing it at remote files adds latency, permission friction, and coordination overhead. Run Claude Code on the machine where the work is.
This lesson covers the setup that makes remote sessions as comfortable as local ones.
When Remote Makes Sense
Running Claude Code remotely is the right choice when:
- The data lives there. Database files, large datasets, production logs — if the files are remote and Claude needs to read them, local operation means copying them first.
- The environment is there. Your staging server has the exact config and services needed to test. Running Claude Code there means it can run the actual test suite against the real environment.
- The deployment target is there. Having Claude deploy to a server while running on that server eliminates the SSH-deploy friction entirely.
- Long-running tasks. A task that takes 4 hours runs better on a dedicated server than on your laptop that needs to close its lid.
SSH + tmux: The Core Pattern
The combination is simple and robust. SSH gives you a terminal on the remote machine. tmux creates a persistent session that survives disconnections.
Install tmux on the remote machine:
# Ubuntu/Debian
sudo apt-get install -y tmux
# macOS (Homebrew)
brew install tmux
Connect and create a named session:
ssh user@your-server
tmux new-session -s dev
Inside the tmux session, start Claude Code:
cd /path/to/your/project
export ANTHROPIC_API_KEY="$(cat ~/.secrets/anthropic-key)"
claude
Claude Code launches, reads your project, and begins. If your SSH connection drops — bad WiFi, laptop sleep, network hiccup — the tmux session continues running on the server. Your Claude Code session is mid-task and finishes uninterrupted.
Reattach from any terminal:
ssh user@your-server
tmux attach -t dev
You are back in the session exactly where you left it.
Skipping Permission Prompts
Claude Code normally asks for confirmation before running commands and modifying files. In a remote environment — especially for automated tasks — you often want to skip these prompts:
claude --dangerously-skip-permissions
This flag bypasses the interactive permission dialogs. Only use it in environments where you trust the operation and you understand what Claude will do. Good use: deploying to a staging server you control. Bad use: production databases without a separate backup-first step.
Injecting Secrets Safely
This is the piece most people get wrong. The cardinal rule: API keys and credentials live in your local keychain or a secrets manager, not in files on remote machines.
The pattern for injecting secrets at launch time:
# Option A: Pass via env at launch
ANTHROPIC_API_KEY="$(op read 'op://vault/anthropic/key')" claude
# Option B: Load from a local-only env file that is never committed
source ~/.secrets/remote-env.sh && claude
# Option C: Use a secrets manager that injects at runtime
aws secretsmanager get-secret-value --secret-id prod/anthropic/key \
--query SecretString --output text | \
ANTHROPIC_API_KEY="$(cat)" claude
What NOT to do:
# BAD — plaintext key in shell history
export ANTHROPIC_API_KEY="sk-ant-..."
claude
# BAD — key committed in a file the repo can read
cat ~/project/.env # contains ANTHROPIC_API_KEY
Rotate keys after any session on a machine you do not fully control. This is not paranoia — it is correct security hygiene.
You are in command of your security posture. Take charge of it before it becomes someone else's leverage against you.
SSH Config for Comfort
Typing ssh user@<server-ip> repeatedly is friction. Eliminate it:
# ~/.ssh/config
Host remote-dev
HostName your-server.example.com
User your-user
IdentityFile ~/.ssh/id_ed25519
ServerAliveInterval 60
ServerAliveCountMax 3
ServerAliveInterval and ServerAliveCountMax keep the connection alive through idle periods. Now ssh remote-dev is the entire command.
Remote Claude Code with a Specific Project CLAUDE.md
The remote machine checks out the project's CLAUDE.md just like your local machine does. If your remote server runs a different OS or has different paths, consider a server-specific CLAUDE.md override:
# On the remote server, in the project root:
cat >> CLAUDE.md << 'EOF'
## Remote Server Context
- This is the remote development server (Ubuntu 22.04, ARM64)
- Python: /usr/bin/python3.12
- Node: /usr/local/bin/node (v20)
- Services available: PostgreSQL on localhost:5432
- Deploy target: this machine itself (no SSH step needed)
EOF
Use Cases in Practice
Deploying to your own server: SSH into the server, git pull, claude --dangerously-skip-permissions, prompt: "Run the deploy steps from CLAUDE.md, verify the service is running, and tail the logs." Claude does the full deploy, reads the logs, and reports status.
Processing large data files: The files are on the server. Start a tmux session, launch Claude, prompt: "Process all CSV files in ./data/, extract the summary stats, and write a report to ./reports/summary.md." Claude works through the files on the server at full speed.
Remote debugging production issues: SSH to the staging server, start Claude with access to the log files, prompt: "The service is returning 500 errors. Read the last 500 lines of /var/log/app/error.log and identify the root cause." Claude reads the actual logs without you copying anything.
Lesson 61 Drill
If you have a remote machine (even a cheap $5/month VPS works): install tmux, SSH in, install Claude Code, create a tmux session named dev, and complete one task with a Claude Code session that persists across an intentional disconnection — close your terminal mid-task, reconnect, and reattach. Confirm the task completed.
If you do not have a remote machine: run the exact same pattern on localhost using tmux locally. The muscle memory for tmux new-session, tmux attach, and the detach shortcut (Ctrl+B, D) is the same.
Bottom Line
Remote Claude Code means full tool access on any machine you can SSH into. tmux is the persistence layer that survives disconnections — always start one before starting work. --dangerously-skip-permissions enables non-interactive operation. Secrets go in environment variables injected at launch time, not stored on the remote machine. Update CLAUDE.md with remote-specific environment context. The pattern — SSH + tmux + claude — transfers to any Unix machine and unlocks use cases that only work when the agent is colocated with the data.