How to run AI coding agents on remote servers via SSH

AI coding agents like Claude Code, Codex CLI, and Gemini CLI are designed for your local terminal. They read your project files, edit code, run tests, and commit changes. But what if your development environment lives on a remote server? Many teams develop on shared dev boxes, cloud VMs, or staging servers that mirror production. If you want to run AI coding agents on a remote server, the setup and workflow are different from local development.

Why run AI coding agents on a remote server?

Your code runs on a server in production. It should run on the same type of server during development. When an AI coding agent runs on your remote dev box, it has access to the same environment (dependencies, databases, networking, file paths) that your code uses in production. The agent can compile, test, and debug in the actual runtime, eliminating the class of bugs that only reproduce on the server.

There are practical benefits beyond environment parity:

GPU-equipped dev servers can run local language models for agents that support BYO models, removing API dependency and per-token cost
Shared team dev boxes let multiple developers use a single agent setup with consistent tooling and dependencies
Sensitive code never leaves your infrastructure when you run the agent on your own server with a local or self-hosted model
The agent can interact with real services (databases, message queues, storage) that are impractical to run locally

The tradeoff is complexity. SSH adds latency, session management, and authentication concerns. An agent that works seamlessly on your laptop may behave differently over a remote connection. This guide covers which agents work over SSH, how to configure your connection for long-running sessions, and what security considerations change when an AI agent runs on a remote machine.

Which AI coding agents work over SSH?

The key requirement is that the agent must run entirely in a terminal with no GUI dependencies. All of the major AI coding CLI tools meet this requirement, but they differ in how they handle authentication, API keys, and session persistence over remote connections.

Claude Code

Claude Code runs as a terminal process with no GUI dependency. It works over SSH with no modification. Launch it with `claude` in your project directory on the remote server. It reads files, edits code, runs shell commands, and commits to git through the SSH connection. Requires an Anthropic API key or a Max subscription. The agent process stays alive as long as the SSH session is open, so tmux or screen is recommended for long-running refactoring tasks that involve multiple file edits across the codebase.

Codex CLI

OpenAI’s Codex CLI ships as a standalone binary (rewritten from TypeScript to Rust in mid-2026). It operates entirely through the terminal and works over SSH with no special configuration. Codex CLI includes a sandboxed execution environment that runs commands in isolated containers. On a remote server, this sandbox requires Docker to be available. Without Docker, commands execute directly on the host, acceptable for single-user development boxes but not recommended for shared environments.

Gemini CLI

Google’s Gemini CLI is an npm package that runs anywhere Node.js 20+ is available. It offers 1,000 free requests per day with Google OAuth, making it the most accessible option for trying AI coding agents on a remote server without committing to a paid plan. Authentication tokens are stored locally on the server, so you authenticate once and the agent reuses the token on subsequent SSH sessions. The generous free tier and million-token context window make it suitable for large-codebase analysis tasks over remote connections.

Aider and open-source alternatives

Aider is an open-source AI pair programmer that works with any LLM, including Claude, GPT-4o, DeepSeek, Gemini, and local models via Ollama. It runs in the terminal, works over SSH without modification, and has the best git integration of any AI coding tool: every change gets a clean commit that you can review or revert. For teams that need to keep all data on their own infrastructure, Aider paired with a local model via Ollama on a GPU-equipped dev server is the most private option. Other open-source alternatives that work over SSH include Cline, OpenCode, and Goose, all terminal-native and SSH-compatible.

SSH configuration for remote AI coding

A default SSH configuration works for interactive use, but AI coding agents introduce longer sessions and different traffic patterns. An agent may spend 30 seconds to several minutes processing without producing output. Without tuning, network equipment may interpret this as an idle connection and drop it, killing the agent mid-task.

Session persistence with tmux

The single most important tool for running AI agents on remote servers is a terminal multiplexer. When your SSH connection drops (and it will, eventually), the agent process running inside tmux continues uninterrupted on the server. You reconnect, reattach, and see the output as if nothing happened.

tmux new-session -s ai-coding
# Inside tmux, start your agent:
claude

The agent keeps running even if you close your laptop, switch networks, or your SSH connection times out. Detach with Ctrl-B d and reattach later with `tmux attach -t ai-coding`. This is essential for multi-step agent workflows that take minutes to complete.

SSH keepalive and timeout tuning

Configure keepalive on the client side to prevent network equipment from dropping the connection during agent thinking periods.

Host *.dev.internal
  ServerAliveInterval 60
  ServerAliveCountMax 30
  TCPKeepAlive yes

