# Run Claude Code on a remote server: a practical guide

URL: https://agentvera.dev/en/blog/claude-code-remote-server/ · Published: 2026-10-22

How to run Claude Code on a remote server or VPS: SSH and tmux, dev containers, cloud VMs, signing in on a headless machine, security, and AgentVera’s Runner.

**In short:**

- Running Claude Code on a server means installing it there, signing in once and starting it in a session that survives disconnects, usually tmux over SSH.
- On a headless machine you can open the login link on your own computer, or set a one-year token from claude setup-token as CLAUDE_CODE_OAUTH_TOKEN.
- AgentVera runs agents on your server through Runner (Pro and Team, outbound connection only) or a saved SSH server, and can isolate local agents in Docker.

To run Claude Code on a remote server, install it on the server, sign in once, and start it inside a terminal session that survives your disconnect, usually tmux over SSH. That’s the whole idea. The rest is choosing where the server lives, how the agent signs in without a browser, and how much of your world the agent can reach from there.

This post explains why people move agents to a VPS, compares the common setups, covers signing in on a headless machine and basic security, and then shows how AgentVera handles remote agents with Runner, SSH agents and Docker.

## Why run a coding agent on a remote server

A laptop is a poor home for long agent runs. It sleeps, it loses Wi-Fi, and you close the lid to go home. A server doesn’t.

Common reasons to move agents off your machine:

- **Long tasks.** A migration, a big refactor or a test suite that takes an hour shouldn’t stop because your laptop went to sleep.
- **The code already lives there.** Some projects only build on Linux, need a GPU, or need a database that only exists on that network.
- **Isolation.** An agent on a disposable VM can’t touch your personal files, SSH keys or browser sessions.
- **Access from anywhere.** You start a task at your desk and check on it from another computer or your phone.
- **Several agents at once.** A server with more cores and memory runs more agents in parallel than a laptop.

The trade-off is setup and responsibility. A server you control is a server you have to secure.

## The options at a glance

| Setup | Survives disconnect | Isolation | Effort | Good for |
| --- | --- | --- | --- | --- |
| SSH + tmux on a VPS | Yes | Separate machine | Low | Most people, one or two projects |
| Dev container (local or remote) | While the container runs | Container | Medium | Reproducible environments, teams |
| Cloud VM per task | Yes | Full VM | Medium to high | Throwaway environments, risky work |
| Agent in a container on your machine | No, stops with the agent | Container | Low | Isolation without a server |

### SSH and tmux

This is the simplest setup and it works for any CLI agent. On the server:

```bash
npm install -g @anthropic-ai/claude-code
tmux new -s agent
cd ~/projects/my-app
claude
```

Detach with `Ctrl-b d` and close SSH. The agent keeps working. Later, `ssh` back in and run `tmux attach -t agent`. If you prefer screen or zellij, the idea is the same: the session belongs to the server, not to your SSH connection.

What you give up: no file tree, no diff view, and switching between several agents means juggling tmux windows.

### Dev containers

A dev container describes the environment in a file (`devcontainer.json` plus a Dockerfile), so every machine gets the same tools. You can run it locally or on a remote Docker host. The agent runs inside the container and sees only what you mount into it.

The catch is that the agent’s login has to exist inside the container too, and a container that is rebuilt loses anything you didn’t persist.

### Cloud VMs

A fresh VM per task gives the cleanest isolation: if the agent wrecks something, you delete the machine. It costs more setup, and you need a way to get the code in and the result out, usually a git branch the agent pushes.

## Signing in on a headless machine

Coding agents normally sign in through a browser. A server has none, so you need one of these routes.

### Claude Code

- **Browser on your computer.** Run `claude` on the server. It shows a login link; open it on your own machine. If the browser can’t reach the server’s local callback, Claude Code shows a code to paste at the “Paste code here if prompted” prompt in the terminal.
- **Long-lived token.** `claude setup-token` creates a one-year OAuth token for a Pro, Max, Team or Enterprise subscription. It isn’t saved anywhere for you: set it on the server as `CLAUDE_CODE_OAUTH_TOKEN`. This token only covers model requests.
- **API key.** Set `ANTHROPIC_API_KEY` if you pay per use through the API.

