Learn

Running Claude Code on a remote machine

People move Claude Code off the laptop so it sits next to the code and the services it talks to, and so a long task survives a closed lid. The habit that makes it work is a persistent terminal session.

Short answer

Claude Code runs anywhere you can install it and open a terminal. Connect over SSH and start it in the project directory there. What makes it comfortable is a terminal multiplexer such as tmux, which keeps the session alive on the remote machine when you disconnect. You start a task, shut the lid, and pick it up later from somewhere else, while the remote box keeps working.

Why people move it off the laptop

The first reason is proximity. The agent is most useful next to the code and the services the code talks to. If the database, the queue and two internal APIs already run on one box, a session there reads the logs, runs a migration and calls the endpoint it just changed with nothing tunnelled in between.

The second is time. A long refactor does not fit into the hour before you close the laptop. A process on a machine that stays on keeps going while you are on a train.

The third is that the machine you develop against is often not the one you sit in front of: a home lab box, a VM with the right versions of things, or a server with more memory than your laptop.

A session that survives a closed lid

When you connect to a remote machine and start a program, that program belongs to the connection. Drop the connection and the program usually goes with it. A terminal multiplexer breaks that link. It runs terminals on the remote machine that keep going with nobody attached, and you attach and detach from them at will.

The habit is one line long: start tmux on the remote machine first, then start Claude Code inside it. When you are done for now you detach, and the work continues on the remote box without you watching it. tmux protects the session from your connection going away. It cannot protect it from the machine shutting down or the process exiting.

Name sessions so you recognise them a day later. A shape that works well: one window running the agent, one tailing the application’s logs, one plain shell for looking around.

Expect one wrinkle: a permission prompt with nobody there to answer it simply waits, so an unattended session often comes back sitting on a question. Decide up front how much you will approve in that environment.

Start and reconnect to a session

With Claude Code and tmux installed on the remote machine, substitute your own host and path.

ssh user@dev-host
cd /path/to/project
tmux new -s app-work
claude

Press Ctrl-b, then d to detach. Later, reconnect with SSH and run tmux attach -t app-work. A session waiting for approval will stay paused until you respond.

What remote control actually means here

Reconnecting is: connect over SSH, attach to the session. You get the scrollback, the running task and the prompt as you left them. There is no control daemon, and the computer you sit down at needs nothing but an SSH client and access to the machine.

Because the thing you attach to is a terminal, Claude Code behaves as it does locally: same repository, same project instruction file, same permission prompts, same review at the end. Get those habits right first: Claude Code in a terminal workflow covers them.

Settle these before it gets a machine of its own

An agent on a box you are not watching raises questions that never come up on your laptop. Answer them once, when you set the machine up.

Which repository and which branch Give the session its own clone and a branch per task. Mixing its work into the copy you use yourself makes it hard to tell which change came from where.
What credentials live in that environment A session inherits whatever is on the box: deploy keys, database URLs, cloud tokens. An unattended session is the wrong place for a credential you would not hand to someone else. If it needs a secret, scope that secret to this environment.
Who else uses the machine On a shared home lab or team server, commands run as the user you connect as, and restarting a service affects everyone. Give the agent its own machine or VM, or agree what it may touch.
How you will see what it did Hours of scrollback is not a report. Have it commit as it goes, after changes it has checked, so you come back to a branch with a history you can read. Then look at git status for anything it left uncommitted.

Checking that the change actually works

A change that runs on the remote box has only been proven there, with your versions, your data and your configuration. The check that matters is running it somewhere closer to production, which usually means pushing the branch and letting something build it. On AppHaven a pushed branch is built and served at its own preview URL with its own database, covered in How to deploy an AI-built app.

Read the diff on the branch before you trust the summary, the same way you would locally.

Common questions

What happens to a long task if my connection drops?

If you started it directly over the connection, it usually dies with the connection. If you started it inside a terminal multiplexer such as tmux or screen, it keeps running on the remote machine and you attach to the same session when you reconnect.

Is it easier to run it on Windows or on a remote Linux machine?

Both work. It runs on Windows through PowerShell or WSL, and it runs on a Linux server, home lab box or VM that you connect to. If your project already expects a Linux environment, a remote machine saves you from reproducing that setup locally.

Run it on AppHaven.

Run your business app with a managed database, private access and production backups.

Try it with your app Read the docs