ServerAliveInterval sends a keepalive packet every 60 seconds. ServerAliveCountMax allows 30 missed replies (30 minutes) before disconnecting. This keeps the connection open through long agent processing periods and brief network interruptions. On the server side, ensure sshd_config has matching values: ClientAliveInterval 60 and ClientAliveCountMax 30.

Security: what changes when an AI agent runs on your server

Running an AI coding agent on a remote server changes the threat model compared to local use. The agent has filesystem access – it reads files, executes commands, and can modify configuration. On a dedicated development server, this is intentional. But the boundaries matter.

The same risks that apply locally are amplified on a shared or production-adjacent server:

The agent reads every file its user has access to. Ensure your project directory does not contain .env files with production secrets, unencrypted SSH keys, or database credentials
Agent-generated commands run with your user’s permissions. A compromised prompt could delete files, exfiltrate data, or modify system configuration
API keys for the AI service (Anthropic, OpenAI, Google) are stored on the remote server. Protect them at the same level as production credentials using restricted file permissions and never shared directories
Git operations use your SSH agent forwarding. Consider using a deploy key with read-only scope rather than forwarding your personal SSH agent

The security model for AI assistants in SSH sessions is covered in detail in the guide on SSH managers with AI assistants. The same principles apply to AI coding agents: never grant production filesystem access, always review generated commands before execution, and treat the agent like any other tool that runs commands on your server.

A practical rule: run AI coding agents in a container or a dedicated user account with filesystem access scoped to the project directory. This limits what a misbehaving or compromised agent can affect.

Performance: API-based agents vs local models

AI coding agents fall into two categories based on where the AI computation happens. The choice affects latency, cost, and infrastructure requirements.

API-based agents (Claude Code, Codex CLI, Gemini CLI):

Require internet access from the remote server to reach the AI provider’s API
Minimal CPU and RAM usage on the server. All inference happens in the cloud
Latency depends on network round-trip time between your server and the API endpoint. Expect 500ms-3s per response from most regions
Pay-per-token pricing scales with usage. Cost is predictable and no upfront hardware investment is needed

Local model agents (Aider + Ollama, OpenCode with local models):

No internet dependency after the initial model download. Works in air-gapped environments
Require GPU hardware (NVIDIA with 12GB+ VRAM recommended) for acceptable throughput on modern coding models
Zero per-token cost. The hardware is a fixed expense that amortizes across all usage
Strongest privacy guarantee: code and prompts never leave the server

For most teams, API-based agents are the practical choice for remote servers. The server needs only a stable internet connection and a terminal. Local models make sense when you have GPU hardware available on the remote server, need to process sensitive code that cannot be sent to an external API, or have high enough usage volume that per-token costs exceed hardware amortization.

Managing multiple remote AI coding environments

If you manage more than one remote development server, SSH config organization becomes the difference between a smooth workflow and constant context-switching friction. Each server needs a unique host alias, the correct identity file, and agent configuration that matches its role.

Host dev-api
  HostName 10.0.1.50
  User developer
  IdentityFile ~/.ssh/dev_ed25519
  ServerAliveInterval 60

Host dev-web
  HostName 10.0.1.51
  User developer
  IdentityFile ~/.ssh/dev_ed25519
  ServerAliveInterval 60

Host gpu-box
  HostName 203.0.113.80
  User ml-user
  IdentityFile ~/.ssh/gpu_ed25519
  ForwardAgent yes

Each host alias serves as a single target for both SSH access and agent configuration. When you switch projects, you SSH to the correct alias and start your agent inside a tmux session, eliminating manual hostname, port, or key lookups. The question of how to keep credentials synchronized across these environments is addressed in the guide on managing SSH credentials across multiple devices, which covers encryption models and sync strategies for multi-machine setups.

The hybrid workflow: local editing, remote execution

The most effective pattern for remote AI coding combines local editing with remote agent execution. Edit code in your local editor where latency is zero and the UI is familiar. Run AI agent commands on the remote server where the actual environment lives.

The workflow:

Mount your project locally via SSHFS, VS Code Remote, or rsync so files stay on the server while editing happens locally
Open a persistent tmux session on the remote server for the AI agent. Keep it running in its own window
Edit files locally with your preferred editor, then invoke the agent on the remote server for tasks like refactoring, test generation, and debugging against real dependencies
Use separate tmux windows for the agent session, a shell for ad-hoc commands, and a log tail for real-time feedback

This pattern gives you the UI responsiveness of local editing with the accuracy of AI execution in the actual runtime environment. The agent works with real files, real dependencies, and real data, not a local approximation that may behave differently in production.

Termique supports this workflow with credential management across multiple hosts, session persistence, and an AI assistant that knows which server you are connected to and can suggest context-aware commands. The credential vault uses end-to-end encryption so your SSH keys never leave your devices in plaintext.

Related articles