On Linux, Claude Code stores its credentials in `~/.claude/.credentials.json` with file mode 0600. On macOS they go to the Keychain, and over SSH it falls back to that file if the Keychain is locked.

### Codex

- **Device code.** `codex login --device-auth` gives you a code to enter in a browser elsewhere. It’s in beta and has to be enabled in your ChatGPT security settings (or by your workspace admin).
- **API key.** `printenv OPENAI_API_KEY | codex login --with-api-key`.
- **Fallbacks.** Copy `~/.codex/auth.json` from a machine where you are signed in, or forward the login port with `ssh -L 1455:localhost:1455` and sign in normally.

Whichever route you choose, a credential file on a server is as sensitive as a password. Anyone who can read it can use your subscription.

## Security on the server

An agent on a server runs commands with the rights of the user it runs as. Plan for that.

- **Use a separate user.** Don’t run agents as root. A dedicated user with its own home folder limits what a bad command can reach.
- **Keep production secrets off the box.** If the agent doesn’t need the production database password, it shouldn’t be in an `.env` file on that server.
- **Close inbound ports.** SSH with keys only, no password login, and no exposed dev servers you forgot about.
- **Work on branches.** Let the agent push to a branch, not to main. Git worktrees let several agents work on the same repo without stepping on each other.
- **Watch for long-lived tokens.** A one-year token on a shared server is a one-year risk. Rotate it if the machine is shared or retired.
- **Expect logins to expire.** For unattended runs, check that the session is still signed in before you leave it alone for the night.

## How AgentVera runs agents on a server

[AgentVera](/en/ "AgentVera") is a desktop app that runs coding-agent CLIs side by side in real terminals with your own logins. It gives you three ways to move agents off your machine.

### Runner: your own server, opened from anywhere

[Runner](/en/runner/ "AgentVera Runner") is a small service you install on your own Linux or macOS server, or a Mac. It runs Claude Code, Codex, Gemini CLI, opencode and plain terminal sessions in real terminals. Sessions keep running when you disconnect, and you reconnect from the browser or the desktop app.

Setup in short:

1. Open app.agentvera.dev/runners and add a runner. You get an 8-character pairing code that is valid for 10 minutes.
2. On the server, run the install command with that code:

```bash
curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD
```

3. Install and sign in to the CLI on the server, for example `npm install -g @anthropic-ai/claude-code` and then `claude login`.

Runner needs Node.js 20 or newer and curl or wget. On Linux it installs a systemd user service; run `sudo loginctl enable-linger $USER` once so it keeps running when you log out. To keep agents inside certain folders, run `agentvera-runner roots ~/projects`. Without roots, agents work in your home folder.

On security, Runner only makes an outbound connection to app.agentvera.dev on port 443, so you don’t open a port on the server. Traffic is relayed over TLS, and the AgentVera server doesn’t interpret, log or store it. Your code stays on your server, and only active members of your organization can connect. The Runner page also shows the server’s CPU, memory and disk.

Runner is on the Pro and Team plans.

### Agents over SSH: no extra service

If you already have a server in AgentVera’s SSH list, you don’t need Runner. In the new agent dialog, set **Runs on** to that saved server instead of **This computer**, and choose the **Folder on the server**. The agent then runs on the server with the server’s own CLI login. As the dialog says, the CLI must be installed and signed in on the server, or you can sign in from the agent’s terminal on first launch. Your local accounts, MCP and browser settings aren’t used on the server.

If tmux is installed on the server, AgentVera starts the agent inside a tmux session. That session outlives the SSH connection, and the next connection, from any computer, attaches to it again. Quitting the app doesn’t stop it; stopping or closing the agent does.

The SSH feature itself is free: saved servers, an encrypted vault for credentials, SFTP and ProxyJump. Details are on the [SSH and SFTP](/en/features/ssh-and-sftp/ "SSH and SFTP") page.

