claude-code - 💡(How to fix) Fix [BUG] macOS Desktop client SSH remote connection floods server with SSH sessions, triggers MaxStartups throttling, never launches remote server [2 comments, 2 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

The Claude Desktop app (macOS) fails to establish SSH remote sessions to a Linux VPS. The connection hangs on "Connecting..." indefinitely, then fails with a generic "try again" prompt. No actionable error is shown in the client UI.

Root cause investigation revealed two compounding issues:

1. SSH CONNECTION FLOODING: The Desktop client opens dozens of simultaneous SSH sessions to the remote server within seconds during connection setup. This triggers sshd's MaxStartups throttling, which drops connections — including the critical one needed to launch the remote server. The remote-server.log remains completely empty because the server binary never gets a chance to start.

2. files.list RPC FLOODING: When connections do get through (after raising MaxStartups), the remote server's RPC handler issues hundreds of sequential files.list calls to enumerate the project directory tree before spawning ccd-cli. A project with ~25,000 files and ~990 directories generates 160+ files.list calls per connection phase, taking 5+ seconds per burst. Neither .gitignore, .claude/settings.json ignorePatterns, nor .claudeignore reduce this enumeration.

These issues did not occur with the previous Desktop client version. Terminal SSH to the same server works perfectly, and Claude Code CLI (v2.1.79) connects and operates without issue on the same VPS using the same user account.

What Should Happen?

The Desktop client should:

1. Establish a single SSH connection (or a small, bounded number) to the remote server rather than flooding with dozens of simultaneous sessions.

2. Respect .gitignore, .claudeignore, or .claude/settings.json ignorePatterns when performing the initial file tree enumeration via files.list RPC calls.

3. Complete the SSH handshake and launch the remote server binary within a few seconds, presenting the user with an active Claude Code session — matching the behavior of the previous client version and the terminal CLI.

4. Surface meaningful error messages in the UI when connection fails, rather than silently spinning on "Connecting..." with no diagnostic information.

Error Messages/Logs

=== journalctl -u sshd (showing connection flood + throttling) ===

Apr 14 21:41:27 sshd[1333]: error: beginning MaxStartups throttling
Apr 14 21:41:27 sshd[1333]: drop connection #19 from [CLIENT_IP]:60143 past MaxStartups
Apr 14 21:41:28 sshd-session: Accepted publickey for claudeuser from [CLIENT_IP] port 60125
Apr 14 21:41:28 sshd-session: session opened for user claudeuser
Apr 14 21:41:28 sshd-session: Accepted publickey for claudeuser from [CLIENT_IP] port 60127
Apr 14 21:41:28 sshd-session: Accepted publickey for claudeuser from [CLIENT_IP] port 60130
[... dozens more connections opened and closed within 1-2 seconds each ...]
Apr 14 21:41:57 sshd[1333]: exited MaxStartups throttling after 00:00:30, 18 connections dropped

=== remote-server.log (files.list flood when connections succeed) ===

2026/04/14 20:18:50 [Server] RPC request: method=files.list, id=17
2026/04/14 20:18:50 [Server] RPC response sent: id=17, hasError=false
2026/04/14 20:18:50 [Server] RPC request: method=files.list, id=18
[... 168 consecutive files.list calls from id=17 to id=185 in ~5 seconds ...]
2026/04/14 20:18:55 [Server] RPC response sent: id=185, hasError=false
2026/04/14 20:20:15 [Server] RPC request: method=process.spawn, id=186
[... ccd-cli spawns successfully after the flood completes ...]
[... then another burst of 185 files.list calls from id=189 to id=373 ...]
[... then another burst of 92 files.list calls from id=380 to id=471 ...]

=== After raising MaxStartups and truncating logs ===

remote-server.log remains EMPTY — the remote server binary is never launched.
The client-side connection still fails silently at "Connecting..."

=== Project stats ===

$ find /project/path -maxdepth 3 -type d | wc -l
989
$ find /project/path -type f | wc -l
25399
$ du -h --max-depth=1 /project/path
249M    frontend/        (242M is node_modules)
153M    node_modules/
118M    uploads/
16M     .git/

Steps to Reproduce

1. Set up a Linux VPS with a non-root user account (e.g. "claudeuser") with:

   • SSH key-based authentication (ed25519)
   • Node.js installed via nvm
   • A project directory containing ~25,000+ files (typical Node.js project with node_modules, uploads, .git)

2. Configure Claude Desktop (macOS) with an SSH remote connection to the non-root user account

3. Click "Connect" in the Desktop client's Code tab

4. Observe: Client shows "Connecting..." indefinitely, then fails

5. Verify via journalctl -u sshd --since "5 minutes ago" on the server: dozens of SSH sessions are opened and closed rapidly, triggering MaxStartups throttling

6. Verify via tail -f ~/.claude/remote/remote-server.log on the server: log remains empty (remote server never launches)

7. For comparison, SSH into the same server as the same user and run claude from the terminal — it connects and operates normally

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

Desktop client version prior to the most recent update (exact version unknown). The remote server's ccd-cli binary is version 2.1.101, which was functioning with the previous Desktop client. CLI version 2.1.79 works correctly via terminal.

Claude Code Version

ccd-cli: 2.1.101 (remote server binary, installed by Desktop client) CLI: 2.1.79 (working via terminal as workaround) Desktop client: latest macOS version as of April 14, 2026

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

Re: Terminal/Shell - N/A — issue is with Desktop client's built-in SSH, not terminal usage. Terminal SSH (via macOS Terminal.app / bash) works correctly.

WORKAROUNDS ATTEMPTED (server-side):

1. Added .claudeignore with node_modules/, uploads/, .git/, dist/, build/, *.log

   • Reduced directory count from 989 to 44
   • Did NOT reduce files.list RPC flood (server daemon ignores this file)

2. Added .claude/settings.json with ignorePatterns

   • Also had no effect on the files.list enumeration

3. Raised MaxStartups in sshd_config from 10:30:100 to 50:30:100

   • Eliminated throttling/dropped connections
   • But client still fails to launch the remote server

4. Verified claudeuser environment: shell works, Node.js accessible, ccd-cli binary present and executable, ulimit -n adequate

SUCCESSFUL WORKAROUND:

Installed Claude Code CLI (v2.1.79) for the non-root user via npm install -g @anthropic-ai/[email protected] and authenticated via OAuth with Max subscription. Terminal-based Claude Code works perfectly on the same server with the same user account.

NOTE: CLI versions 2.1.80+ have a separate OAuth regression that prevents subscription-based authentication (redirect_uri mismatch / "Unknown scope" errors). Version 2.1.79 is the latest version with working OAuth for subscription accounts connecting to remote Linux servers.

RELATED ISSUES:

• #37434 (SSH mode silently fails — --allow-dangerously-skip-permissions flag)
• #36739 (Remote SSH connection fails after client update 1.1.7714)
• #32734 (Timed out while waiting for handshake — internal ssh2 library)
• #27165 (Desktop app gets stuck connecting via SSH)
• #37747 (OAuth redirect_uri regression in 2.1.80+)