How to Run Claude Code on a VPS: Remote AI Coding Agents, Explained (The Beginner's Guide)

CodexFuse Team · 2026-11-03T14:38:42.231Z · 15 min read min read

How to Run Claude Code on a VPS: Remote AI Coding Agents, Explained (The Beginner's Guide)

Learning how to run Claude Code on a VPS is the moment your AI coding agent stops being a laptop program and becomes a server program: a session that keeps working after you close the lid, from any device, anywhere. The persistence lesson is simple — your laptop sleeps, but a VPS never does — and it changes everything about long coding-agent runs. This beginner guide covers the full arc: pick a VPS (see what is VPS hosting if the term is new), generate your key pair with a free SSH key generator, install Claude Code on Ubuntu, keep the session alive with tmux, drive it from your phone with Remote Control, and understand the Codex alternative plus the three connectivity models. The short version: SSH in with keys, run curl -fsSL https://claude.ai/install.sh | bash (the official installer as of November 3, 2026), start the agent inside tmux, and your coding agent now outlives every coffee-shop Wi-Fi drop.

What Does "Running Claude Code on a VPS" Actually Mean?

Running Claude Code on a VPS means installing Anthropic's Claude Code CLI on a remote Linux server instead of your own computer, so the agent's process lives in a datacenter with an always-on internet connection while you control it from your laptop, tablet, or phone. A Claude Code VPS setup is the simplest form of a remote coding agent: the code lives on the server, the agent runs on the server, and your device is just a remote control — exactly the "run AI agents on a VPS" setup developers adopt when agent sessions grow longer than a laptop battery or a commute. Nothing about Claude Code itself changes: same claude command, same tools, same subscription. Only the machine changes, and that one change solves persistence, availability, and "my laptop fan sounds like a jet engine" in one move.

How Do You Run Claude Code on a VPS?

The complete path, end to end, is seven steps. This is the snippet to memorize:

1. Get a small cloud server. A 2 vCPU / 4 GB RAM Ubuntu 24.04 VPS is a sensible floor — Claude Code's own minimum is 4 GB of RAM (official docs, November 2026).
2. Make an SSH key pair and kill password logins. Generate with ssh-keygen -t ed25519, copy it with ssh-copy-id user@server, then set PasswordAuthentication no on the server.
3. Install Claude Code on the server. Run the official installer curl -fsSL https://claude.ai/install.sh | bash and confirm with claude --version.
4. Log in with an eligible plan. Claude Code needs a Pro, Max, Ultra, Team, Enterprise, or Console account — the free claude.ai plan does not include access (official docs).
5. Start the agent inside tmux. A terminal multiplexer keeps the session running after you disconnect; without it, closing SSH kills your agent.
6. Enable Remote Control for phone access. claude --remote-control bridges the server session into the Claude mobile app or claude.ai/code — no inbound ports, outbound HTTPS only.
7. Lock down the server. Firewall to SSH only, automatic updates, and never expose agent transports to the public internet.

The rest of this guide explains each step so you understand why it works, then compares your options: the three connectivity models, the Codex path, and when a managed box beats your own VPS.

What You Need Before You Start

Before anything else, check the four prerequisites — skipping one is the cause of most failed first attempts:

You do not need a powerful machine. Agent inference happens on Anthropic's servers, not yours — the VPS is running a terminal client, so a modest box handles it. If you are price-shopping the server itself, read our cheap VPS hosting comparison before you buy.

Step 1: Pick and Prepare Your VPS

Any mainstream cloud provider works — the self-hosting guides surveyed this run name DigitalOcean, Linode, and AWS Lightsail as the usual suspects, and the argument for self-hosting is the same everywhere: full data ownership, predictable costs, and no vendor lock-in (Geeky Gadgets' VPS guide, December 2025). Create the server with Ubuntu 24.04, note the IP address, and pick a region close to you for lower SSH latency. A 2 vCPU / 4 GB / 40 GB disk instance is the sweet spot for a first agent box: room for the agent, a dev server, and a database without paying for cores you will not use.

One detail beginners miss: confirm you can reach the server over SSH on port 22 from your network before installing anything. If SSH times out on a fresh box, the problem is the provider's firewall panel, not your key — open port 22 there first.

Step 2: Connect with SSH Keys, Never Passwords

SSH keys are the only sane way into a server, and the official guidance has been stable for years: the ed25519 key type is the 2026 default. Run these from your laptop, not the server:

ssh-keygen -t ed25519 — creates ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub. Accept the default location and set a passphrase.
ssh-copy-id username@server_ip — appends your public key to the server's ~/.ssh/authorized_keys; it asks for the password exactly once.
ssh username@server_ip — should now log you in without a password.

Then, on the server, harden the door: edit /etc/ssh/sshd_config, set PasswordAuthentication no, and restart sshd. From this moment the server rejects password login attempts entirely — a brute-force bot can guess forever and get nowhere. (Key commands verified against reintech.io and learnubuntu.com guides, fetched November 3, 2026.) If generating keys locally feels fiddly, the free SSH key generator linked in the introduction produces a ready pair in your browser — the rest of this guide works identically either way.

Step 3: Install Claude Code on the Server

Claude Code on a server installs exactly like on your laptop — it is a terminal CLI, so the server is a first-class citizen. On the server, run:

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

This is Anthropic's official Native Install path (also available via Homebrew, WinGet, apt/dnf/apk, and npm; PowerShell users run irm https://claude.ai/install.ps1 | iex). The installer drops a launcher at ~/.local/bin/claude and native installs auto-update in the background. Verify with claude --version and run claude doctor if anything looks off. (Install paths confirmed against the official setup docs, fetched November 3, 2026. As the writer caution in this guide's research brief warned: version numbers move fast — claude --version on your machine is the only number that matters; sightings this run reached 2.1.310 in late October 2026.)

Then run claude and complete /login with your eligible plan. If you are completely new to the tool itself — first session, first prompt, how the permissions work — our Claude Code beginner guide walks through it before you add the VPS layer.

Step 4: Keep the Agent Running After You Disconnect

Here is the trap that eats every beginner's first server session: when your SSH connection closes, the shell closes, and Claude Code dies with it. The fix is a terminal multiplexer — tmux is the standard choice, and the remote-agents guide that informed this run (dev.to, October 29, 2026) calls the SSH-plus-tmux combo "the bedrock" of remote agents for exactly this reason.

The attach/detach arc is three commands:

1. Connect and start a named session: ssh -t devbox tmux new -A -s agent (use your server's address instead of devbox).
2. Inside it, run claude and start your task. Detach with Ctrl-b then d — the session keeps running on the server.
3. Reattach anytime, from any device: ssh -t devbox tmux attach -t agent — your agent is exactly where you left it.

That is persistence: laptop lid closed, phone in pocket, commute across town — the agent on the VPS never noticed. A systemd service is the alternative for a truly headless setup (one hoster guide this run documented a systemd unit that survives reboots), but tmux is the beginner's answer because you can see the session.

Step 5: Drive It from Your Phone with Remote Control

Remote Control is Claude Code's vendor-managed bridge between a running session and your phone or browser — claude.ai/code or the Claude app's Code tab becomes a window into the server session. Three ways to turn it on (official docs, November 2026):

claude remote-control — server mode: one process hosts multiple parallel sessions; press spacebar for a QR code.
claude --remote-control (or --rc) — your interactive session becomes reachable remotely.
/remote-control (or /rc) inside a running session — the terminal shows /rc active while connected.

Two hard requirements to know before you rely on it: your account must be Pro, Max, Ultra, Team, or Enterprise (API keys are not supported, and Team/Enterprise owners must enable the toggle), and you must be logged in via claude.ai. The connection mechanics are beginner-friendly: outbound HTTPS only, no inbound ports to open, automatic reconnect after your laptop sleeps or the network drops, and push notifications when a task finishes or a permission decision needs you. Inference still executes on your VPS; the phone is a control surface, not the computer.

The Codex Path: Run Codex on a VPS Instead

Prefer OpenAI's Codex CLI? The remote story is parallel but younger. The experimental path that the October 2026 guides document:

codex remote-control start starts the managed app-server daemon with remote control enabled, and codex remote-control pair generates a temporary manual pairing code. For the raw route, start the server on the VM with codex app-server --listen ws://127.0.0.1:4500, then reach it from your laptop through an SSH tunnel: ssh -N -L 4500:127.0.0.1:4500 devbox, and connect locally with codex --remote unix://.

Three cautions, all from the guides fetched this run: this is explicitly experimental and the daemon's lifecycle contract may change; OpenAI's security rule is to never expose app-server transports directly on a shared or public network — keep it bound to localhost and reach it over SSH, a VPN, or Tailscale; and keep the local Codex client and the remote host on the same version, because the WebSocket protocol can break across versions. The daemon auto-starts on Codex 0.157+ and auto-updates hourly — handy on your own box, a restart risk on shared machines. (tobilg.com, openclawlaunch.com, and varops.com, fetched November 3, 2026.)

The Three Connectivity Models, Compared

The October 29 dev.to remote-agents guide names the three models every remote-agent setup reduces to. Pick consciously:

Most beginners should start with model one — it teaches the fundamentals the other two abstract away — and add a vendor relay for phone convenience once the basics feel boring.

Own VPS vs Managed Alternatives: When to Pay Someone Else

Running your own box is the self-host AI coding agent path in its purest form, while two managed options and the sandbox family exist for people who would rather not babysit SSH keys — presented as a comparison, not an endorsement:

The honest decision rule: if you enjoy SSH and want the cheapest long-running agent, own the VPS; if you want the agent without the server, pay the managed box. Both are legitimate — the mistake is paying for managed while treating it like your own server, or running your own server while never learning SSH.

Locking It Down: The Security Checklist

The security section is mandatory and it is short, because server security for one agent box really is this list. Say it once, do it always:

1. SSH keys, never passwords — PasswordAuthentication no, done in Step 2.
2. Firewall to SSH only — on Ubuntu, ufw allow 22/tcp then ufw enable; add ports only when a service actually needs them.
3. Automatic security updates — enable unattended-upgrades so the box patches itself; an agent server you forget about is still a server.
4. No exposed agent transports — Codex's app-server stays bound to 127.0.0.1 behind your SSH tunnel; Remote Control needs no inbound ports at all, which is the point.
5. Separate credentials per purpose — the SSH key that reaches the box is not the API key that pays for tokens; compromise of one must not mean compromise of the other.

Five Beginner Mistakes on a VPS

Sources

Anthropic, "Remote Control," Claude Code docs (code.claude.com/docs/en/remote-control) — fetched November 3, 2026. Anthropic, "Set up Claude Code," Claude Code docs (code.claude.com/docs/en/setup) — fetched November 3, 2026. Devandrew, "Mastering Remote AI Agents: A Comprehensive Guide to Claude and Codex on Virtual Machines," dev.to — published October 29, 2026, fetched November 3, 2026. Beam, "Best Stateful Sandbox Code Execution 2026," beam.cloud/blog — fetched November 3, 2026. Geeky Gadgets, "Run AI Agents VPS," geeky-gadgets.com — published December 2025, fetched November 3, 2026. Tobilg, "Using a Local Codex App Server Remotely," tobilg.com — commands current as of October 25, 2026, fetched November 3, 2026. OpenClawLaunch, "Codex VPS Hosting," openclawlaunch.com — fetched November 3, 2026. VarOps, Codex CLI daemon notes, varops.com — fetched November 3, 2026. TermSquad, "Always-On Cloud Computer," termsquad.com/features — fetched November 3, 2026. Superfluidity.ai, Turm pricing watcher entry — re-read October 31, 2026. Reintech, "Setting Up SSH Key Authentication Ubuntu 22," reintech.io — fetched November 3, 2026. LearnUbuntu, ssh-copy-id guide, learnubuntu.com — fetched November 3, 2026. AI Parabellum, Claude Code Web tutorial — tested with Claude Code v2.1.310, October 26, 2026.

Frequently Asked Questions

Can I run Claude Code remotely on the free Claude plan?

No. Claude Code — local or on a VPS — requires a Pro, Max, Ultra, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access, so /login will fail on an ineligible account. This is per Anthropic's official docs, checked November 3, 2026.

Does the agent keep working when I close my laptop?

Yes, if the agent runs on the VPS inside tmux or a systemd service. The whole point of the server is persistence: your laptop sleeps, the VM doesn't. Without tmux or a service, closing your SSH connection kills the agent — that is the single most common beginner surprise.

Can I run Codex on a VPS instead of Claude Code?

Yes. Install the Codex CLI on the server, then either use the experimental codex remote-control start daemon or run codex app-server --listen ws://127.0.0.1:4500 and reach it through an SSH tunnel. Codex on VPS setups use the same SSH-key discipline as the Claude path — keep the app-server bound to localhost and the client and server versions matched.

How much does running Claude Code on a VPS cost?

Two bills: the Claude subscription (your plan, same as local use) and the server (a small VPS — see our cheap VPS hosting guide for current prices). There is no extra Claude Code license for the server. Managed alternatives like Turm or TermSquad fold the server into one price instead.

Is it safe to expose the agent to the internet?

The agent itself, no — but you don't have to. SSH keys plus a firewall leave exactly one hardened door (port 22); Remote Control uses outbound HTTPS with no inbound ports; the Codex app-server must stay on localhost behind an SSH tunnel. Follow the security checklist above and the setup is boring in the best way.