VPS Tutorials
Deploying Claude Code on a VPS (2026): Remote Dev Environment Setup, Authentication, Permission Isolation and Persistent tmux
Deploy Claude Code on an Ubuntu or Debian VPS: server sizing, official installation, headless login, ANTHROPIC_API_KEY authentication, isolation between a regular user and project permissions, persistent tmux sessions and recovery after SSH disconnects, plus troubleshooting commands for command not found, 403, authentication failures and OOM, and a production security checklist.

Deploying Claude Code on a VPS (2026): Remote Dev Environment Setup, Authentication, Permission Isolation and Persistent tmux
Running Claude Code on a VPS suits remote development, server troubleshooting and automation scripts that need to stay online long term. After logging in over SSH, you run claude directly inside the Git repository, so code, dependencies and the build environment all stay on the server while your local machine only handles the terminal connection.
This article uses Ubuntu 22.04/24.04 and Debian 12 as examples to build a reusable setup: a regular user, the official installation, headless authentication, project permission restrictions and tmux session recovery. Claude Code's official system requirements are 4GB or more of memory, an x64 or ARM64 processor, and a network environment that can reach Anthropic services.
| Use case | Recommended configuration | Notes |
|---|---|---|
| Reading code, editing small scripts | 2 cores / 4GB / 40GB SSD | Meets the official minimum memory requirement, suitable for a single repository |
| Building Node.js and Python projects | 4 cores / 8GB / 80GB NVMe | Leaves headroom for dependency installation, tests and compilation |
| Multiple repositories, Docker and databases in parallel | 4-8 cores / 16GB / 120GB NVMe | Prevents build tasks from competing for memory and IO |
Even if a 1GB or 2GB VPS can start the installer, it easily runs out of memory (OOM) during npm install, TypeScript compilation or Docker builds. On a limited budget, start with 4GB and reserve at least 10GB of disk space for the system.
First log in over SSH and update the system:
ssh root@YOUR_SERVER_IP
apt update && apt full-upgrade -y
apt install -y ca-certificates curl git tmux ripgrep sudo
Do not let AI tools run as root long term. Create a dedicated account and working directory:
adduser coder
usermod -aG sudo coder
mkdir -p /srv/workspaces
chown -R coder:coder /srv/workspaces
su - coder
Then confirm that networking and time are correct:
curl -I https://code.claude.com
timedatectl status
If SSH itself returns Permission denied, first check keys, users and directory permissions using the VPS SSH Permission denied troubleshooting checklist, then continue with the installation.
Run the official Linux installation command as the coder user:
curl -fsSL https://claude.ai/install.sh | bash
Reload the shell configuration and check the version:
export PATH="$HOME/.local/bin:$PATH"
claude --version
claude doctor
The official native installation updates automatically. If the server needs a pinned version or a stable channel, you can install stable:
curl -fsSL https://claude.ai/install.sh | bash -s stable
Do not save the curl download into the project repository, and do not use sudo to install Claude Code into root's home directory. If you see claude: command not found, first check echo $PATH and ls -l ~/.local/bin/claude.
Start Claude Code in the project directory:
mkdir -p /srv/workspaces/demo
cd /srv/workspaces/demo
claude
On first run it displays an authorization URL. Copy it into a local browser to complete login with a Claude Pro, Max, Team, Enterprise or Console account, then return to the SSH session. A headless VPS does not need a browser installed; the key is to keep the terminal connection alive until authorization completes.
Automation tasks can use ANTHROPIC_API_KEY. Do not write the key directly into command history or Git:
read -s ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
claude
unset ANTHROPIC_API_KEY
For use by fixed scripts, create a credentials file readable only by the current user:
install -m 600 /dev/null ~/.config/claude.env
printf 'ANTHROPIC_API_KEY=replace-me\n' > ~/.config/claude.env
set -a
. ~/.config/claude.env
set +a
Add ~/.config/claude.env to your backup exclusion list and to the project's .gitignore. When rotating the key, overwrite the file and run chmod 600 ~/.config/claude.env.
Place the repository where coder can write and other services cannot:
cd /srv/workspaces
git clone YOUR_REPOSITORY_URL demo
sudo chown -R coder:coder demo
cd demo
You can create .claude/settings.json inside the project to require confirmation for high-risk commands and to deny reading the secrets directory:
{
"permissions": {
"allow": [
"Read(./**)",
"Edit(./**)",
"Bash(git status)",
"Bash(git diff)",
"Bash(npm test)"
],
"ask": [
"Bash(git push*)",
"Bash(docker *)",
"Bash(rm *)"
],
"deny": [
"Read(~/.ssh/**)",
"Read(~/.config/claude.env)",
"Bash(curl * | bash*)"
]
}
}
Rules should be adjusted to the project's actual commands. Do not enable a fully automatic high-privilege mode just to skip confirmation steps; on a production VPS, at minimum keep manual confirmation for Git commits, deletions, Docker and network downloads.
Interactive development is best kept in tmux:
tmux new -s claude-demo
cd /srv/workspaces/demo
claude
Press Ctrl+b, then d to detach from the session; after reconnecting to the VPS, restore it:
tmux ls
tmux attach -t claude-demo
To continue the previous conversation, run claude --continue in the repository directory, or use claude --resume to select a session. tmux only keeps the terminal process from disconnecting; it does not handle automatic recovery after a VPS reboot for you, and it is not suitable for approving high-risk changes unattended.
Check the server's DNS, system time and outbound firewall:
curl -v https://claude.ai/install.sh
getent hosts claude.ai
If a corporate proxy replaces certificates, import the CA according to the official network configuration documentation; do not use curl -k to bypass TLS verification.
command -v claude
ls -l ~/.local/bin/claude
echo $PATH
Add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc and log in again. Confirm that installation and execution use the same Linux user.
Check the current user and environment variables:
whoami
env | grep '^ANTHROPIC_API_KEY=' | cut -c1-12
claude doctor
root and coder have different configuration directories, so you cannot log in as root and then switch users to run it.
free -h
dmesg -T | grep -i -E 'oom|killed process'
First stop unrelated services and reduce the number of parallel builds; if it still OOMs, upgrade to 8GB of memory. Swap only relieves peaks; it cannot replace actual memory.
- Claude Code runs as a regular user, and the working directory does not contain SSH private keys, database backups or production secrets.
- The API Key file has permissions
600, has not been committed to Git, and has not been written into shell history. - SSH allows key-based login only, the firewall opens only necessary ports, and management ports are not fully open to the public internet.
- The project's
.claude/settings.jsonkeeps confirmation forgit push,rm, Docker and external downloads. - Before each major change, create a Git branch or commit point, and check
git diffand test results afterward. - Monitor disk, memory and outbound traffic; Docker projects should also set healthchecks and resource limits, as described in the VPS Docker Compose production configuration checklist.
If you already use a Codex CLI remote development environment on a VPS, the deployment approach for Claude Code is basically the same: a regular user, clear authentication boundaries and tmux sessions are the core of stability; the differences are mainly the account system, the API Key name and the permission configuration file format.
A Linux VPS starting at 4GB can host Claude Code's remote development workflow. Start with the official installer and a regular user to complete the minimal setup, then add permission rules, tmux sessions and monitoring as the project requires. Isolating authentication information from production directories matters far more than simply chasing a larger CPU.