Claude Code on a VPS: An Agent That Outlives Your Laptop Lid

Claude Code is an agentic coding tool for the terminal, not a chatbot: it reads your code, decides on its own which commands to run, edits files, runs your tests, and narrates what it's doing and why along the way. By default it lives wherever you started it, which is usually a terminal on your laptop. Close the lid, let it sleep, lose Wi-Fi on a train, and any task that takes longer than a couple of minutes dies mid-step. Moving the agent to a VPS you control isn't a "just in case" move; it solves a specific problem: the session lives next to the server you're actually working on, and it keeps running long after your laptop is closed.

Short version. On Linux, Claude Code's current official install doesn't touch Node.js at all - curl -fsSL https://claude.ai/install.sh | bash. The npm path (npm install -g @anthropic-ai/claude-code) still works but needs Node.js 22+ and counts as the fallback these days. Logging in is just running claude: it opens a browser for OAuth login, and when there's no browser on the box, it offers to copy a link you open elsewhere and a code you paste back. Keep a session that has to survive a dropped SSH connection in tmux, not wrapped in systemd - this is an interactive back-and-forth with an agent, not a background daemon. Claude Code has real shell and filesystem access, and that deserves the same caution as any SSH key: a dedicated non-root user, a specific working directory, nothing else sitting nearby.

Why put Claude Code on a VPS when it already runs on your laptop

The simplest reason: a laptop isn't built to keep a process alive for hours unattended. It sleeps when idle, gets closed and shoved in a bag, switches networks mid-task. Any of that kills a running Claude Code session unless you paused it first. A VPS does none of that - staying up is its entire job.

The second reason is genuinely long-running agentic work: a migration across a large codebase, a batch of failing tests, the same fix applied across dozens of files. Worth kicking off and walking away from, not babysitting next to a laptop that might doze off mid-task.

The third reason is more concrete: the agent's working environment ends up right next to where the deployment happens. Editing an nginx config, fixing a systemd unit, figuring out why a service is dying on memory - an agent already on that server doesn't need files copied over or journalctl output described to it. It reads exactly what you'd see logging in yourself.

And last, a persistent box is something several people, or CI-adjacent tooling, can reach - a single laptop isn't. A second team member connects with their own SSH key and opens their own tmux session next to yours, without reinstalling anything.

What the server needs before you install anything

Claude Code's official requirements are modest, but one of them is worth checking ahead of time, because the cheapest VPS tier usually doesn't clear it.

If your existing tier sits at 1-2 GB for something lightweight, don't try to squeeze Claude Code onto it. Get a separate 4 GB+ plan, or put the agent on the same box as something else only if there's genuine headroom above that floor.

Step 1. Install Claude Code on the server

The official Linux path skips Node.js entirely - you're installing a compiled binary, not an npm package. Connect over SSH as your own user (not root, more on why below) and run:

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

The installer drops the binary into ~/.local/bin, your home directory, not a system path, so it needs no sudo. Most current Ubuntu shells already have that directory on PATH; if the terminal answers command not found: claude afterward, add this line to the end of ~/.bashrc and reconnect:

export PATH="$HOME/.local/bin:$PATH"

Confirm the install worked:

claude --version

A working install prints a version number - on the test server while writing this article (September 24, 2026), the command returned 2.1.281 (Claude Code). Yours will almost certainly show something different: Claude Code auto-updates in the background and the version number moves practically day to day, which is normal, not a sign anything went wrong. For a deeper health check, including permission and config issues, run:

claude doctor

If the same box already runs a Node project and you have Node.js 22 or newer anyway, the npm path works just as well for day-to-day use:

npm install -g @anthropic-ai/claude-code

• Don't run this as sudo npm install -g - it complicates future updates and hands root a job it doesn't need. If npm complains about write permissions on the global directory, fix npm's prefix for your user instead of reaching for sudo.
• On an older Node.js version, npm prints an EBADENGINE warning but still finishes the install - the warning doesn't mean anything is broken right now, but it's worth scheduling a Node upgrade.

Step 2. Log in from a server that has no browser

Run:

claude

On first launch, Claude Code tries to open a browser for a standard OAuth login to your claude.ai account. A bare SSH server obviously doesn't have one, and that's already accounted for: press c to copy the login link to your clipboard, open that link in a browser on your own machine, sign in, and paste the code the browser shows back into the server's terminal prompt. This is the officially documented path for SSH sessions, WSL, and containers, not an improvised workaround.

What you should see. A successful login prints Login successful and prompts you to press Enter to continue - that line is your confirmation the session is authenticated.

There's a second option: set the ANTHROPIC_API_KEY environment variable with a key from the Claude Console. When it's set, Claude Code skips the browser entirely and just asks you once whether to approve using it. The practical difference:

