Configuration

# SSHKit

Connection pooling and command-runner tuning for large fleets.

[SSHKit](https://github.com/capistrano/sshkit) is the SSH toolkit used by Kamal.

The default, settings should be sufficient for most use cases, but when connecting to a large number of hosts, you may need to adjust.

## SSHKit options

The options are specified under the sshkit key in the configuration file.

```yaml
sshkit:
```

## Max concurrent starts

Creating SSH connections concurrently can be an issue when deploying to many servers. By default, Kamal will limit concurrent connection starts to 30 at a time.

```yaml
max_concurrent_starts: 10
```

## Pool idle timeout

Kamal sets a long idle timeout of 900 seconds on connections to try to avoid re-connection storms after an idle period, such as building an image or waiting for CI.

A pooled connection that the network dropped while idle is evicted and the command retried once on a fresh connection, so a long wait elsewhere (a server-lock poll, a loadbalancer reboot) does not fail the next command on another host. A host that stops answering keepalives mid-command is not retried; that deploy fails.

```yaml
pool_idle_timeout: 300
```

## DNS retry settings

Some resolvers (mDNSResponder, systemd-resolved, Tailscale) can drop lookups during bursts of concurrent SSH starts. Kamal will retry DNS failures automatically.

Number of retries after the initial attempt. Set to 0 to disable.

```yaml
dns_retries: 3
```

> **Note:** Generated from the gem's `lib/dash/configuration/docs/sshkit.yml` — the same reference `dash docs sshkit` prints in your terminal, so this page always matches your installed version.