Running Claude Code on a VPS

A Claude Code run on a decent-sized task can take twenty or forty minutes. If the agent runs on your laptop, the laptop has to stay open and online that whole time, which in practice means you either sit there watching it or you come back to a dead session more often than you'd like.

I moved my agent work to a VPS a while ago. The agent runs there, the repo lives there, and I check on it from a browser when I want to. Laptop sleep doesn't matter anymore. This post is the setup and a few things I learned running it this way.

Server setup

You need a VPS with Node 18+ and the claude CLI logged in. Mine is a 4 GB Hetzner instance; Claude Code itself doesn't need much, but your builds and tests run on the same box, so size for those.

ssh dev@your-server

# Node, if needed
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs git

# Claude Code
npm install -g @anthropic-ai/claude-code
claude login

# project + host
git clone https://github.com/you/your-project.git
cd your-project
npx codemote-cli start

claude login opens a browser auth flow; on a headless server it gives you a URL to open elsewhere and a code to paste back. Mildly annoying, works fine.

The last command prints a pairing code. Open the connect page in any browser, paste it, and you're in the workspace. If the claude binary is present on the server, the agent chat is available; if it's missing, the workspace tells you.

What's different from running claude in a terminal

Functionally it's the same agent. The differences are around it.

Output is rendered instead of scrolled. Tool calls show up as cards, file edits as diffs. When the agent asks permission to run a command, you get the command in a proper prompt rather than somewhere in the scrollback. I didn't expect to care about this much, and then I went back to the raw CLI for a week on another machine and found myself scrolling up constantly to find what the agent had actually changed.

The session belongs to the server. This is the actual reason to do any of this. Close the tab mid-run and the agent keeps going. Reopen the workspace later, from any machine, and the chat is there with whatever happened in between. I regularly start something in the morning, close everything, and read the result after lunch.

There are real terminals next to the chat. When the agent says the tests pass, I run them myself. This isn't paranoia exactly; it's that verifying is cheap when the terminal is on the same machine as the agent, so there's no reason not to.

Things I learned the annoying way

Watch the disk. My first box had 40 GB and filled up during a run, at which point the agent started producing confusing errors that took me a while to trace back to ENOSPC. Agents install dependencies more casually than you do. 80 GB has been fine.

Put a CLAUDE.md in the repo. This is standard advice for Claude Code generally, but it matters more when you're not watching the run live, because you're not there to correct a wrong assumption in the first two minutes.

Keep the host per project. codemote-cli start runs inside a project directory and scopes the workspace to it, which matches how Claude Code wants to work anyway. I tried pointing one host at a parent folder with five repos in it and it was worse in every way.

Don't pre-approve everything just because you're remote. It's tempting, because permission prompts used to mean the run stalls until you notice. Notifications fix that properly. The prompts are the only leash the agent has.

Is this worth a VPS

If you run one short agent task a day at your desk, probably not; the laptop is fine. It became worth it for me when the tasks got long enough that "keep the laptop open" was a real constraint, and when I started wanting to check on runs from other places. The server costs 6 euros a month and also does backups and a staging deploy, so the marginal cost of the agent living there is roughly zero.

The workspace setup itself is covered in the VPS post. Beta signup is on the homepage.