SSH Connection Troubleshooting

Connection Refused

Symptom: "Connection refused" when connecting to a remote server.

Check:

1. SSH server is running: systemctl status sshd on the remote
2. Port is correct (default 22, some providers use custom ports)
3. Firewall allows SSH traffic
4. Security group / network ACL permits inbound SSH (cloud instances)

Authentication Failed

Symptom: "Authentication failed" after entering credentials.

Solutions:

Test from terminal first:

ssh -v user@host

The -v flag shows which authentication methods are attempted and why they fail.

Host Key Changed

Symptom: "Host key verification failed" or "REMOTE HOST IDENTIFICATION HAS CHANGED".

Cause: The server's SSH key changed (reinstalled OS, different server at same IP, or potential MITM attack).

If you trust the change:

1. The app shows a dialog with the new fingerprint
2. Click Accept New Key to update your known hosts
3. Or manually: ssh-keygen -R hostname then reconnect

If unexpected: Do not connect. Verify with your server administrator.

Agent Deployment Failed

Symptom: "Failed to deploy agent" after connecting.

The app uploads crab-desktop-agent to ~/.crab/bin/ on the remote server.

Check:

1. Disk space: df -h ~ — need ~20 MB free
2. Permissions: ls -la ~/.crab/bin/ — binary must be executable
3. Architecture mismatch: The app detects remote arch (x86_64/aarch64) and uploads the matching binary. If detection fails, check uname -m on the remote.
4. Kill stale agent: pkill crab-desktop-agent on the remote, then reconnect

High Latency

Symptom: Remote operations feel slow (> 500ms for file tree, > 1s for diffs).

Solutions:

1. Enable compression: Edit the connection profile → enable compression
2. Check connection quality: SSH view → Connection Diagnostics shows RTT and bandwidth
3. Adaptive caching: The app automatically increases cache TTLs for slow connections. You can also manually increase in the connection profile.
4. Reduce prefetch: For very slow connections, disable prefetch in connection settings

Connection Drops

Symptom: "Connection lost" messages, operations fail intermittently.

What happens automatically:

• The app reconnects with exponential backoff (1s, 2s, 4s, up to 60s)
• Read operations use cached data during reconnection
• Write operations queue and retry after reconnection

If drops are frequent:

1. Check network stability (Wi-Fi vs wired)
2. Add ServerAliveInterval 30 to your SSH config for the host
3. Check if the server has an idle timeout (some cloud providers disconnect after inactivity)
4. Use a jump host if the direct connection is unreliable

Port Forwarding Issues

Symptom: Port forward fails or service isn't accessible.

Check:

1. The remote service is actually listening: ss -tlnp | grep PORT on the remote
2. The local port isn't already in use: lsof -i :PORT locally
3. The remote service binds to 0.0.0.0 or 127.0.0.1 (not just a specific interface)

Remote Repository Not Detected

Symptom: Browsing remote files but "Open as Repository" doesn't appear.

Check: The directory must contain a .git folder. Navigate into the correct directory — the button appears when .git is detected in the current path.