• Account login (Pro/Max/Team subscription) - simpler for a personal box: sign in once from your phone or laptop, and the session refreshes itself in the background afterward.
• API key - a better fit for a shared server or any automation that shouldn't require an interactive login at all: mint the key in the Console and pass it through the environment, no browser step involved.

Credentials are stored in ~/.claude/.credentials.json with file mode 0600, meaning only the file's owner can read it. That's one more reason to run the agent under a dedicated user without passwordless sudo: your login to Anthropic shouldn't be sitting somewhere anyone else on the box can reach.

A session that survives an SSH drop: tmux, not systemd

Claude Code is a conversation, not a background service: the agent waits for your next reply, asks clarifying questions, and shows you what it's about to do before doing it. Wrapping that in systemd with Restart=always, the way the article on keeping a service alive on a server describes, is the wrong tool here - you'd end up with a process that keeps restarting on its own, not a session you can return to. The right tool is a terminal multiplexer: something that keeps a terminal session running on the server independently of your SSH connection to it. If it isn't already installed:

sudo apt install -y tmux

Start a named session and run Claude Code inside it:

tmux new -s claude

claude

Work with the agent as usual from there. When you're ready to step away, don't type exit - that kills the session along with the process inside it. Detach instead with Ctrl+b, then d. The session keeps running on the server on its own.

Get back to it later, whether from this same laptop, your phone over SSH, or tomorrow:

tmux attach -t claude

Check which sessions are currently alive on the server:

tmux ls

What you should see is a line like claude: 1 windows (created ...). If nothing shows up and you're sure you created a session, you likely typed exit instead of detaching with Ctrl+b d.

One boundary worth knowing: tmux survives a dropped SSH connection, a closed laptop, or a network switch, but not a reboot of the server itself. It's an ordinary process, not a system service, and rebooting takes it down along with whatever session was inside it. If that matters to you, say the server reboots regularly for kernel updates, just recreate the session afterward - it takes seconds.

Claude Code also has its own native background-session mode, run through an internal supervisor process (/background, the --bg flag), which is a newer, version-specific capability. tmux works identically across any version and with any other interactive program on the server, which is why it's the one covered here.

Shell access isn't a toy just because it's not your laptop

It's tempting to relax because "it's on a VPS, not my machine" - but from the agent's point of view nothing changed at all. It still has a command to run shell commands and edit files; those files and commands just now belong to a real server instead of a sandbox.

• A dedicated non-root user. Set one up the way the fresh-VPS security guide describes, and run claude under it. When the agent makes a mistake - renames the wrong file, deletes the wrong folder - the damage stays inside its own account instead of spreading across the system.
• A specific working directory, not the whole disk. Start claude from a single project's directory. By default it reads files without asking only within that directory and any you explicitly add.
• Approval before action - don't turn it off out of habit. By default Claude Code asks permission before running a command or editing a file, outside a narrow set of read-only actions. You can approve a command permanently for a given repository - fine for routine work. A no-questions-asked mode also exists; turning it on near other people's projects or production data should be deliberate and short-lived, not a default.
• Nothing else sitting next to it. If the server already holds someone else's client projects, a production database, or another service's secrets, don't launch the agent from a directory where all of that is one cd .. away.

Resources and networking: what the agent actually needs from the box

On resources, the only official threshold is 4 GB of RAM for the whole machine, not the process alone. The agent itself is an ordinary client that holds a conversation's context in memory and talks to the API over HTTPS; it only gets heavy when your instructions have it building a project or running a test suite, and at that point the build is doing the work, not Claude Code. On the test server, right after launch and before logging in, the process held about 180 MB of real memory (VmRSS in /proc/<pid>/status) - that's the process's starting footprint, not a figure for an active conversation with a loaded context, and it grows as a session goes on. Check ps aux | grep claude or top on your own server for the real number for your own workload rather than trust a figure someone else measured - reports vary a fair amount with session length.

Networking is more clear-cut: Claude Code is an outbound-only client. It reaches Anthropic's servers over HTTPS (api.anthropic.com for model requests, claude.ai and platform.claude.com for login) and doesn't listen for anything coming in. A default-deny-incoming firewall, the same ufw setup from the fresh-VPS security guide, needs no changes at all - there's no reason to open a port, since nothing outside the server is ever supposed to reach it.

Claude Code or a self-hosted model with Ollama

I'm not going to pretend this is a close call. If the job is actually writing and fixing code in your own repository - a multi-step bug, refactoring a module, orienting itself in an unfamiliar codebase - Claude Code wins on reasoning quality by a wide margin. The models a GPU-less VPS can run through Ollama (typically 7-8 billion parameters, occasionally more) usually aren't strong enough for that kind of work: they lose the thread over a long context, drop steps in a multi-part task, and hand back code that looks plausible and doesn't run.

