How to Install Claude Code on a Headless Server or Raspberry Pi

Running Claude Code on a headless box instead of your laptop is mostly an argument about blast radius and uptime, not about speed. A homelab server or a Raspberry Pi is always on, has wired ethernet, and does not care that a build takes thirty minutes. More importantly, an agent that runs shell commands there is not running them next to your browser cookies, your SSH keys and your password manager.

This guide covers the install on a headless Debian-family system, the official requirements that decide whether your hardware qualifies, and the two failure modes that actually bite on small machines.

Check the requirements before you start

These are the published system requirements, and on small single-board computers they are the difference between a working install and a confusing one:

• OS: Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+ (also macOS 13.0+ and Windows 10 1809+, not relevant here)
• Hardware: 4 GB+ RAM, x64 or ARM64
• Network: internet connection required
• Shell: Bash or Zsh
• Account: a Pro, Max, Team, Enterprise or Console account. The free claude.ai plan does not include Claude Code.

ARM64 is explicitly supported, so a Raspberry Pi is a legitimate target rather than a workaround. The 4 GB line is the one to take seriously: a 2 GB Pi 4 is below the stated requirement, and the symptoms of ignoring it are covered below.

Picking the hardware

The official requirement is a floor, not a recommendation. Our read on how the common homelab options behave against that floor:

Treat the “practical limitation” column as our assessment, not vendor guidance.

Install

The native installer is the recommended method and the one to use here:

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

Then confirm:

claude --version

A working install prints a version number such as 2.1.211 (Claude Code).

Worth correcting a common misconception, including in earlier versions of this article: Claude Code is not a Node.js application at runtime. The installer places a native binary, and even the npm package pulls in a per-platform native binary through an optional dependency — the installed claude does not invoke Node. You do not need to install Node.js on the server to run it.

If you prefer package management, Debian and Ubuntu have a signed apt repository:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
gpg --show-keys /etc/apt/keyrings/claude-code.asc

Confirm the fingerprint reads 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE before continuing, then register the repository and install:

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

The trade-off is real and worth stating: the native install auto-updates in the background, apt installs do not. With apt you upgrade through your normal system workflow (sudo apt update && sudo apt upgrade claude-code). On a server you rarely log into, that difference decides whether you are running a current version six months from now.

The failure mode that actually bites: the OOM killer

This is the one that catches people on 2 GB Pis and small VPS instances. The install dies with:

bash: line 183: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

Exit code 137 is the Linux out-of-memory killer. Installing needs roughly 512 MB of free memory, and running Claude Code needs more than that. The fix on a machine you cannot add RAM to is swap:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Then rerun the install command. To make the swap file survive a reboot, add it to /etc/fstab.

Be clear-eyed about what this buys you: swap lets the install finish on a machine below the requirement. It does not make a 2 GB Pi a comfortable place to run an agent against a large repository, because swapping to an SD card is slow enough to feel broken. It is a way to get a small machine working, not a way to pretend it is a big one.

Keeping sessions alive over SSH

An SSH session that drops takes your agent with it. On a headless box, run Claude Code inside a terminal multiplexer so the session outlives the connection:

sudo apt install tmux
tmux new -s claude
# start claude, then detach with Ctrl+b then d
# reattach later from any machine:
tmux attach -t claude

This is ordinary tmux usage rather than anything Claude-specific, but it is the piece people skip and then regret on a long-running task.

Authentication on a machine with no browser

Logging in normally opens a browser. On a headless server, the practical route is the ANTHROPIC_API_KEY environment variable: when it is set, Claude Code prompts you once to approve the key instead of opening a browser.

Keep the key out of your shell history and out of any file you might commit. Setting it in your shell profile is the usual approach; putting it in a project file is how keys end up on GitHub.

Before you give an agent your homelab

The isolation argument at the top of this article only holds if the isolation is real. A few things worth deciding deliberately rather than by default:

• Run it as an unprivileged user, not root. Installing as root into / inside a container is also a documented cause of install hangs.
• Do not forward your personal SSH agent into the session unless you specifically need it. Agent forwarding hands the box the ability to authenticate as you everywhere.
• Decide what it can reach on your LAN. A homelab server usually has more network access than a laptop, not less — which inverts the isolation benefit if you do not think about it.

Sources

• Claude Code docs — Advanced setup (system requirements, native and apt install, npm native-binary behavior)
• Claude Code docs — Troubleshoot installation and login (exit code 137, 512 MB figure, swap procedure)
• Anthropic — Supported countries

Related reading