docs: document VS Code SSH keepalive and reconnection settings (#30501)

This commit is contained in:
coder[bot] authored and GitHub committed 2026-10-09 18:43:18 +05:00
1 parent 4276b93551
commit f8e053e385
1 file changed
+57
@@ -100,6 +100,63 @@ Support bundles can contain sensitive diagnostic data. Review the generated
bundle before sharing it. Learn more about
[support bundles](../../support/support-bundle.md).
## Connection timeouts and reconnects
The Coder Remote extension sets SSH keepalive and Remote - SSH reconnection defaults for Coder workspaces.
If your connection drops while the workspace is under heavy load, such as memory pressure, you can relax these settings.
### SSH keepalives
The extension writes these keepalive options to the SSH configuration it generates for Coder workspaces:
| Option | Default | Behavior |
|-----------------------|---------|--------------------------------------------|
| `ServerAliveInterval` | `10` | Sends a keepalive every 10 seconds. |
| `ServerAliveCountMax` | `3` | Disconnects after 3 unanswered keepalives. |
With these defaults, the SSH client disconnects after about 30 seconds without a response from the workspace.
To tolerate longer stalls, override the options in the `coder.sshConfig` VS Code setting:
```json
{
"coder.sshConfig": ["ServerAliveCountMax=30"]
}
```
This example disconnects after about 5 minutes without a response.
To remove a default option, set it to an empty value, such as `"ServerAliveCountMax="`.
The new values apply the next time you connect to the workspace.
If you're already connected, reload the window.
The extension merges SSH options from these sources, from highest to lowest precedence:
1. The `coder.sshConfig` VS Code setting.
1. Options passed to `coder config-ssh --ssh-option`.
1. Deployment-wide options that an administrator sets with [`CODER_SSH_CONFIG_OPTIONS`](../../reference/cli/server/index.md#--ssh-config-options).
### Reconnection settings
When you connect to a workspace, the extension writes these `remote.SSH.*` settings, in seconds, to your user settings.
They apply to all SSH hosts, not only Coder workspaces.
| Purpose | Setting | Set on connect | Recommended |
|----------------------------------|--------------------------------------------------------------------------------------|----------------------------------|--------------------------|
| Connection timeout | `connectTimeout` | Raised to at least `1800` | `1800` (30 minutes) |
| Server lifetime after disconnect | `reconnectionGraceTime` (VS Code, Devin Desktop) or `serverShutdownTimeout` (Cursor) | `28800` (8 hours), if unset | `86400` (24 hours) |
| Reconnection attempts | `maxReconnectionAttempts` (VS Code, Devin Desktop) | `null` (8 attempts), if unset | `null` (8 attempts) |
To apply the recommended values, run **Coder: Apply Recommended SSH Settings** from the Command Palette.
This command overwrites any values you set for these settings.
If you're connected to a workspace, reload the window to apply them.
On Devin Desktop, the extension writes the same values to the matching `remote.devinSSH.*` settings.
Antigravity has no equivalent settings.
`reconnectionGraceTime` only applies to Linux workspaces, and only after the remote server restarts.
These settings control how long your editor waits to connect, how long the remote server waits for you to reconnect, and how many times your editor retries.
They don't change when the SSH connection itself times out.
To adjust the SSH connection timeout, use `coder.sshConfig`.
## VS Code extensions
There are multiple ways to add extensions to VS Code Desktop: