Claude Code on a VPS: Setup, tmux and Remote Control

Published on

Run Claude Code on a Linux VPS: requirements, the native installer, signing in over SSH, tmux, Remote Control from your phone, usage limits and security.

A phone lying on a grey sheet, showing code in a dark editor

Claude Code is a terminal program, so you can run it on a Linux VPS over SSH just as you would on your laptop. Put it on a server and the session stops depending on your laptop: you start a task over SSH, close the lid, and check on it later from your phone or another computer. This guide sets that up on a Linux VPS step by step, and covers the parts that catch people out: signing in without a browser, the usage limits, and what to lock down.

Quick answer: Claude Code needs at least 4 GB of RAM and supports Ubuntu 20.04+, Debian 10+ and Alpine Linux 3.19+. Install it with Anthropic's native installer, sign in by opening the login link on your own device and pasting the code back into the terminal, and start it inside tmux so it survives an SSH disconnect. On a Pro, Max, Team or Enterprise plan you can then follow and steer the session from claude.ai/code or the Claude app with Remote Control. The model still runs at Anthropic, and your plan's five-hour and weekly limits apply on a server just as they do on a laptop.

A word on who is writing: we sell VPS hosting, so we have a stake in this. The requirements, commands and limits below come from Anthropic's Claude Code documentation and the official tmux and Ubuntu docs, all opened on 28 October 2026 and linked where they are used.

Why Run Claude Code on a VPS

A claude session you start in a terminal is tied to that terminal and ends when it closes, as Anthropic's agent view docs put it. On a laptop, the work stops when the lid closes. On a VPS the process runs on a machine that stays on, so the session is still there when you come back.

That matters most for Remote Control, the feature that lets you follow and steer a session from your phone. The Remote Control docs describe the web and mobile apps as "a window into that local session, so your computer has to stay on and the claude process has to keep running." A laptop in a backpack can't do that. A server can.

There are two more reasons. Claude Code runs shell commands on the machine it sits on, and in its advice on untrusted content, Anthropic's security page recommends virtual machines "to run scripts and make tool calls, especially when interacting with external web services." A VPS is a virtual machine, and it keeps those commands away from the files on your own computer. You also don't need a GPU: the model runs at Anthropic, and the VPS only runs Claude Code, your code and your tools.

You may not need a server at all. Anthropic's cloud sessions, available on Pro, Max and Team plans and some Enterprise seats, keep running after you close your laptop. They count toward your plan's usage limits, with "no separate charge for the cloud VM." They clone and push through GitHub, and a session's VM is reclaimed after a period of inactivity. A VPS is the better fit when you want a machine of your own: a database or dev server running next to the agent, Docker, a git host other than GitHub, and files that stay where you left them.

What You Need

  • 4 GB of RAM or more and an x64 or ARM64 processor. That is the minimum in Anthropic's system requirements.
  • A supported Linux: Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+. Anthropic also publishes apt, dnf and apk repositories for Debian, Fedora, RHEL and Alpine. The list includes Windows Server 2019+, but on a VPS, Linux is the simpler route.
  • A Claude account that includes Claude Code: a Pro, Max, Team or Enterprise plan, or a Claude Console account with prepaid API credits. The free Claude plan does not include Claude Code.
  • An internet connection on the server, and you need to be in a country Anthropic supports.
  • tmux, to keep the session running when you disconnect.

On a Space-Node Premium VPS you choose the operating system at checkout, where Ubuntu 24.04 LTS is marked as recommended; Ubuntu 26.04 LTS, Ubuntu 22.04 LTS and Debian are on the list too. Standard checkouts have no OS step, so for a specific OS on a Standard plan, open a ticket after your order. Need Windows Server? Ask us before you order.

Step 1: Prepare the Server

Log in with the details from your client area. The native installer puts Claude Code in your home directory, and Anthropic's security page notes that a command you approve "can still write anywhere your user account can." So give Claude Code a normal account rather than root. Ubuntu's user management guide creates one with:

sudo adduser username

The same guide adds a user to a group with sudo adduser username groupname. Use sudo as the group name if the account should be able to run sudo.

