Last updated 13 October 2026
Run Claude Code on a remote linux server
Running Claude Code on remote Linux servers
Developing on a remote Linux server often involves working via SSH in a terminal environment where a browser is not available. You want to run Claude Code directly on that server to take advantage of its proximity to your source code and build tools. This setup avoids the latency of syncing files back and forth between a local machine and a production or development instance. You need a stable internet connection on the server and an Anthropic API key to begin the process. The remote server must have sufficient permissions for you to install global packages and execute scripts within your project directories.
Before installing anything, ensure your server has Node.js and npm installed. Claude Code runs as a command line tool and relies on these environments to execute. Check your permissions to ensure you can install global packages. If you are using a restricted server, you might need to adjust your path or use a version manager to keep the installation within your home directory. The stability of your remote connection is vital because the interactive nature of the tool requires constant feedback between the agent and your terminal session.
Installation and environment verification
To start the installation, run the standard npm install command for the Claude Code package globally. Once the process completes, you can verify the installation by typing the command claude in your terminal. This command should trigger the initial setup or show the help screen. If the command is not found, verify that your global npm bin directory is part of your system path variable. You can also run claude update at any time to ensure you have the latest improvements to the tool logic and tool set.
The first step after installation is running claude doctor to check the state of your environment. This command inspects your system for common issues like missing dependencies or network restrictions that might prevent the agent from reaching its backend. It provides a clear report on what works and what needs attention. If the doctor command reports a clean bill of health, your server is ready to handle coding tasks. This diagnostic tool is your first line of defense if you encounter issues with tool execution or network timeouts.
Authentication on headless systems
The primary challenge with a headless server is the authentication process which usually expects a browser. When you run the /login command inside a claude session, the tool generates a URL for you to visit. You must copy this URL and open it in a browser on your local machine. This allows you to sign in with your Anthropic account and authorize the remote instance. There is no need for the remote server to have a graphical user interface or a local browser installed for this process to succeed.
After you authorize the request in your local browser, the remote terminal should detect the successful login automatically. If the connection is blocked by a firewall, you might need to use SSH port forwarding to allow the session to communicate with the authentication server. Ensure that your server can reach the necessary API endpoints over HTTPS. Once authenticated, your credentials stay in your user profile on the server, so you do not need to repeat this step for every new session. You can use /logout if you need to clear your credentials or switch accounts.
Controlling the agent with settings and project files
Claude Code looks for configuration in several places starting with ~/.claude/settings.json for your user-wide preferences. You can define permission modes here to control how much autonomy the agent has. For a remote server where you might not be watching every second, setting the permissions to plan or default ensures the agent asks before making significant changes. You can change these modes during a session by pressing Shift+Tab to cycle through them. Other modes like acceptEdits or bypassPermissions allow for faster iteration by reducing the number of confirmation prompts.
Project-specific rules live in a file called CLAUDE.md at the root of your repository. This file is the primary way to tell the agent about your build commands, testing frameworks, and coding style. On a remote server, this is especially useful for documenting the specific paths to compilers or database sockets that the agent needs to use. If you have a large project, you can place additional CLAUDE.md files in subdirectories to provide localized context for specific modules. The agent reads these files to understand the environment it is operating in.
Managing session context and costs
When working on a remote server, you will often start a task, disconnect, and return later. The claude --continue command, or the -c flag, allows you to jump back into the most recent session in your current folder. If you need to find an older conversation, use claude --resume or the -r flag to see a list of previous sessions. This helps you maintain continuity even if your SSH connection drops or you move between different workstations. You can also use /resume from inside an active session to switch to a different historical thread.
Long conversations can fill up the context window and increase your costs. You can use the /cost and /usage commands to monitor your spend in real time. To keep the session efficient, run the /compact command. This summarizes the history of the conversation and clears out older data to make room for new instructions. If a session becomes too cluttered or the agent seems confused, the /clear command allows you to start fresh in the same directory without losing your project context. Managing your context window is essential for long-running remote development tasks.
Executing tasks with bash and filesystem tools
The agent uses a set of tools to interact with your server including Bash, Read, Edit, and Write. Because it runs directly on the remote machine, the Bash tool executes commands in the local shell environment. This means the agent can run your tests, compile your code, and check system logs just as you would. It uses Glob and Grep to find files and search for patterns across your codebase. This direct access to the shell makes the agent highly effective for troubleshooting environment-specific bugs that are hard to replicate locally.
When the agent needs to modify code, it uses the Edit and Write tools to update your files. It can also use TodoWrite to track tasks or NotebookEdit if you are working with data science files. If the agent needs to reach out to the internet for documentation, it uses WebFetch and WebSearch. You can see which tools are active by looking at the session status. If you need to stop an operation that is taking too long or seems to be heading in the wrong direction, pressing the Escape key once will interrupt the current tool execution.
Visualizing multiple remote sessions
Managing multiple Claude Code sessions across different projects on a remote server can become disorganized in a single terminal window. This is where adhdTerminal provides a significant advantage for macOS and Windows users. It allows you to run many Claude Code sessions side by side as tiles on a wall. Each tile represents a specific session on your server, labeled with a name, a color, and a number. This native app for macOS and Windows is made by MINDBALANCER OU and is not affiliated with Anthropic.
The app shows you at a glance whether a remote session is working, waiting for your input, or finished with its task. Since tiles reopen in the same place after a restart and resume their sessions, you do not have to manually reconnect and run the resume commands every time. This visual organization helps you track several complex tasks simultaneously without losing context. It costs 99 dollars once, and a free iPhone app mirrors the wall over an end to end encrypted link so you can answer a prompt or send the next task while away from your desk.
Extending functionality with MCP and subagents
For advanced workflows, you might need to connect Claude Code to other services or local databases on your server. The claude mcp command allows you to manage Model Context Protocol servers. These servers act as bridges to other tools that are not part of the standard set. You configure them in a .mcp.json file in your project or home directory. Inside a session, you can use the /mcp command to check the status of these connections or refresh the list of available tools provided by your MCP servers.
You can also define custom subagents in the .claude/agents folder using markdown files. These subagents can be specialized for specific parts of your remote infrastructure, such as database optimization or log analysis. You can see which agents are available by using the /agents command. If you find yourself repeating the same complex instructions, you can save them as custom slash commands in markdown files within the .claude/commands directory. This allows you to create a tailored command set for your specific server management tasks.
Enhancing security and terminal interaction
Security is a priority when running an autonomous agent on a remote server. Claude Code respects your .gitignore files to ensure it does not read or modify sensitive files like environment variables or private keys. You can further restrict its access by editing the permissions section in your settings.json file. This allows you to allow or deny specific tools per project. For example, you might allow the Read tool but require manual approval for the Bash or Write tools. Use /permissions to see the current state of these rules.
To improve your experience in the remote terminal, use the /terminal-setup command. This helps configure your shell to work better with the interactive elements of the agent. You can also use Ctrl+R to search through your shell history if you need to find a specific command you previously used with the agent. If you ever need to go back to a previous point in a conversation, pressing the Escape key twice will offer a list of earlier messages that you can revert to. This undo functionality is vital when an agent makes a change that has unexpected side effects on your server.
Questions people ask
How do I handle a lost SSH connection while the agent is working?
You can reconnect to your server and use the claude --continue or -c command in the same directory. This will reload the most recent session and show you the current status of the task. If the agent was in the middle of a long process, it should pick up where it left off once the terminal session is restored.
Can I run Claude Code on a server without an internet connection?
No, the tool requires a connection to the Anthropic API to function. While it interacts with your local files and shell, the intelligence that drives the agent is hosted remotely. You must ensure your server can reach the necessary HTTPS endpoints or use a proxy configured in your environment variables.
What happens if the agent tries to run a command that requires sudo?
The agent will attempt to run the command via the Bash tool. If your shell requires a password for sudo, the process will likely hang or fail unless you have configured passwordless sudo for those specific commands. It is safer to give the agent the necessary user-level permissions rather than granting it full root access to your server.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.