Connect to a host over SSH

Give yoink SSH access to a host that has a root password, a non-default key, a deploy key in the repo, Tailscale, or a local VM.

Read as MarkdownEdit on GitHub

yoink uses the SSH client of your operating system. Each section is one SSH config and is independent of the others.

Fresh VPS, root password only

Copy your SSH key to the host one time. yoink then uses the key.

ssh-copy-id [email protected]                  # asks for the root password once
yoink up --build

Non-default key

Add an entry to ~/.ssh/config:

Host my-server
  HostName 1.2.3.4
  User root
  IdentityFile ~/.ssh/my-server.pem

Then use the Host name as the address in yoink.yaml:

hosts:
  - { address: my-server, user: root }

SSH on a port other than 22

Set port: on the host. Do not put the port in address:, because config load rejects address: host:2200.

hosts:
  - { address: 1.2.3.4, user: deploy, port: 2200 }

Ship the deploy key with the repo

If a team must not keep the host key in each personal ssh-agent, use this config. The key lives in sealed secrets.

  1. Reference the secret from the host:

    secrets:
      provider: age
      recipients: [age1…]
    
    hosts:
      - address: 1.2.3.4
        user: root
        ssh_key_secret: PROD_HOST_SSH_KEY    # name in secrets.age
  2. Run yoink secrets edit.

  3. Add the key value under the name PROD_HOST_SSH_KEY.

At deploy time, yoink decrypts the key to a 0o600 temporary file and uses it for the SSH connection. yoink removes the file on exit.

Tailscale (opt-in)

If you are on Tailscale, set address: to the tailnet hostname. See Networking.

Local VM

To use yoink with a local VM (Colima, OrbStack), expose the docker daemon of the VM over SSH. Then add the VM as a host. No special syntax is necessary.

To deploy to the docker daemon of your laptop without SSH, set address: local.

For a local development loop without a host, Docker Compose is the correct tool.

See also

  • First deploy: the tutorial that uses plain key-based SSH to one host.
  • Sealed secrets: how yoink seals and decrypts the deploy key.
  • Networking: the connectivity layer, Tailscale, and multi-host distribution.
  • Configuration: the hosts: fields, for example ssh_key_secret.

Type a flag, a config field, or a task.