Next, set up key login. On your own computer, Ubuntu's OpenSSH guide uses:

ssh-keygen -t ed25519
ssh-copy-id username@target_machine

Replace target_machine with your server's address. From then on, you log in with ssh username@target_machine (see the ssh manual). If this is your first Linux server, our Linux VPS beginners guide covers these first steps in more detail.

Last, install tmux. The tmux wiki gives apt install tmux for Debian and Ubuntu. Put sudo in front when you are not logged in as root.

Step 2: Install Claude Code

Logged in as your new user, run the native installer, the method Anthropic's setup page recommends:

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

It shows no progress while it downloads. When it's done, open a new terminal, for example by logging in again, and check the install:

claude --version

A version number means it worked. If the shell can't find claude, the install folder isn't on your PATH yet; on Linux the launcher sits at ~/.local/bin/claude. Native installs update themselves in the background. To check an install without starting a session, run claude doctor: the CLI reference says it prints the install health and whether your account can use Remote Control.

Step 3: Sign In Over SSH

Go to your project folder and start Claude Code, as the quickstart does:

cd /path/to/your/project
claude

On a laptop, Claude Code opens a browser for the login. A server has no browser, so open the login link in a browser on your own computer or phone instead. The authentication docs say to press c to copy the login URL when no browser opens. After you sign in, the browser may show a code instead of sending you back. Paste it into the terminal at the Paste code here if prompted prompt. The docs say this happens when the browser can't reach Claude Code's local callback server, "which is common in WSL2, SSH sessions, and containers." The terminal then shows Login successful. You can also sign in before your first session with claude auth login.

On a server, that login needs some care:

  1. It's a file. On Linux, Claude Code stores the login in ~/.claude/.credentials.json with file mode 0600. That file is your sign-in, so guard it like a password.
  2. It expires. Three days before, Claude Code warns Your login expires in 3 days · run /login to renew at startup, and /status tells you once it has expired. A Remote Control or background session that outlives its login stops making progress until you sign in again, so renew early on a box you leave running.
  3. An API key takes over. If ANTHROPIC_API_KEY is set in your environment, Claude Code uses it instead of your plan, "resulting in API usage charges," as Anthropic's Pro and Max help article warns. An interactive session asks once whether to use the key; a -p run uses it without asking. Remote Control won't run on an API key either. If you sign in with a plan, keep the key out of ~/.bashrc.

Step 4: Keep the Session Running with tmux

tmux keeps programs running after you disconnect, and it's what the Remote Control docs tell you to use: "If you run claude from a terminal on a remote machine, start it inside tmux or screen to keep the session running after you disconnect from SSH."

The commands below are the ones in the tmux Getting Started guide. Create a session called mysession:

tmux new -smysession

Start claude inside it and give it a task. To leave, press C-b d, which means Ctrl and b together, then d. tmux prints [detached (from session mysession)] and Claude Code carries on. Close the laptop if you like. When you're back, SSH in and reattach:

tmux attach -tmysession

tmux ls lists the sessions on the server. Always start tmux first and claude inside it. A session you start straight in your SSH shell ends when that shell closes.

Step 5: Steer It from Your Phone with Remote Control

Remote Control connects claude.ai/code and the Claude app for iOS and Android to the session on your VPS. Claude Code keeps running on the server with its files and tools; your phone is a window into it. You need a Pro, Max, Team or Enterprise plan, and "API keys are not supported." On Team and Enterprise, an Owner first has to switch Remote Control on in the Claude Code admin settings.

The Remote Control docs give three ways to start it:

  • claude remote-control runs server mode. It waits for connections, prints a session URL and shows a QR code for your phone when you press the spacebar. One server can host several sessions.
  • claude --remote-control "My Project" starts a normal interactive session that you can also reach from your other devices.
  • /remote-control, typed inside a session that is already running, hands that conversation over with its history.

Run it inside tmux, from your project folder. The first run in a folder asks whether you trust it, and trust is never saved for your home directory, so it would ask every time there. Then open the URL, or go to claude.ai/code or the Code section of the Claude app, where an online session shows a green dot.

