Claude Code on a VPS: Set Up a Sandboxed Remote Dev Box (2026)

To run Claude Code on a VPS, deploy an Ubuntu 24.04 server with at least 4 GB of RAM, create a dedicated user without sudo, install Claude Code with Anthropic’s native installer, log in by pasting the browser code over SSH, and start every session inside tmux. The result is a sandboxed remote dev box: the agent reaches only what you put on the server, while your laptop, personal SSH keys and production secrets stay out of its reach.

Each command follows the official Anthropic, Ubuntu and GitHub documentation as of October 2026, and the setup adds the least-privilege steps most guides skip: no sudo for the agent, a single-repo key, and a sandbox policy the agent cannot edit.

Why run Claude Code on a VPS instead of your laptop?

Claude Code reads files, edits code and runs shell commands with the permissions of the user who starts it. On a laptop, that user can also read your browser profile, your SSH keys and every other project. A VPS gives the agent its own machine and its own kernel, so a bad command or a prompt injection lands on a disposable server instead of your workstation.

A dedicated virtual machine provides the strongest separation, with its own kernel and, in cloud or microVM deployments, its own virtualized hardware.

Anthropic, Claude Code docs: Choose a sandbox environment

• Long sessions. The server stays on when your laptop sleeps, and tmux holds the session through dropped SSH connections.
• A reproducible environment. One OS image and one toolchain, rebuilt from a script or rolled back to a snapshot.
• A clean exit. Delete the server, and the login, transcripts and caches on it go with it.

What a VPS does not change: Claude still sends your prompts and the files it reads to Anthropic’s API. In Anthropic’s words, isolation “does not change what is sent to the model.” For always-on agents driven from Telegram or Discord rather than an interactive coding session, see how to run AI agents on a VPS.

VPS, laptop or Claude Code on the web?

Two alternatives cover part of the same ground, and each is a better fit for some jobs:

What size VPS does Claude Code need?

Anthropic lists 4 GB of RAM as the minimum, on an x64 or ARM64 processor, with Ubuntu 20.04+ or Debian 10+ (system requirements, October 2026). The installer alone needs roughly 512 MB of free memory. Below that, the Linux out-of-memory killer stops it with exit code 137, which Anthropic calls “common on small VPS and cloud instances.”

The model runs on Anthropic’s servers, so the VPS does no inference and needs no GPU. Its RAM and CPU go to the work Claude triggers: package installs, builds, test suites, language servers and dev servers. Size the box for your toolchain, not for the agent.

Pick a location close to you, because every keystroke over SSH makes a round trip. HourlyVPS deploys KVM servers in Istanbul today, with New York coming soon, and our guide to choosing a VPS location shows how to measure latency first. Anthropic’s setup docs also require one of its supported countries; Türkiye and the United States are both on that list as of October 2026.

Set up the server: firewall and a no-sudo agent user

Deploy Ubuntu 24.04 LTS and log in as your sudo-capable admin user. If you only have a root login so far, work through our checklist to secure a new Linux VPS first; the guide to connecting to a VPS over SSH covers keys and the first login.

This setup uses two accounts: your admin account keeps sudo, and a separate agent account runs Claude Code without it, so nothing the agent runs can change system files, the firewall or its own sandbox policy. Several popular guides put the agent user in the sudo group, which hands it the whole machine.

1. Update the system and install git, tmux and curl (as the admin user):

sudo apt update && sudo apt upgrade -y
sudo apt install -y git tmux curl

2. Allow SSH, then turn on the firewall. Claude Code needs no inbound ports, Remote Control included, so SSH stays the only open port.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

3. Create the agent account without a password. It logs in with your SSH key only.

sudo adduser --disabled-password --comment "Claude Code agent" agent

4. Copy your SSH public key to the agent account:

sudo install -d -m 700 -o agent -g agent /home/agent/.ssh
sudo install -m 600 -o agent -g agent ~/.ssh/authorized_keys /home/agent/.ssh/authorized_keys

