---
title: "How to run Claude Code on remote server machines and keep the session alive"
description: "To run Claude Code on remote server machines, start it in tmux over SSH or a Claude Desktop SSH environment, and sign in with claude.ai, since Remote Control refuses API keys."
url: "https://aldena.ai/blog/run-claude-code-on-remote-server"
---

# How to run Claude Code on remote server machines and keep the session alive

Published 2026-11-20.

## Five ways to put Claude Code to work on a server you control

To run Claude Code on remote server machines, put the `claude` process on the server and keep it alive after SSH disconnects, with [tmux](https://code.claude.com/docs/en/remote-control) or [Claude Desktop's background helper](https://code.claude.com/docs/en/desktop).

| Route                             | Where Claude Code runs                 | After an SSH drop       | With your laptop shut                  | Sign-in                       | From a phone                              |
| --------------------------------- | -------------------------------------- | ----------------------- | -------------------------------------- | ----------------------------- | ----------------------------------------- |
| `claude` in tmux over SSH         | the server                             | keeps running in tmux   | keeps running                          | claude.ai login or API key    | Remote Control, on a claude.ai login      |
| Remote Control server mode        | the server                             | keeps running in tmux   | keeps running                          | claude.ai login only          | claude.ai/code or the Claude app          |
| Claude Desktop SSH environment    | the server, under a background helper  | keeps running           | can stop within minutes of sign-in end | the Claude account in Desktop | not covered in the SSH docs               |
| VS Code Remote-SSH or a Tunnel    | the server, in the integrated terminal | keeps running in tmux   | keeps running in tmux                  | same as the CLI               | vscode.dev in a browser, through a Tunnel |
| Local Claude Code that runs `ssh` | your laptop                            | each command reconnects | stops                                  | your laptop's sign-in         | Remote Control, while the laptop is on    |

[Anthropic's Remote Control docs](https://code.claude.com/docs/en/remote-control) say the computer running the session has to stay on and the `claude` process has to keep running, and a server does both by default. [Claude Desktop's SSH docs](https://code.claude.com/docs/en/desktop) say not to count on a task running overnight, which is why I read the laptop-shut column before any other. If no machine of yours stays on, I'd skip all five and use [Anthropic's cloud sessions](https://aldena.ai/blog/claude-code-in-the-cloud) instead.

## The sign-in decides whether Remote Control works

Claude Code on a server starts Remote Control only from a claude.ai login, which [Anthropic's Remote Control docs](https://code.claude.com/docs/en/remote-control) list among its requirements.

[Anthropic's authentication docs](https://code.claude.com/docs/en/authentication) rank an approved `ANTHROPIC_API_KEY` above a claude.ai login, so a key exported in the server's shell profile takes over every session, and Remote Control doesn't support API keys. Run `unset ANTHROPIC_API_KEY`, then `/status` inside Claude Code to see which one is in use.

![Four ways Claude Code signs in on a server: an ANTHROPIC_API_KEY, a setup token, a gateway in ANTHROPIC_BASE_URL and a claude.ai login, with only the claude.ai login able to start Remote Control](https://cdn.aldena.ai/images/blog/run-claude-code-on-remote-server-1-20261120.png)

A server has no browser for the login page. [The same docs](https://code.claude.com/docs/en/authentication) cover that case: when no browser opens, press `c` to copy the login URL, finish signing in on your laptop and paste the code at the `Paste code here if prompted` prompt. On Linux the credentials land in `~/.claude/.credentials.json` with mode 0600.

[`claude setup-token`](https://code.claude.com/docs/en/authentication) prints a one-year token for `CLAUDE_CODE_OAUTH_TOKEN`, which is fine for a cron job, but that token can only make model requests and can't start Remote Control. Pointing `ANTHROPIC_BASE_URL` at an LLM gateway or proxy, or running on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, leaves Remote Control unavailable too, per its [requirements](https://code.claude.com/docs/en/remote-control).

[Remote Control](https://code.claude.com/docs/en/remote-control) needs a Pro, Max, Ultra, Team or Enterprise plan, and on Team and Enterprise an Owner turns on the Remote Control toggle in Claude Code admin settings first. Logins also expire. On v2.1.318 or later, `claude auth status --text` prints a `Sign-in ends` line, and a Remote Control session that outlives its login disconnects until you sign in again, per the [authentication docs](https://code.claude.com/docs/en/authentication).

## What ends a remote Claude Code session

A remote Claude Code session started outside `tmux` or `screen` dies with its SSH connection, which is why [Anthropic's Remote Control docs](https://code.claude.com/docs/en/remote-control) say to start `claude` inside one.

![Five things that end a remote Claude Code session, each with its fix: an SSH drop, logind killing user processes, the Desktop sign-in lapsing, a network outage in server mode and an unanswered trust prompt](https://cdn.aldena.ai/images/blog/run-claude-code-on-remote-server-2-20261120.png)

- **The SSH connection drops.** `tmux new -s claude` starts a session that outlives the connection, `C-b d` detaches from it and `tmux attach -t claude` brings it back, per the [tmux getting-started guide](https://github.com/tmux/tmux/wiki/Getting-Started).
- **logind ends your processes at logout.** On machines with `KillUserProcesses=yes`, the [logind.conf manual](https://www.freedesktop.org/software/systemd/man/latest/logind.conf.html) warns that the setting breaks screen and tmux unless they move out of the session scope. [Anthropic's Desktop docs](https://code.claude.com/docs/en/desktop) suggest the fix I'd ask an admin for, an exemption for your user through `KillExcludeUsers`.
- **Desktop's sign-in lapses.** [Claude Desktop](https://code.claude.com/docs/en/desktop) keeps an SSH task running under a background helper after the connection closes, on Desktop v2.31226.0 or later. Desktop renews that task's sign-in only while it is running, connected and signed in, so a task can stop a few minutes after you close the laptop.
- **The network goes away.** In [server mode](https://code.claude.com/docs/en/remote-control), `claude remote-control` gives up after about 10 minutes offline and exits, while an interactive session keeps retrying until the network returns. `claude remote-control --continue` brings the last session back for about four hours after the server stopped.
- **Nobody answers the trust prompt.** In a directory you haven't trusted, [`claude remote-control`](https://code.claude.com/docs/en/remote-control) asks `Trust <directory>? [y/N]`, and with no terminal attached, as under a service manager, it exits with `Workspace not trusted`. Run it once by hand and answer `y`. The answer is never saved for your home directory, so start it from the project directory.

## Server mode runs many sessions on one machine

Server mode, started with [`claude remote-control`](https://code.claude.com/docs/en/remote-control) or its alias `claude rc`, keeps one Claude Code process waiting for connections and runs at most 32 sessions by default.

The [`--spawn` flag](https://code.claude.com/docs/en/remote-control) decides where those sessions write. The default, `same-dir`, puts every session in the current directory, where two of them can edit the same file. `--spawn worktree` gives each on-demand session its own git worktree, and pressing `w` while the server runs switches between the two modes. I'd start a shared server in worktree mode, for the same reason I give [each parallel agent its own checkout](https://aldena.ai/blog/run-multiple-claude-code-agents).

![One claude remote-control process on a server in two spawn modes: same-dir sessions sharing one checkout and colliding on a file, and worktree sessions each in their own git worktree](https://cdn.aldena.ai/images/blog/run-claude-code-on-remote-server-3-20261120.png)

The terminal prints a session URL, and the spacebar toggles a QR code that opens it in the Claude app on [iOS or Android](https://code.claude.com/docs/en/remote-control). A served session that crashes comes back when a connected device sends it a message, on v2.1.238 or later, with no server restart. Outside Remote Control, I'd add a [Notification hook that reaches your laptop over SSH](https://aldena.ai/blog/know-when-claude-code-needs-input).

## Claude Desktop's SSH environment installs Claude Code for you

Claude Desktop's SSH environment connects to a Linux, macOS or Windows machine and installs Claude Code there automatically on the first connection, per [the Desktop docs](https://code.claude.com/docs/en/desktop).

You add one from the environment selector under New environment, on the SSH tab, with a name, a `user@hostname` or a host from `~/.ssh/config`, a port (22 by default), an optional key and a worktree folder. [The Desktop docs](https://code.claude.com/docs/en/desktop) ask for an x86_64 or arm64 server with glibc 2.17 or musl, the SFTP subsystem and about 1 GB free in `~/.claude/remote/` on a filesystem that allows exec.

![Preflight for a Claude Desktop SSH environment: x86_64 or arm64, glibc 2.17 or musl, the SFTP subsystem, a prompt-free login, two SSH sessions at once and about 1 GB in \~/.claude/remote/ on a filesystem that allows exec](https://cdn.aldena.ai/images/blog/run-claude-code-on-remote-server-4-20261120.png)

[Desktop](https://code.claude.com/docs/en/desktop) logs in at least twice, so the SSH login has to be prompt-free. `ssh -o BatchMode=yes <host> true` tests that, since [ssh_config](https://man.openbsd.org/ssh_config) says BatchMode turns off password prompts and host key confirmation. A server with `MaxSessions 1` needs Desktop v3.1623.0 or later on macOS or Linux, or a higher limit, and the [sshd_config manual](https://man.openbsd.org/sshd_config) puts the default at 10. Proxy variables go in the `env` block of `~/.claude/settings.json` on the server, and [SSH sessions](https://code.claude.com/docs/en/desktop) read skills from the remote `~/.claude/skills/`.

## VS Code Remote-SSH and Tunnels put the editor on the server

VS Code's [Remote-SSH extension](https://code.visualstudio.com/docs/remote/ssh) installs VS Code Server on the remote host and runs commands and extensions there, so `claude` in the integrated terminal runs on the server.

[Remote-SSH](https://code.visualstudio.com/docs/remote/ssh) supports x86_64 Debian 8+, Ubuntu 16.04+ and CentOS/RHEL 7+ hosts, macOS 10.14+ hosts with Remote Login turned on, and glibc 2.17 or later, which leaves Alpine out. The editor needs 1 GB of RAM and recommends 2 GB, while Claude Code's [setup page](https://code.claude.com/docs/en/setup) asks for 4 GB or more, so I'd size the server for Claude Code and skip [the out-of-memory failures](https://aldena.ai/blog/claude-code-agents-running-out-of-memory) a smaller box invites.

[Microsoft's Remote-SSH page](https://code.visualstudio.com/docs/remote/ssh) doesn't say what happens to terminal processes when the SSH link drops, so I'd run `claude` inside tmux in that terminal too.

[VS Code Tunnels](https://code.visualstudio.com/docs/remote/tunnels) skip SSH entirely. `code tunnel` on the server makes outbound connections to an Azure service and sets up no network listener, both ends sign in with the same GitHub or Microsoft account, and `code tunnel service install` keeps the tunnel running. vscode.dev connects from a browser, which makes a Tunnel the workable answer for VS Code on an Android tablet.

## A security checklist for a Claude Code server

A Claude Code server keeps your Claude login in [`~/.claude/.credentials.json`](https://code.claude.com/docs/en/authentication) next to your repository, so lock it down before the first session.

![Which side opens each connection: SSH and Remote-SSH come in on port 22, while a VS Code Tunnel and Remote Control both connect out from the server, so neither needs an open inbound port](https://cdn.aldena.ai/images/blog/run-claude-code-on-remote-server-5-20261120.png)

- **Keys only.** `PasswordAuthentication` and `KbdInteractiveAuthentication` both default to `yes` in [sshd_config](https://man.openbsd.org/sshd_config), so set both to `no` once your key works.
- **Root stays out.** `PermitRootLogin` defaults to `prohibit-password` in [sshd_config](https://man.openbsd.org/sshd_config), which still accepts a key, so I'd set it to `no` and run Claude Code as an ordinary user.
- **No new inbound ports.** [Remote Control](https://code.claude.com/docs/en/remote-control) makes outbound HTTPS requests only, and a VS Code Tunnel sets up no listener, so SSH stays the only door in.
- **Trusted Devices on.** [Trusted Devices](https://code.claude.com/docs/en/remote-control) is off by default. Turned on, it asks for an enrolled device and a sign-in no more than 18 hours old before anyone views or steers a session.
- **Transcripts leave the box.** While [Remote Control](https://code.claude.com/docs/en/remote-control) is connected, Anthropic's servers store the transcript, tool activity included, and execution stays on the server. Zero Data Retention and HIPAA organizations can't enable Remote Control, and the `disableRemoteControl` setting turns it off.
- **Production secrets live elsewhere.** I'd keep deploy keys off the box entirely, the boundary I argued for in [how to sandbox coding agents](https://aldena.ai/blog/sandbox-coding-agents).

## How a team runs Claude Code in Aldena sandboxes

Aldena runs Claude Code inside each conversation's sandbox on a provider the team connects, such as Boat, so nobody keeps a tmux session alive on a shared box.

I built Aldena for the moment a second person needs the same agents. An owner or admin pastes the provider's API key once, on the team's providers page, and nobody manages a server after that. The [sandbox](https://aldena.ai/features/isolated-projects) starts with a conversation's first turn and sleeps 30 minutes after its last command. Its files stay until the conversation sits quiet for 7 days. The next turn wakes it, each new sandbox runs the project's setup script, and you never SSH into anything.

When an agent waits on a person, its chat lands in the [team inbox](https://aldena.ai/features/human-in-the-loop), grouped by project and oldest first, and any member can answer within the seven days questions and approvals wait. That queue is the part I'd miss most on a shared VPS.

![Aldena team Inbox with 3 chats that need a person, grouped by project: checkout-web with a Requirements agent question waiting 6 minutes and a Project Setup approval behind it, then status-page with 1 chat](https://cdn.aldena.ai/images/blog/claude-code-in-the-cloud-5-20261112.png)

Claude Code runs on each member's own Claude plan, or on the team's Anthropic key for anyone who hasn't signed in. A member signs in once, in any project's Settings → Runtimes. Each project then stays on its Claude Code version until an owner or admin [updates it there](https://aldena.ai/features/agents), and Aldena checks for new releases once a day. On your own server the [native installer](https://code.claude.com/docs/en/setup) updates itself, so the version moves whenever Anthropic ships one, and on a team I want a person making that call. Boat bills the machine time per second to the team's own account while the sandbox runs, and Aldena bills only the [team plan](https://aldena.ai/pricing).

For one developer with one VPS, tmux and Remote Control are less to run, and I'd stay there. Aldena makes sense once several people share the agents and whoever is free should answer them.

## The setup I'd start with on a fresh server

A fresh Linux server needs four steps for Claude Code: the native installer, a claude.ai login, a tmux session and server mode started inside it.

```bash
curl -fsSL https://claude.ai/install.sh | bash
claude
tmux new -s claude
claude remote-control --spawn worktree
```

Run `/login` in that first `claude` session, press `c` to copy the URL, and quit once you're signed in. Then start tmux and run server mode from the project directory. [Anthropic's setup page](https://code.claude.com/docs/en/setup) recommends the native installer and lists Ubuntu 20.04+, Debian 10+ and Alpine 3.19+ with 4 GB of RAM or more. Press `C-b d` to detach, close the laptop, and open the session from the Claude app.