Worth knowing before you rely on it:

  • No open ports. The session "makes outbound HTTPS requests only and never opens inbound ports," so your firewall needs no new rule.
  • The transcript is stored at Anthropic while Remote Control is connected, to keep your devices in sync. Commands and files stay on the VPS.
  • Network drops. An interactive session keeps retrying and reconnects when the network returns. Server mode gives up after roughly 10 minutes and exits. If claude remote-control stops, for example after a reboot, claude remote-control --continue in the same folder brings back the session it started with, for about four hours.

Would you rather use a chat app? Channels, a research preview, push Telegram or Discord messages into a running session, and Claude can answer through the same chat. The plugins need Bun, and messages only arrive while the session is open, so they suit a session kept open in tmux on a server. On Team and Enterprise, an admin has to enable channels first. Use the plugin's allowlist so only your own account can send messages: if the plugin relays permission prompts, anyone on that list can approve or deny tool use in your session.

Background Sessions Without tmux

Claude Code also has background sessions, a research preview you manage in agent view. Start one from your shell with a prompt. This is Anthropic's example:

claude --bg "investigate the flaky SettingsChangeDetector test"

A separate supervisor process runs these sessions, so you can close your shell and they keep working. Claude Code prints the session's short ID with the commands to manage it: claude agents lists your sessions, claude attach <id> opens one in your terminal, claude logs <id> shows recent output and claude stop <id> stops it. In a git repository, Claude moves each background session into its own git worktree under .claude/worktrees/ before it edits files, so parallel sessions don't write over each other.

Background sessions have limits too. Shutting down or restarting the server stops running sessions; reply to one or attach to it to restart it from its saved conversation. Each session uses your plan the same way an interactive one does, so "running ten agents in parallel uses quota roughly ten times as fast as running one." And every session is a separate process, so several of them need more memory. When memory runs low, the supervisor stops idle sessions.

Turn On the Sandbox, Including the Ubuntu 24.04 Step

Claude Code can run the shell commands it executes in a sandbox. By default, sandboxed commands can write only to your project folder, a temp directory and folders you add, and their network traffic goes through a proxy that checks each host against a list of allowed domains, which starts empty. The sandbox is off until you turn it on: type /sandbox in a session, and its panel shows anything that's missing. On Linux it relies on bubblewrap and socat, which the sandboxing docs install on Ubuntu and Debian with:

sudo apt-get install bubblewrap socat

Ubuntu 24.04 and later need one more step, because the default AppArmor policy stops bubblewrap from creating the user namespaces it needs. Check first:

sysctl kernel.apparmor_restrict_unprivileged_userns

If it prints 0, or an error that the key doesn't exist, skip this step. If it prints 1, add an AppArmor profile for bwrap. It applies only to bwrap itself, not to the commands it runs:

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

Reload AppArmor, then restart Claude Code, because it checks its dependencies at startup:

sudo systemctl reload apparmor

Know where the sandbox stops. It covers shell commands only; Claude's file tools, MCP servers and hooks run outside it. Sandboxed commands can still read most of the machine by default, including ~/.ssh, and they inherit Claude Code's environment variables, secrets included.

Usage Limits: What a VPS Changes and What It Doesn't

A VPS keeps the session alive. It doesn't give you more Claude. The limits belong to your account, wherever Claude Code runs:

  • Pro and Max plans have "a five-hour session limit and a weekly limit," shared between Claude and Claude Code, and Max adds a separate weekly limit for Claude Fable models, says Anthropic's help article. Team and Enterprise seats draw from an allowance that resets on a rolling five-hour window and a weekly window, according to the costs page.
  • The legal and compliance page adds that the advertised Pro and Max limits "assume ordinary, individual usage of Claude Code and the Agent SDK."

At the limit, Claude Code shows a message such as You've hit your session limit · resets 3:45pm and, in the words of the error reference, "blocks further requests until the reset time shown in the message." Switching models doesn't get you around the session and weekly limits, because they cover every model.

