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:

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.

ssh:

The SSH user#

Defaults to root:

user: app

The SSH port#

Defaults to 22:

port: "2222"

Proxy host#

Specified in the form or @:

proxy: root@proxy-host

Proxy command#

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

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

Log level#

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

log_level: debug

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.

keys_only: false

Keys#

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

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

Key data#

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

key_data:
  - SSH_PRIVATE_KEY

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

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.

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).

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.

connect_timeout: 30

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.