Run Claude Code on a VPS: SSH, tmux and Headless Login

Claude Code runs on Ubuntu 20.04+ or Debian 10+ with 4 GB of RAM. How to SSH into a VPS, log in without a browser, and keep sessions alive in tmux.

If you want Claude Code to keep working after you close your laptop, or you want it in an isolated machine instead of your own, install it on a VPS and connect over SSH. This guide is for a development box you use interactively: choosing a server, SSH keys and a non-root user, installation, logging in without a browser, tmux, connecting from your local editor, secrets and permissions, and what a server costs while you’re not using it. For running a bot around the clock with systemd, see running an AI agent on a VPS 24/7.

We did not rent a server for this article. On 2026-10-29 we ran tmux and ssh-keygen in our test environment (macOS: tmux 3.8, OpenSSH 10.3p1, Claude Code 2.1.312), inside a scratch directory under /tmp, and show that output below. Every server-side command is from the docs or general Linux practice (not run).

Choosing a server

The docs list these requirements for Claude Code: Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+ on Linux, 4 GB+ RAM, an x64 or ARM64 processor, and an internet connection. Alpine needs bash, curl, libgcc, libstdc++ and ripgrep installed first, so a mainstream Ubuntu or Debian image is the simpler start.

Source: https://code.claude.com/docs/en/setup (checked 2026-10-29)

For interactive use, the smallest plan that meets those numbers is enough to start. Pick a region close to you, since every keystroke in an SSH session makes a round trip. Hourly billing suits short trials, but read your provider’s billing docs before you rely on it: some providers keep charging for a server that is only stopped (see the last section). For a longer look at what matters in a server for AI coding, see choosing a VPS for AI coding.

SSH keys and a non-root user

Create the key on your local machine. This is what we got:

$ ssh-keygen -t ed25519 -f ./vps_ed25519 -N "" -C dev@example
Generating public/private ed25519 key pair.
Your identification has been saved in ./vps_ed25519
Your public key has been saved in ./vps_ed25519.pub

The private key was created as -rw------- (600). For a real key, drop -N "" and set a passphrase.

On the server, don’t work as root. Create a working user. These are generic Ubuntu commands (not run):

# As root on the VPS (not run)
adduser dev
mkdir -p /home/dev/.ssh
cp ~/.ssh/authorized_keys /home/dev/.ssh/
chown -R dev:dev /home/dev/.ssh && chmod 700 /home/dev/.ssh

If you leave this user out of the sudo group, the commands Claude Code runs stay inside that user’s permissions.

Installing Claude Code

The docs give the native installer for Linux:

curl -fsSL https://claude.ai/install.sh | bash

You can also install the npm package, which needs Node.js 22 or later. The docs say not to use sudo npm install -g:

npm install -g @anthropic-ai/claude-code

apt, dnf and apk packages are also listed for Debian, Fedora, RHEL and Alpine. Check the install with claude --version. claude doctor prints read-only install and settings diagnostics without starting a session. For a first-time setup, see getting started with Claude Code.

Source: https://code.claude.com/docs/en/setup (checked 2026-10-29)

Logging in on a server without a browser

The first time you run claude, it tries to open a browser to log in. If no browser opens, press c to copy the login URL to your clipboard and open it in your local browser. Whether that copy reaches your local clipboard over SSH depends on your terminal (unverified); if it doesn’t, copy the URL from the screen. After you sign in, if the browser shows a login code instead of redirecting, paste it at the Paste code here if prompted prompt. The terminal then shows Login successful.

On Linux, the login is stored in ~/.claude/.credentials.json with file mode 0600.

For environments where browser login isn’t available, such as CI pipelines and scripts, claude setup-token generates a one-year OAuth token. It runs the same browser authorization, prints the token, and saves it nowhere; you set it as CLAUDE_CODE_OAUTH_TOKEN. Setting ANTHROPIC_API_KEY with a Console key is another option, and Claude Code asks once whether to use it. For an interactive VPS, the normal login is enough. We did not try any of this on a server (not run).

Source: https://code.claude.com/docs/en/authentication (checked 2026-10-29)

Keeping sessions with tmux

Run Claude Code inside tmux so the session survives a dropped SSH connection. We created, listed and removed a session in our test environment, on a separate socket (-L) so it couldn’t touch any existing tmux server:

$ tmux new -s dev -d
exit=0
$ tmux ls
dev: 1 windows (created Thu Oct 29 14:09:45 2026)
$ tmux kill-session -t dev
exit=0

A session created with -d stays alive after the command that created it returns. We sent an echo into it and confirmed with tmux capture-pane that the output was still there. On a VPS the flow looks like this:

ssh -i ~/.ssh/vps_ed25519 dev@<server-ip>
tmux new -s dev        # first time
cd ~/projects/todo-app && claude
# press Ctrl-b, then d, to detach
tmux attach -t dev     # next time you connect

tmux list-keys showed bind-key -T prefix d detach-client, which is the Ctrl-b then d detach.

Connecting from your local editor

An editor that connects over SSH, such as VS Code’s Remote - SSH, lets you open the server’s files locally. Start Claude Code with claude in the editor’s integrated terminal. We did not try an editor connection for this article (unverified).

Secrets and permissions

• Don’t put .env files or production keys in the server’s working directory
• Add permissions deny rules so Claude can’t read any secret files that remain
• Keep work inside one directory, such as ~/projects/todo-app, and start claude there

Without asking, Claude can read files only in its working directory and any additional directories. A deny rule like Read(./.env) is not a wall. It covers Claude’s file tools and Bash commands that name the file, such as cat, but not a command like grep -r that reads files without naming them, or a script that opens files itself. For OS-level blocking, the docs point to the sandbox.

Source: https://code.claude.com/docs/en/permissions (checked 2026-10-29)

For rule syntax, see the permissions settings guide.

What it costs when you’re not using it

Billing rules differ by provider, and the difference that bites is between stopping and deleting a server. On some providers a stopped server keeps its disk, IP address or reserved resources and is still billed; on others, stopping reduces the charge. Before you count on hourly billing, find the answer in your provider’s billing docs.

If deleting is the only way to stop the charges, remember that the server’s files are gone afterwards. Exit Claude Code inside tmux and push your changes to the remote repository first.

Summary

• Requirements: Ubuntu 20.04+, Debian 10+ or Alpine 3.19+, 4 GB+ RAM, x64 or ARM64.
• Install with the native installer or npm (Node.js 22+, no sudo).
• Without a browser, press c for the login URL, open it locally, and paste the code back.
• tmux new -s dev to start, Ctrl-b d to detach, tmux attach -t dev to return.
• Keep .env off the server, add deny rules, and start claude in one working directory. Deny rules don’t stop every read.
• Check your provider’s billing docs: a stopped server may still be billed.