This is where a server helps a little. In an interactive session signed in with a Claude plan (version 2.1.234 or later), Claude Code waits and then continues the task by itself after the reset, as the interactive mode docs describe. That only works while the session stays open, and a session in tmux on a VPS does. It still stops at permission prompts, and it re-arms the wait at most twice in a row before it gives up. It doesn't start the wait by itself in a Remote Control session, where you start it yourself from /rate-limit-options, or when the reset is more than 24 hours away, as a weekly limit can be. Background sessions and -p runs don't offer the wait at all.

When you do hit a limit, Anthropic lists these options: wait for the reset (/usage shows when that is), buy extra usage with /usage-credits, move to a bigger plan, or switch to a Console account with API credits.

Unattended Jobs: Use an API Key

For a job that runs from a script or cron with nobody watching, use an API key from the Claude Console. Anthropic's Consumer Terms, which cover Free, Pro and Max, rule out access "through automated or non-human means, whether through a bot, script, or otherwise," except through an API key or where Anthropic explicitly permits it. API usage is billed on its own, too, so a nightly job doesn't eat the five-hour window you want for your own sessions.

Claude Code's headless mode is built for this. Anthropic's example for scripts uses bare mode, which skips hooks, plugins, MCP servers and CLAUDE.md, and never reads your plan login:

claude --bare -p "Summarize README.md" --allowedTools "Read"

Set ANTHROPIC_API_KEY in the job's own environment, not in your shell profile, for the reasons in step 3. Bare mode matters for another reason: without it, a -p run loads a project's hooks and MCP servers even in a folder you never trusted. And from version 2.1.302, a -p run starts in Manual mode when nothing else sets a permission mode, and in Manual mode a tool call that needs approval is denied unless something approves it. --allowedTools is how you pre-approve the tools a job needs.

To cap spend, add --max-budget-usd. The CLI reference says it stops a print-mode run once its estimated spend on API calls reaches the amount:

claude -p --max-budget-usd 5.00 "query"

The cap works from Claude Code's own estimate and spend can go past it, so leave some headroom. Anthropic also offers claude setup-token, a one-year token tied to a Pro, Max, Team or Enterprise plan, for CI and scripts. It can't start Remote Control, and bare mode doesn't read it.

Security Basics for a Claude Code Server

Claude Code runs commands with your user's rights, so treat the VPS as something worth protecting.

  • A normal user, not root. Anthropic's permission modes page keeps bypassPermissions, the mode that skips permission prompts and safety checks, for "Isolated containers and VMs only," and asks for a non-root user when you run fully unattended; on Linux, Claude Code won't start that mode as root. The same page warns that it "offers no protection against prompt injection or unintended actions" and points to auto mode for fewer prompts. Leave it off on a server that holds anything you can't afford to lose, such as a production database or keys to other systems.
  • SSH keys, no passwords. Once key login works, turn password login off with PasswordAuthentication no in a file in /etc/ssh/sshd_config.d/. Ubuntu's OpenSSH guide explains why: its sshd_config includes those files at the very top, and because OpenSSH uses the first value set, they override the main file. The sshd_config manual adds that included files are read in lexical order, so check that no file read earlier sets it to yes. sudo sshd -T prints the settings sshd will actually use (sshd manual). Then check the config with sudo sshd -t and run sudo systemctl restart ssh.service, as Ubuntu's guide does, because a broken config can lock you out.
  • One open port. Remote Control needs no inbound port, so for Claude Code itself only SSH has to be reachable. Ubuntu's firewall guide uses sudo ufw allow 22 and sudo ufw enable. Run them in that order: allow SSH first, then switch the firewall on. Our UFW and Fail2Ban guide goes further.
  • Updates. Ubuntu installs security updates automatically through unattended-upgrades, which is installed by default, according to its automatic updates page. Native Claude Code installs update themselves.
  • Fewer secrets on the box. Your login file and API keys work like passwords, and the sandbox can read most of the disk by default. Keep keys this server doesn't need somewhere else, and only add MCP servers and plugins you trust.
  • Your own backups. Backups are not included on our VPS plans, so commit and push often.

