Running Claude Code on a VPS

Running Claude Code on a server instead of your laptop gets you three things. It keeps working when your laptop is shut. It survives a dropped connection. And it puts the agent on a machine you can throw away, not the one with your SSH keys and browser profile on it. This guide covers a setup that takes about fifteen minutes on a fresh Debian or Ubuntu box. The same steps work on Alpine and Fedora with small changes.

You need a Claude plan that includes Claude Code: Pro, Max, Team or Enterprise, or a Console account. The free claude.ai plan doesn't include it. Sign in with your subscription and there's no API key to manage and no usage billed on top.

1. Pick a box

Anthropic's system requirements list 4 GB of RAM or more and an x64 or ARM64 processor. The supported Linux systems are Ubuntu 20.04+, Debian 10+ and Alpine 3.19+. In practice your project's toolchain decides more than the CLI does:

• 4 GB: the documented minimum, fine for one session on a modest project.
• 8 GB: if you build anything substantial (a bundler, a test suite, a container or two) or run several sessions at once.
• 16 GB: if you run several agents in parallel, or a database next to them.

Hetzner, DigitalOcean, Scaleway, OVH, Vultr and others all work, and so does an old machine under your desk. Pick a region near you if you'll ever type into a terminal on it. ARM instances are usually the cheapest per gigabyte and Claude Code runs on them natively. Our guide to the best VPS for coding agents compares providers and sizes.

2. Create a non-root user

Many VPS images log you in as root. Don't run the agent as root. It turns any mistake into a system-wide one. Claude Code also refuses to start in bypass-permissions mode as root, so you'll need a normal user eventually anyway. On Debian or Ubuntu:

adduser dev
usermod -aG sudo dev
rsync --archive --chown=dev:dev ~/.ssh /home/dev

On Fedora the admin group is wheel instead of sudo. On Alpine, install sudo or doas first. The last line copies the key you're already logged in with, so you can reconnect as dev before you lock anything down. Test it from a second terminal before closing the first. Locking yourself out of a fresh VPS is a rite of passage worth skipping.

3. SSH keys and hardening

If you're still logging in with a password, switch to a key first. Generate one on your computer with ssh-keygen -t ed25519, then copy it up with ssh-copy-id dev@your-server. Once key login works, edit /etc/ssh/sshd_config:

PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes

Then restart SSH: sudo systemctl restart ssh on Debian and Ubuntu. On Fedora the service is called sshd, so run sudo systemctl restart sshd. For more, add fail2ban and a firewall that only allows SSH. If the machine doesn't need to be on the public internet at all, put it on a Tailscale network. Your phone joins the same network and reaches it directly.

From a phone: SSH apps can generate a key on the device and show you the public half to paste into ~/.ssh/authorized_keys. Maude does this for you: its "Set up key login" button creates a key over the connection you already signed in with. It installs the public half, tests the new key, and keeps the private half only in the phone's keychain.

4. Install Claude Code

Anthropic now recommends the native installer, which doesn't need Node.js. Run it as your normal user, not with sudo:

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

It puts the launcher at ~/.local/bin/claude and updates itself in the background. claude doctor checks the install and your settings without starting a session. Some alternatives, all from the setup docs:

• Signed apt, dnf and apk repositories if you'd rather the system package manager owned it. These don't auto-update; you upgrade with the rest of the system.
• npm still works (npm install -g @anthropic-ai/claude-code, Node.js 22 or later). It installs the same native binary. Anthropic warns against sudo npm install -g.
• Alpine needs bash, curl, libgcc, libstdc++ and ripgrep, plus USE_BUILTIN_RIPGREP=0 in your settings.

If an older guide told you to install Node first, you can skip that step now.

5. Log in without a browser

Run claude (or claude auth login) and follow the prompts. A VPS has no browser, so you'll open the login URL on any other device. Claude Code lets you press c to copy it. Sign in there. When the browser can't reach Claude Code's local callback, which is normal over SSH, it shows a code instead. Paste that at the Paste code here if prompted line and the login completes on the server.

The credential is saved in ~/.claude/.credentials.json with mode 0600. Treat the box accordingly: anyone with a shell as that user can use your Claude subscription. For scripts and CI there's also claude setup-token, which prints a one-year token you set as CLAUDE_CODE_OAUTH_TOKEN. Per the authentication docs, that token can only make model requests and can't start Remote Control sessions.

6. Keep it alive

Anything you start in the foreground of an SSH session dies with that connection. The usual fix is tmux:

sudo apt install tmux
tmux new -s work
# start claude, then detach with Ctrl-B then D
tmux attach -t work

You can detach, lose signal, reconnect hours later and reattach, and the session is untouched. tmux doesn't survive a reboot, though. After one, claude --continue picks up the most recent conversation in that directory. Our guide on keeping Claude Code running after you close your laptop covers the other options, including systemd and session daemons.

7. Same box, more agents

A server that runs Claude Code can run the other coding agents next to it. Each one installs into your home directory and keeps its own login, so they don't get in each other's way. Leave room in RAM for each one that runs at the same time.

Sources: Codex auth, OpenCode docs, Grok Build docs, Antigravity CLI install, checked October 2026. Codex and Antigravity have their own walkthroughs: Codex CLI on a VPS and Antigravity CLI on a server. Gemini CLI is no longer an option for personal Google accounts, and Antigravity CLI is Google's replacement.

8. Reach it from your phone

There are three ways to do it, from the most hands-on to the least:

An SSH app and tmux. Termius, Blink or any other client, attached to your tmux session. It's free and complete, and you're driving a full-screen terminal with a soft keyboard. Here's how that compares.

Remote Control. Start claude remote-control inside tmux and open the session from the Code tab of the Claude app. It's included with Pro, Max, Team and Enterprise. Anthropic's docs suggest tmux or screen for exactly this case. It only works for Claude, and the permission prompts the session raises come to the phone for you to answer. The app can't switch the session to Auto or Bypass permissions.

Maude. Maude does steps 4 and 6 for you, and step 5 moves to your phone. You add the server by address, by pasting an ssh … command, or by scanning a QR code from curl -fsSL https://maude.pilotdev.fr/setup | sh. If you're logged in as root, a button creates the non-root user from step 2 for you. Maude then deploys its own daemon over SSH and installs each agent at a version we have tested and pinned. You sign in to Claude, Codex or any of the others from the phone. Sessions keep running on the server when the app is closed, and the server dials out to Maude's relay, so it works behind NAT without an open port.

9. Decide on permissions

Now the interesting question: how much do you let it do unattended? A server you can rebuild is the right place to relax permissions, as long as you've actually treated it as disposable. Claude Code's auto mode, where a classifier approves safe actions, covers a lot of the gap. Full bypass has rules of its own, including the root restriction from step 2. They have their own page: running Claude Code with full permissions, safely.

Run it from your phone

Once the server is up, Claude Code on your phone explains how Maude drives it. If Claude isn't your only agent, start from the agents overview.

Frequently asked questions

What changed

• October 1, 2026 — Install switched to Anthropic's native installer (Node.js no longer required); RAM guidance aligned with the documented 4 GB minimum; headless login paste-code flow and setup-token added; new section on running Codex, OpenCode, Grok Build and Antigravity on the same box.
• July 25, 2026 — First published.