5. Check it. From your laptop, log in with ssh [email protected] (your server’s IP) and run groups. Besides agent it may list the shared users group, but never sudo, adm or docker.

Ubuntu 21.10 and later create home directories with mode 0750 (Ubuntu Server docs), so the agent cannot read your admin user’s files. If ls -ld /home/* shows drwxr-xr-x for one, run sudo chmod 0750 on it.

Install Claude Code with the official installer

Log in as agent for everything from here on. Anthropic’s recommended method is the native installer. It needs no Node.js and installs into the user’s home directory, so it needs no sudo:

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

Open a new shell, then check the version. A working install prints a version number.

claude --version

If Bash answers claude: command not found, the launcher at ~/.local/bin/claude is not on your PATH yet. Anthropic’s fix for Bash on Linux:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Finish with the read-only diagnostics, which check the install, your settings files and the auto-updater:

claude doctor

Release channels and other install methods

• Stable channel. Native installs update themselves in the background. For a box you leave running, curl -fsSL https://claude.ai/install.sh | bash -s stable follows a channel about a week behind that skips releases with major regressions.
• apt, dnf or apk. Anthropic publishes signed repositories. Installed from the admin account, the binary is one the agent cannot modify; it does not auto-update, so upgrade with sudo apt update && sudo apt upgrade claude-code.
• npm. Needs Node.js 22 or later; Anthropic warns against sudo npm install -g.

Check out your project with a single-repo key

Do not copy your personal GitHub key to the server. Generate a key on the VPS and add it to one repository as a deploy key. Per GitHub’s docs, a deploy key “grants access to a single repository,” is read-only unless you tick Allow write access, and never expires, so you remove it yourself when the box goes away.

1. Generate an Ed25519 key as agent. Press Enter to accept the default path and leave the passphrase empty so Claude’s git commands can use the key; that is why it should open one repository only.

ssh-keygen -t ed25519 -C "agent@claude-vps"

2. Print the public key and add it under the repository’s Settings → Deploy keys → Add deploy key. Leave write access off unless Claude should push branches: GitHub warns that a deploy key with write access “can perform the same actions as an organization member with admin access” on that repository.

cat ~/.ssh/id_ed25519.pub

3. Set a commit identity so Claude’s commits are easy to spot.

git config --global user.name "Claude agent (VPS)"
git config --global user.email "[email protected]"

4. Clone the repository into ~/work.

mkdir -p ~/work && cd ~/work
git clone [email protected]:your-org/your-repo.git

For an organization with many repositories, GitHub recommends a GitHub App over deploy keys for finer-grained permissions.

How do you log in to Claude Code on a headless VPS?

Claude Code needs a Pro, Max, Team, Enterprise or Console account; the free claude.ai plan does not include it. A server has no browser, and Anthropic documents the flow for exactly this case:

1. Change into the project and run claude. Start in the project, not your home directory: Anthropic notes that workspace trust accepted in the home directory is not saved, so the prompt returns on every launch.
2. Pick your account type, copy the login URL Claude Code prints, and open it in your laptop’s browser.
3. Sign in. The browser cannot reach the server’s local callback, so it shows a login code instead of redirecting.
4. Paste the code at the Paste code here if prompted prompt. The terminal shows Login successful.

cd ~/work/your-repo
claude

If pasting into the prompt does nothing, run the login on its own; it reads the pasted code from standard input:

claude auth login

Which credential should a VPS use?

Set one method per account: Claude Code picks credentials in a fixed order, and /status shows which one is active. On a box you plan to delete, the subscription login is the easiest credential to clean up.

Keep sessions running with tmux, Remote Control or the desktop app

Claude Code is an interactive terminal app, so it stops when its terminal does. Anthropic’s Remote Control docs give the fix for a remote machine: to keep a session running after you disconnect from SSH, “start it inside tmux or screen.”

Configure tmux for Claude Code

Inside tmux, Shift+Enter submits instead of adding a newline, and notifications never reach your local terminal. Anthropic’s terminal guide fixes both with the first three lines below. The fourth comes from Anthropic’s fullscreen rendering docs: the mouse wheel scrolls Claude Code only with tmux mouse mode on, while PgUp and PgDn work either way. Put all four in ~/.tmux.conf:

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
set -g mouse on

Save them with an editor such as nano ~/.tmux.conf. If a tmux server is already running, apply them in place:

tmux source-file ~/.tmux.conf

The daily loop

1. Attach from your laptop. This one command attaches to the tmux session named claude, or creates it; the -A flag makes new-session attach when the name already exists.

ssh -t [email protected] tmux new -A -s claude

2. Start Claude Code in the project, inside tmux.

cd ~/work/your-repo && claude

3. Detach by pressing Ctrl+b, then d. Claude keeps working while you close the laptop. Run step 1 again later, from any machine, to land back in the same session.

tmux sessions do not survive a reboot, but conversations do: Claude Code saves transcripts under ~/.claude/projects/. In the project directory, claude --continue reopens the most recent conversation and claude --resume opens a picker.

Steer it from your phone with Remote Control

Remote Control connects claude.ai/code or the Claude mobile app to the Claude Code process on your server. Start it inside tmux, or type /remote-control in a session that is already running:

claude --remote-control "your-repo"

• It needs a Pro, Max, Team or Enterprise login made with /login. API keys and setup-token tokens cannot start it, and on Team and Enterprise an owner must switch it on.
• The server makes outbound HTTPS requests only and never opens an inbound port, so the firewall stays as you set it.
• While connected, the session transcript is stored on Anthropic’s servers to sync your devices; commands and files stay on the VPS.

Prefer a window to a terminal? Use the desktop app over SSH

The Claude desktop app can run sessions on this server. Open the environment menu, choose + Add SSH connection, and enter [email protected] with your private key. Per Anthropic’s desktop docs, the remote machine must run Linux or macOS, the app installs Claude Code there on the first connection, and SSH sessions support permission modes, plugins and MCP servers. For a session that must outlive your connection, the documented route is still tmux.

Lock it down: permission modes, sandbox and secrets

The VPS protects your laptop. Inside the VPS, three layers decide what Claude can do: the permission mode, your permission rules and the OS-level Bash sandbox. Claude Code enforces these itself; instructions in a prompt or in CLAUDE.md do not change them.

Which permission mode fits a VPS dev box?

Press Shift+Tab to cycle modes, or start in one with claude --permission-mode plan. Anthropic says bypass mode “offers no protection against prompt injection or unintended actions” and points to auto mode instead. A VPS still has internet access, so the policy below switches bypass mode off and locks down the network.

Install the sandbox on Ubuntu 24.04

The sandbox wraps every shell command Claude runs in an OS-enforced boundary: writes only in the project and a temp directory, network only to domains you allow. Reads stay open by default, one more reason the agent account should hold nothing valuable. On Linux it uses bubblewrap and socat. Install them from your admin account:

sudo apt-get install bubblewrap socat

Ubuntu 24.04’s default AppArmor policy can stop bubblewrap from creating the user namespaces it needs. Check the setting:

sysctl kernel.apparmor_restrict_unprivileged_userns

If it prints 1, add Anthropic’s AppArmor profile for bwrap, then reload AppArmor. The profile applies to bwrap itself, not to the commands it runs. If it prints 0 or a No such file or directory error, skip this step.

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

A sandbox policy the agent cannot edit

Write the policy from your admin account to /etc/claude-code/managed-settings.json. Claude Code ranks managed settings above user, project and command-line settings, and root owns the file, so neither the agent nor a repository’s .claude/settings.json can switch these keys back. Every key comes from Anthropic’s docs; the file must be strict JSON, with no comments or trailing commas.

sudo mkdir -p /etc/claude-code
sudo tee /etc/claude-code/managed-settings.json > /dev/null <<'EOF'
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": [
        "github.com",
        "*.npmjs.org"
      ],
      "allowManagedDomainsOnly": true
    }
  }
}
EOF

• deny blocks Claude’s file tools from .env files in the directory you start Claude in (Anthropic’s own example); ask makes every git push prompt you.
• disableBypassPermissionsMode makes Claude Code reject --dangerously-skip-permissions.
• failIfUnavailable stops Claude Code at startup if the sandbox cannot start. allowUnsandboxedCommands set to false removes the “retry outside the sandbox” escape hatch and, in managed settings, stops a repository’s settings from loosening the sandbox.
• allowedDomains with allowManagedDomainsOnly limits shell commands to the listed hosts and blocks others without a prompt; add your registries here as admin. Git over SSH to an allowed host works on Linux. Claude’s built-in web fetch tool follows permission rules instead.
• Sandboxed commands run without a prompt, even in Manual mode; deny rules and the git push ask rule still apply. Add "autoAllowBashIfSandboxed": false under sandbox to approve each one.

Start Claude Code as agent and run /status: Setting sources should show Enterprise managed settings (file). Server-managed settings from a claude.ai organization take priority over this file. Then run /sandbox and test it as Anthropic suggests: ask Claude, not your own ! shell prompt, to run touch ~/sandbox-probe (expect Read-only file system) and curl --noproxy '*' https://example.com (expect Could not resolve host).

Anthropic lists docker as incompatible with the sandbox, and an excludedCommands exception runs it with the agent’s full access. If your project needs Docker, read how to install Docker on a VPS and weigh the trade-off: Docker’s own docs say the docker group “grants root-level privileges to the user,” which undoes the no-sudo design.

Ports, snapshots and updates

• Leave SSH as the only open port. Preview a dev server through an SSH tunnel, ssh -L 3000:localhost:3000 [email protected], instead of opening a port.
• Take a snapshot in the control panel before risky runs (dependency upgrades, migrations, a long auto-mode session) so you can roll back the whole disk.
• Patch the OS from the admin account; our VPS security checklist covers automatic security updates.
• The agent acts on your account, so our acceptable use policy applies to everything it runs.

What does a Claude Code VPS cost by the hour vs always-on?

Two bills apply. Anthropic bills model usage through your plan or API account; across enterprise deployments it reports an average of about USD 13 per developer per active day, with 90% of users staying below USD 30 per active day (Manage costs, October 2026). On API billing that figure dwarfs what a small server costs for a day, so the real server question is whether it runs while you are not working.

An 8-hour working session on Quartz Q4 costs $0.24; the same session on Quartz Q8 costs $0.40. Leaving a Q4 running all month costs no more than $15.00: once a server’s charges reach the monthly price, they stop for the rest of that billing period (one month from your order date).

Decision checklist: session box or always-on box?

Delete the box after each session if:

• you work in blocks of a few hours, a few days a week;
• you want a fresh server for each untrusted repository or risky experiment;
• your setup is scripted, so a rebuild takes minutes.

Rent it by the day for a one- to three-day sprint or hackathon: keep one server for the whole event, then delete it. Three days on Q4 is 72 hours of hourly billing, $2.16.

Leave it running if:

• you use Remote Control from your phone and want the session reachable at any hour;
• you leave tmux sessions running across days;
• you would rather keep caches, builds and the toolchain warm than rebuild: left on, the box never costs more than the monthly price in a billing period.

Run your own numbers in the VPS cost calculator, read why capped hourly billing never costs more than monthly, or see how an always-on dev box is billed on a monthly VPS. For what 4 GB costs at other providers, see how much a VPS costs in 2026.

Tear the box down cleanly

1. Push your branches and copy anything you want to keep.
2. Run /logout in Claude Code to remove the stored login from the server.
3. Delete the deploy key in the repository settings, and revoke any API key or token you placed on the box.
4. Delete the server. Stopping it does not stop billing; see which providers bill stopped servers and our checklist before you delete a VPS.

Troubleshooting Claude Code on a VPS