Which Space-Node Plan Fits

Claude Code's 4 GB minimum sets the starting point. Our smallest VPS, VPS-XS Premium with 2 GB, sits below it. That plan suits a lighter agent, such as one OpenClaw gateway on API models, not Claude Code.

  • One Claude Code session in tmux: VPS-S with 4 GB. Standard costs €5.50 a month with 3 shared vCores on an AMD EPYC 7452, 4 GB of DDR4, 40 GB of NVMe storage and 10 TB of transfer a month. Premium costs €8.40 a month with 2 shared vCores on the AMD Ryzen 9 9950X and DDR5.
  • Several sessions, background agents, or Docker and a database next to the agent: VPS-M with 8 GB. Standard costs €11.10 a month with 4 shared vCores and 60 GB of NVMe storage. Premium costs €16.80 a month with 3 shared vCores on the Ryzen 9 9950X.
  • Agents that compile, run test suites and build Docker images: VPS-M Premium. Premium is our tier for heavier work.

Every plan comes with KVM and full root access, dedicated RAM with shared vCores, DDoS protection and an EU data center. Prices include VAT, billing is monthly, and longer billing periods cost less per month. Our VPS page for AI agents and coding tools lists the plans for this kind of work with their order links. Questions about the VPS itself? Our team answers by live chat, Discord and email every day from 08:00 to 20:00 UTC.

FAQ

How much RAM does Claude Code need on a VPS? Anthropic lists 4 GB or more as the minimum, on an x64 or ARM64 processor. On our plans that means VPS-S with 4 GB for one session. Take VPS-M with 8 GB if you run several sessions or background agents, or Docker next to Claude Code.

Can I use Claude Code on a VPS with the free Claude plan? No. Claude Code needs a Pro, Max, Team or Enterprise plan, or a Claude Console account with API credits. The free Claude plan does not include Claude Code.

Does Claude Code keep running when I close my laptop? Yes, if it runs on the VPS inside tmux or as a background session. It stops making progress when your plan's usage limit is reached or its login expires, and it stops when the server restarts. A plain interactive session in tmux can continue by itself once a usage limit resets within 24 hours; background and Remote Control sessions wait for you.

Does running Claude Code on a VPS give me more usage? No. Your plan's five-hour and weekly limits, or your API key's billing, apply wherever Claude Code runs. A VPS only keeps the session open, which lets an interactive session in tmux continue by itself after a reset.

Can I use Remote Control with an API key? No. Remote Control works with Pro, Max, Team and Enterprise plans, and Anthropic's docs say API keys are not supported. If ANTHROPIC_API_KEY is set in your environment, Remote Control won't start until you remove it.

Will Anthropic ban me for running Claude Code on a VPS? Anthropic's own docs describe running Claude Code on a remote machine inside tmux, so the server itself is not the problem. The rules are about your account: don't share your login or make your account available to others, Pro and Max limits assume ordinary, individual usage, and scripts and bots should use an API key. Anthropic says it may enforce its rules on credential use without prior notice.

Do I need a GPU for Claude Code? No. The model runs at Anthropic. The VPS runs Claude Code, your code and the commands it starts, so RAM and CPU are what matter.

Which operating system should I choose? Ubuntu 24.04 LTS is the image our Premium checkout marks as recommended, and Claude Code supports Ubuntu 20.04 or newer and Debian 10 or newer. On Ubuntu 24.04 and later, the sandbox may need the AppArmor profile from the sandbox section above; the check there tells you. If you need Windows Server, ask us before you order.

Can I talk to Claude Code on my VPS through Telegram or Discord? Yes, with Channels, a research preview. You install the Telegram or Discord plugin, which needs Bun, and start Claude Code with the channels flag. Messages only arrive while the session is open, so keep it running in tmux, and lock the bot to your own account with the allowlist.

Sources

All opened on 28 October 2026:

Claude and Claude Code are made by Anthropic. Space-Node is not affiliated with or endorsed by Anthropic or by the makers of the other tools named in this guide.