Last updated 13 October 2026
Run Claude Code on a remote server via SSH
The challenge of remote development
You are working on a cloud instance or a remote staging server and you need the intelligence of Claude Code exactly where the code lives. Running the agent locally and syncing files back and forth creates friction. It introduces lag into your development cycle and often leads to version conflicts. You want to execute the claude command directly in your SSH session so the agent can see the environment, run the local build tools, and interact with the filesystem without a middle layer. This setup allows the agent to run tests and debug issues in the same environment where the bugs occur.
Running a stateful agent over SSH is hard because of connection stability. If your terminal session drops, the process usually dies with it. This can leave the agent in the middle of a file write or a complex bash command, which might corrupt your work. You need a setup that survives a network flicker and allows you to resume your work exactly where you left it. You also need a way to authorize the agent on a machine that does not have a web browser.
Preparing the Linux environment
Before you install the agent, ensure your remote Linux machine has a modern version of Node.js and npm. Most cloud providers offer minimal images, so you might need to install these dependencies manually using your system package manager. Once your environment is ready, you can install the CLI globally. This makes the claude command available across your entire system for any user with the correct permissions. Check your path settings to ensure that globally installed npm binaries are accessible from your shell.
After installation, run claude doctor to verify that the environment meets all requirements. This command checks for necessary dependencies and ensures the agent can communicate with the necessary backend services. It also looks for common configuration issues that might interfere with the agent's ability to execute tools. If the doctor command reports missing components, address those specific system packages before you attempt to log in or run a full session.
Handling authentication over a remote connection
Authentication requires a browser, which is not available on a headless Linux server. When you run /login inside a session or start the agent for the first time, it provides a URL and a unique code. You must copy this URL into a browser on your local machine. Complete the Anthropic sign in process there and enter the code provided by the remote terminal. This links your remote session to your account without needing a graphical interface on the server itself.
Once the server receives the authorization token, it stores your credentials in the local configuration files. Your user settings are kept in a hidden folder in your home directory at ~/.claude/settings.json. You do not need to repeat this login process every time you connect via SSH. The token persists across sessions until you explicitly run /logout. If you need to use a different account, you can run /logout and then /login again to refresh the credentials.
Ensuring session persistence with terminal multiplexers
Relying on a raw SSH connection for a long coding session is risky. If your internet connection drops, the agent might be interrupted while executing a Bash command or using the Write tool. To prevent this, always run your sessions inside a multiplexer like tmux or screen. These tools keep the process running on the server even if your SSH client disconnects. This is the most reliable way to handle long running tasks that require multiple steps from the agent.
When you reconnect to your server, you simply reattach to the existing multiplexer session to find the agent exactly where you left it. If you forgot to use a multiplexer and the session closed, you can use claude --continue or claude -c to carry on the most recent session in that directory. For older work, claude --resume or claude -r allows you to pick from a list of previous conversations stored on the server. This ensures that the context of your previous work is not lost due to a bad connection.
Configuring project instructions on the remote host
The agent relies on CLAUDE.md files to understand your project structure and coding standards. On a remote server, you should place a CLAUDE.md file in the root of your repository to guide the agent. This file should define how to run tests, how to build the project, and which naming conventions to follow. If you are working on a specific module, you can place an additional CLAUDE.md in that subdirectory to provide more granular context for that part of the tree.
You can also control the agent's behavior through .claude/settings.json within the project folder. For instance, if you want the agent to automatically accept file edits without asking for permission every time, you can configure the permissions section in this file. This is useful on remote servers where you might want a more hands-off approach. You can toggle between permission modes like default, acceptEdits, plan, and bypassPermissions by using Shift+Tab within the interactive session.
Managing multiple sessions and monitoring
When you manage several remote servers or multiple projects on a single large instance, keeping track of every agent's state becomes difficult. This is where adhdTerminal provides an answer for your workflow. It allows you to run many Claude Code sessions side by side on your desktop. Each session appears as a tile on a wall. You can have one tile connected to your local environment and another tile dedicated to your remote SSH session, allowing you to monitor both without switching terminal tabs.
The adhdTerminal app shows you whether each session is working, waiting for your input, or idle. Because the tiles show the last few exchanges of the conversation, you can see the progress of a remote build or a complex refactor at a glance. If you need to step away from your desk, the free iPhone app mirrors your wall of tiles over an encrypted link. You can check if the remote agent finished its task or even send the next task while you are away from your computer.
Optimizing context and cost on remote instances
Remote sessions can quickly consume a large context window, especially if the agent reads many large log files or source files from the server. Use the /compact command to summarize the conversation so far and free up space in the context window. This prevents the session from becoming sluggish and helps manage the tokens used by the agent. You can monitor your spend and token usage at any time by running /cost or /usage within the session.
If the conversation becomes too cluttered or the agent loses focus, use the /clear command to start a fresh session in the same folder. This wipes the current context but keeps you in the same working directory. Remember that the agent can use tools like Grep and Glob to find information on the remote filesystem. This is often more efficient than having it read every file individually. Using these tools effectively keeps your context window clean and your costs lower.
Customizing the remote experience with hooks and subagents
You can extend the functionality of the agent on your server by using custom slash commands and subagents. Custom commands are markdown files in the .claude/commands directory. For example, you could create a command that triggers a deployment script or runs a specific suite of integration tests. Subagents, defined in .claude/agents, allow you to create specialized personas for different tasks like security auditing or documentation work on the remote host.
Hook events provide another layer of automation. You can configure events like SessionStart or PostToolUse to trigger specific actions. For instance, you might set a hook to notify an external monitoring service whenever the agent completes a task. These configurations are stored in the .claude directory and ensure that your remote environment is tailored to your specific development needs. This level of customization makes the agent feel like a native part of your remote toolchain.
Security and terminal setup
Security is vital when giving an agent Bash access to a remote server. Always review the tool outputs, especially when the agent uses the Bash or Write tools. You can use the /review command to look over the changes the agent has proposed before they are finalized. If the agent starts a process that seems to be hanging or behaving incorrectly, press the Escape key once to interrupt it. Pressing Escape twice allows you to go back to earlier messages if you need to revert a specific line of reasoning.
To ensure the terminal interface renders correctly over SSH, you may need to run /terminal-setup. This command helps configure the terminal environment to handle the rich interactive elements of the agent. If you encounter issues with colors or character rendering, the /doctor command can also help identify if your remote terminal emulator is missing required features. Proper setup ensures that you can see the color-coded status and the clear output of the agent's tools without visual glitches.
Questions people ask
Can I run Claude Code on a server without a public IP?
Yes, as long as the server has outbound internet access to reach the Anthropic API, you can run the agent. You connect to the server via SSH as you normally would and then launch the agent from the command line. The authentication process only requires your local machine to have a browser to verify the login code.
What happens if my SSH session times out during a long task?
If you are not using a multiplexer like tmux, the agent process will likely terminate when the SSH connection drops. You can attempt to resume your progress by reconnecting and running claude --continue. For better safety, always use a multiplexer to keep the session active regardless of your local connection status.
How do I handle file permissions for the agent on Linux?
The agent operates with the permissions of the user who started the session. If it needs to edit files owned by another user, you must adjust your filesystem permissions or run the agent with appropriate privileges. You can also manage tool-specific permissions in your .claude/settings.json file to restrict or allow specific actions.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.