Configuration

# SSH

How dash connects to your hosts.

Kamal uses SSH to connect and run commands on your hosts. By default, it will attempt to connect to the root user on port 22.

If you are using a non-root user, you may need to bootstrap your servers manually before using them with Kamal. On Ubuntu, you’d do:

```shell
sudo apt update
sudo apt upgrade -y
sudo apt install -y docker.io curl git
sudo usermod -a -G docker app
```

## SSH options

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

```yaml
ssh:
```

## The SSH user

Defaults to `root`:

```yaml
user: app
```

## The SSH port

Defaults to 22:

```yaml
port: "2222"
```

## Proxy host

Specified in the form  or @:

```yaml
proxy: root@proxy-host
```

## Proxy command

A custom proxy command, required for older versions of SSH:

```yaml
proxy_command: "ssh -W %h:%p user@proxy"
```

## Log level

Defaults to `fatal`. Set this to `debug` if you are having SSH connection issues.

```yaml
log_level: debug
```

## Keys only

Set to `true` to use only private keys from the `keys` and `key_data` parameters, even if ssh-agent offers more identities. This option is intended for situations where ssh-agent offers many different identities or you need to overwrite all identities and force a single one.

```yaml
keys_only: false
```

## Keys

An array of file names of private keys to use for public key and host-based authentication:

```yaml
keys: [ "~/.ssh/id.pem" ]
```

## Key data

An array of strings, with each element of the array being a secret name.

```yaml
key_data:
  - SSH_PRIVATE_KEY
```

You can also provide raw private key in PEM format, but this is deprecated.

```yaml
key_data:
  - "-----BEGIN OPENSSH PRIVATE KEY----- ..."
```

## Config

Set to true to load the default OpenSSH config files (~/.ssh/config, /etc/ssh_config), to false ignore config files, or to a file path (or array of paths) to load specific configuration. Defaults to true.

```yaml
config: [ "~/.ssh/myconfig" ]
```

## Forward agent

Whether to forward the local SSH agent to the remote host. Defaults to true (sshkit's default). Set to false when connecting through a jump host or tunnel that does not support agent forwarding (for example, Cloudflare Access for Infrastructure with SSH).

```yaml
forward_agent: false
```

## Connect timeout

Seconds to wait for the TCP connection and the SSH handshake with a host before giving up with `Net::SSH::ConnectionTimeout`. Defaults to 30. Without a bound, a host that accepts the connection but never answers the handshake hangs the deploy indefinitely.

```yaml
connect_timeout: 30
```

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