### Agents in a Docker container: isolation without a server

Sometimes you don’t need a server, you need a wall. For a local Claude Code or Codex agent, turn on **Run in a Docker container** in the agent dialog. The agent sees only the project folder; other files, programs and SSH keys on your computer stay closed to it. You can set CPU and memory limits.

AgentVera builds its own image (Node 22, git, ripgrep, Claude Code and Codex) on first use, or you can use your own image as long as it has the `claude` or `codex` command. The container is removed when the agent stops. It needs Docker Desktop, Colima or OrbStack. This is free; see [agents in Docker](/en/features/agents-in-docker/ "Agents in Docker").

### Which one to pick

| You want | Use |
| --- | --- |
| Agents that run for hours on your server, opened from the browser | Runner (Pro and Team) |
| An agent on a server you already reach over SSH | Runs on → saved SSH server |
| Isolation on your own machine | Run in a Docker container |
| A quick look at a running agent from your phone | The [mobile app](/en/blog/claude-code-mobile-app/ "Claude Code mobile app") or [Telegram](/en/blog/control-claude-code-from-telegram/ "Control Claude Code from Telegram") |

## Common mistakes

- Starting the agent directly in the SSH session and losing it when the connection drops.
- Running the agent as root “just for now”.
- Copying a whole `.env` with production keys to the server.
- Leaving a long-lived token on a shared machine and forgetting about it.
- Letting several agents work in the same folder instead of separate branches or worktrees.

## Checklist

- [ ] The CLI is installed and signed in on the server.
- [ ] The agent runs inside tmux, Runner or another session that survives a disconnect.
- [ ] It runs as a non-root user, limited to the project folders.
- [ ] No production secrets sit on the server unless the task needs them.
- [ ] Inbound ports are closed except SSH with keys.
- [ ] Each agent works on its own branch or worktree.

## Wrapping up

Running Claude Code on a remote server comes down to three things: a session that outlives your connection, a login that works without a browser, and a server that only holds what the agent needs. SSH and tmux get you there in five minutes. If you want to start agents from anywhere, see their files and diffs, and keep several running at once, AgentVera’s Runner and SSH agents do the same job with less juggling.

Read more:

- [Git worktree for parallel agents](/en/blog/git-worktree-parallel-agents/ "Git worktree for parallel agents")
- [Build a crypto trading bot with AI](/en/blog/build-crypto-trading-bot-with-ai/ "Build a crypto trading bot with AI")
- [Run multiple Claude Code agents](/en/blog/run-multiple-claude-code-agents/ "Run multiple Claude Code agents")
- [Docker](/en/features/docker/ "Docker")
- [What is a coding agent?](/en/glossary/coding-agent/ "Coding agent")

To try AgentVera, start at the [home page](/en/ "AgentVera").

## Frequently asked questions

**Can I run Claude Code on a remote server?** Yes. Install it on the server with npm, sign in once, and start it inside tmux over SSH. The session keeps running after you disconnect, and you reattach later from any computer.

**How do I sign in to Claude Code on a server without a browser?** Run claude on the server and open the login link on your own computer. If the browser can’t reach the server, paste the code it shows into the terminal. For unattended machines, claude setup-token creates a long-lived token you set as CLAUDE_CODE_OAUTH_TOKEN.

**Is it safe to run a coding agent on a VPS?** It can be, if the server only holds what the agent needs. Use a separate user, keep production secrets off the box, close inbound ports you don’t need, and treat credential files like ~/.claude/.credentials.json and ~/.codex/auth.json as passwords.

**What is AgentVera Runner?** Runner is a small service you install on your own Linux or macOS server. It runs Claude Code, Codex, Gemini CLI, opencode and plain terminals in real terminals that keep running after you disconnect. It connects outbound only, so no port is opened. It is on the Pro and Team plans.

**Can AgentVera run an agent on my server without Runner?** Yes. In the agent dialog, set “Runs on” to a saved SSH server and pick a folder on the server. The agent uses the server’s own CLI login. If tmux is installed there, the session survives a dropped connection.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/