Claude Code on a VPS: setup, login and tmux, step by step

To run Claude Code on a VPS, rent a Linux server with at least 4 GB of RAM and install Claude Code with the official script. Sign in with /login, pasting the code back, or with a one-year token from claude setup-token. Then run it inside tmux, so the session survives disconnects and keeps working with your laptop closed.

Why run Claude Code on a VPS?

A VPS is a computer that stays on. Claude Code running there keeps going when your laptop sleeps, and you can reach it from anywhere: over SSH, or from your phone with Remote Control.

It also gives you what Anthropic's cloud sessions hold back. You choose the tools, the compute and the network, so Claude Code can reach a private database, a staging server or a repo on any git host. Cloud sessions start from a fresh GitHub clone with an allowlisted network, and their machines pause when idle.

The price is that you run the server. That trade-off is the rest of this guide. For a comparison with every other way to run Claude Code off your laptop, see the best way to work with Claude Code in the cloud.

What size VPS does Claude Code need?

Anthropic's system requirements are 4 GB of RAM or more, an x64 or ARM64 processor, and on Linux, Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+.

Claude Code itself is light. What sizes the server is the work it does: builds, test suites, a headless browser, and how many sessions run at once. Two reference points:

Machine	CPU	Memory
Anthropic's cloud session VM	4 vCPUs	16 GB
A Kavela agent's computer	2 vCPUs	8 GiB

Start near the minimum for one session of light work, and size up when builds or parallel sessions start to queue.

How do I install Claude Code on a VPS?

1. Create a user for the work. Running everything as root means a mistaken command can touch the whole machine.

   adduser dev
   usermod -aG sudo dev
   

2. Lock down SSH. Use SSH keys, turn off password login, and either allow only SSH through the firewall (ufw allow OpenSSH && ufw enable) or reach the server over a private network such as Tailscale.

3. Install the basics, plus your project's own toolchain:

   sudo apt update && sudo apt install -y git tmux
   

4. Install Claude Code with the official script. The docs also list apt, dnf and apk packages.

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

5. Clone your repo and sign in to the other tools Claude Code will use, such as gh auth login for GitHub.

How do I log in to Claude Code on a headless server?

A server has no browser, which is where most setups stall. One open issue calls it "impossible to authenticate on headless environments (VMs, SSH sessions, containers, cloud instances) when using a Pro/Max subscription". There are three ways in:

Method	How	Use it for
/login with a pasted code	Run claude, then /login. Press c to copy the URL, open it on your laptop and sign in. The browser shows a code, which you paste at the Paste code here if prompted prompt	Interactive sessions on the server
claude setup-token	Prints a one-year token after you approve in a browser. Set it as CLAUDE_CODE_OAUTH_TOKEN on the server	Scripts and cron jobs on your plan
An API key	Set ANTHROPIC_API_KEY	Pay-per-token billing, and --bare runs

Two details catch people out. setup-token doesn't save the token anywhere, so copy it when it prints. And claude -p --bare, the recommended mode for scripts, doesn't read CLAUDE_CODE_OAUTH_TOKEN at all, so a bare run needs an API key.

Can I use my Claude Pro or Max plan on a VPS?

Yes. /login and setup-token both sign the server in to your own plan, and its use counts against your plan's limits the same way your laptop's does.

It is a documented setup. Anthropic's authentication docs offer claude setup-token for "CI pipelines, scripts, or other environments where interactive browser login isn't available."

Treat the token like a password: it acts as you. Keep it out of repos and prompts, and give it only to machines you control.

How do I keep Claude Code running after I disconnect from SSH?

Start each session inside tmux. Closing the SSH connection then detaches from the session without ending it.

tmux new -s api-refactor
claude
# press Ctrl-b then d to detach

tmux ls                      # list sessions later
tmux attach -t api-refactor  # pick one up again

To drive the session from your phone, run claude remote-control inside tmux and open it from the Code tab of the Claude app. Setup and troubleshooting are in how to use Claude Code from your phone.

tmux works, and it is also the part people get tired of. A Hacker News thread titled "Tmux and Claude Code: Sessions, Send-Keys, and the Ceiling" reached 170 points in October 2026.

How do I run Claude Code jobs on a VPS without a terminal open?

Use headless mode, claude -p, with the token in the environment and a clear permission baseline:

export CLAUDE_CODE_OAUTH_TOKEN="..."   # from claude setup-token
cd ~/app
claude -p "Run the test suite, fix what fails, and write a summary to reports/tests.md" \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npm test *),Bash(git diff *),Bash(git status *)"

From Claude Code v2.1.302, a claude -p run starts in Manual mode, where any call that would need your approval is denied. Unless you allow a command in advance, the job quietly skips that step and still finishes. The options:

• acceptEdits: file writes and common file commands run, other commands need an --allowedTools entry.
• dontAsk: every call that would prompt is denied. Good for locked-down jobs.
• auto: a classifier reviews most actions instead of you.

Schedule the command from cron to run it daily. Cron recipes and the pitfalls of scheduled runs are in the Claude calendar guide, and keeping a job going around the clock is covered in how to run Claude Code 24/7.

How do I secure a VPS that runs Claude Code?

• A separate user, SSH keys only, and a firewall or private network, as in the setup steps.
• Limit what Claude can run. Put allow and deny rules in the repo's .claude/settings.json, so unattended runs can't reach beyond the commands you expect.
• Limit where it can connect. Anthropic's reference dev container includes an init-firewall.sh script that restricts outbound traffic to the destinations it allows. Running Claude Code in that container on the VPS gives you the same fence.
• Keep secrets out of prompts. Anything you type into a session lands in its transcript. Load keys from the environment or a secrets manager.

What does a VPS still leave to you?

• The server. Updates, disk space, backups and the bill.
• Logins. The setup token lasts a year, and every other login on the machine expires on its own schedule. An open issue titled "Claude code requires users to constantly login" has 86 comments.
• Approvals. A question in a tmux session waits until you attach, and a headless run denies it outright.
• Usage limits. When your plan reaches its limit, the run stops mid-task. An open request to continue after the reset has 215 reactions.
• Checking the result. A job that exits cleanly can still have skipped the work. Nothing on the server reads the output for you.

How does Kavela compare to running your own VPS?

Kavela is the always-on machine without the server work. Each agent gets its own cloud computer (2 vCPU, 8 GiB) with a shell, files, git and a real browser, and Claude Code runs there on your own Claude plan.

You sign in once for the whole workspace, from a card. The login is stored encrypted (AES-256-GCM), and Kavela's servers pass it on without decrypting it: only the agent's computer decrypts it, at the start of a run. Connect more than one account and runs rotate across them. Connections to your other tools are also made once for the workspace, and every agent can use them. Browser sign-ins are kept between runs, and you can take over the browser at any time.

Work starts from a message to Kav, the lead agent, from a schedule or from an event. Questions land in one Approvals inbox you can answer from your phone. Every workflow run is checked by a second agent against your checklist, and when your plan reaches its limit the task waits and picks up after the reset.

Kavela starts with a 14-day free trial, no card. Start your free trial