SSH configuration

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 <host> or <user>@<host>:

  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

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.

  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" ]