Self-hosted servers

KamalCloud does not have to have built a machine to deploy to it. A self-hosted connection is a namespace rather than a token: it holds machines KamalCloud reaches over SSH and manages what runs on them, without pretending it built them.

This is how you use a machine in a rack, a box at a provider with no supported API, or a VPS somebody else set up.

Adding one

1. Providers → Connect → Self-hosted. There is nothing to paste. The connection exists so the machines have somewhere to live.
2. Servers → New, with that connection. Because there is no catalog to choose from, you describe the machine instead: its address, the SSH user, and the port if sshd is not on 22.
3. Put KamalCloud’s deploy key on it. The server’s SSH key page gives you a one-line command to paste into a console on the machine. It appends a public key to authorized_keys and nothing travels back.

Either address family will do – KamalCloud dials whichever it is given. IPv4 and IPv6 are both recorded if you supply both.

The SSH user

Providers all hand over root. A machine of your own may well not. Set the user KamalCloud should log in as; it needs to be able to run Docker and, for hardening, sudo without a password prompt.

Kamal takes one SSH user and port for a whole destination, so every machine in one environment has to agree on both. An environment with hosts that disagree is blocked before a deploy is attempted, and the environment page says so.

Using your own key

If a machine already trusts a key of yours, import the private half under Account → SSH keys and name it on the server. Blank means the account’s deploy key; anything else names the key that machine already accepts. See SSH keys.

What works and what does not

Works — everything over SSH. Hardening, preparing a runner, deploying, containers, live logs, the shell, tasks, accessories, backups, volumes.

Does not work — everything that is an API call. KamalCloud will not build, resize, power, reboot or price a machine it does not have a provider behind. There is no traffic allowance to read and no cloud firewall to attach, so the cloud_firewall fix does not appear and the machine’s own firewall is the only one there is.

A self-hosted machine as a runner

A runner can be any machine KamalCloud can reach, including a self-hosted one, and including one that is also a deploy target. A small box that only ever runs kamal is the tidier arrangement, because a runner holds checkouts and builds images and both want disk.