A self-hosted model through Ollama has a legitimate place, just a different job: data that genuinely can't leave your infrastructure, a flat bill without per-token charges, or a model that's a component inside your own product rather than a tool for you personally. Then the VPS becomes the actual compute, not a terminal next to your server - exactly what the AnythingLLM on a VPS article covers: a real interface and RAG on top of a model that lives entirely on your own box.

If something's not working

• command not found: claude right after install. ~/.local/bin isn't on your shell's PATH. Add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc and reconnect over SSH.
• No browser opens on login, and there's nowhere to paste a link. Expected on a headless SSH session. Press c to copy the link, open it on your own machine, and paste the resulting code back into the server's terminal.
• 403 Forbidden despite an active subscription. Check whether ANTHROPIC_API_KEY is set in that same shell from an old or unrelated key - if it is, Claude Code uses it instead of your subscription. Run unset ANTHROPIC_API_KEY, and check /status inside a session to confirm which credential is actually active.
• Login expired after a few weeks. Logins aren't permanent; Claude Code warns you at startup a few days before expiry. Run /login inside a session to sign in again.
• A tmux session is gone after routine server maintenance. Expected if the server rebooted - tmux survives a dropped connection, not a reboot. Recreate it with tmux new -s claude and start claude inside it again.

FAQ

Does Claude Code need Node.js?

No, not with the official native installer, which downloads a compiled binary and never touches Node.js. Node.js is only needed for the npm install path, and as of version 2.1.198 that requires Node.js 22 or later.

How do you log into Claude Code on a server with no browser?

Run claude, press c to copy the login link, open it in a browser on your own machine, and paste the code it shows back into the server's terminal. This is the documented path for SSH sessions, WSL, and containers.

How do you keep a Claude Code session alive after an SSH disconnect?

Run claude inside tmux. A dropped connection or a closed laptop only disconnects your terminal from the session, not the session on the server itself - get back to it with tmux attach -t claude. The exception is a server reboot, which stops tmux along with the session inside it.

How much RAM and CPU does Claude Code use?

The official minimum is 4 GB of RAM for the whole server, a requirement on the machine as a whole. The agent process itself is lighter than that on its own and only gets heavy when your instructions have it running a build or a test suite - check your own workload with ps aux or top rather than trust a fixed figure.

Does Claude Code need any inbound ports open?

No. Claude Code is an outbound-only client: it reaches Anthropic's servers over HTTPS on its own and never listens for inbound connections. A default-deny-incoming firewall needs no changes at all.

Should you use Claude Code or a self-hosted model with Ollama?

For real agentic coding work, Claude Code wins on reasoning quality by a wide margin - the models a GPU-less VPS can run through Ollama usually aren't strong enough for that job. Ollama on your own server earns its place when data can't leave your infrastructure at all, or when a flat bill without per-token cost matters more than peak capability.

Is it safe to give an AI agent shell access to your server?

It's real access to files and commands, and it deserves the same caution as an SSH key with login rights. Claude Code asks for approval by default before running commands or editing files, but the actual safety still comes from your setup: a dedicated non-root user, a specific working directory, and no unrelated projects or production data sitting nearby.

Takeaways

• The current official Linux install skips Node.js entirely - curl -fsSL https://claude.ai/install.sh | bash. The npm path still works but needs Node.js 22+ as of version 2.1.198.
• Logging in from a browser-less server is a documented flow, not a workaround: run claude, press c to copy the link, paste the code back. An ANTHROPIC_API_KEY skips the interactive login entirely.
• Keep the session in tmux, not systemd - this is a conversation with an agent, not a background service. Ctrl+b d to detach, tmux attach -t claude to come back. A server reboot still ends the session.
• The official hardware floor is 4 GB of RAM for the whole server; networking needs only outbound HTTPS, no inbound ports at all.
• Shell access is real access whether it's on a laptop or a VPS: a dedicated non-root user, a scoped working directory, and don't disable the approval prompts out of habit.
• For actual code work, Claude Code beats anything a GPU-less VPS can run through Ollama; a self-hosted model earns its place when data can't leave the box or a flat bill matters more than capability.

What's next

• Secure a fresh VPS - a non-root sudo user, key-only login, ufw: do this before an agent ever touches the server.
• Deploy a service and keep it running 24/7 - for comparison, what a correctly built background process looks like with systemd, when the job isn't an interactive session.
• Ollama on a VPS - installing and securing your own model if the job genuinely calls for self-hosted inference instead of an API.
• AnythingLLM on a VPS - a web interface and RAG layer on top of your own model, the next step after a bare Ollama API.