Skip to content
Start / Quickstart

Quickstart

From a new account to a deployed app, in the order the product asks for things.

Eight steps. Most of them are one form. The long ones – building a server, preparing a runner, the first deploy – run in the background and stream their output to the page.

1. Create an account

Sign up and you land on a fresh account with nothing connected. A card is collected before anything is provisioned; the first week is a trial. See Billing.

2. Connect a cloud provider

Providers → Connect. Pick Hetzner, DigitalOcean, AWS or self-hosted, and paste a token.

KamalCloud verifies the token immediately and tells you if the provider refused it. Each connection is one provider project – a Hetzner project, a DigitalOcean team, an AWS account – and you can hold several of the same provider. See Providers.

3. Build a server

Servers → New. Choose the connection, a location, a machine type and an image. KamalCloud builds it with the account’s SSH keys installed for root – never with a root password.

The row goes pending → initializing → running. When it is running, KamalCloud detects the OS and reads the machine’s own idea of itself back.

Have a machine already? Add it as a self-hosted server instead.

4. Harden it

Server → Security. KamalCloud checks the machine and lists what is wanting – the firewall, SSH login settings, fail2ban, automatic security updates, package upgrades, swap and more. Each fix is its own button and its own run, so you decide what to apply. Hardening has the full list.

5. Connect a git host

Git providers → Connect. GitHub installs an app, GitLab and Gitea authorise one, Bitbucket takes a token. Afterwards KamalCloud can list your repositories and branches, clone them on the runner, and receive push events. See Git providers.

6. Prepare a runner

First generate the account’s SSH keys under Account → Access keys; runners and servers are refused until they exist.

Runners → Add runner. Point it at one of your servers – or any machine you can reach over SSH as root. Preparation starts as soon as it is added: KamalCloud installs git, Docker and binfmt, the account’s deploy key and an SSH config, and pulls the pinned Kamal image.

A runner is not a deploy target. It is the machine that runs kamal, and one runner can serve every app in the account. See Runners.

7. Add an app

Apps → New. Name it, choose the runner, and pick the git connection and repository – or paste a plain git URL, which is cloned with the account’s deploy key.

The same form creates the app’s first environment. An environment is a Kamal destination: production, staging, whatever you name it. Give it a branch, a server and, if you have one, a domain. With no domain, KamalCloud gives it a generated sslip.io hostname that resolves to the server, so there is something to reach straight away.

Your repository needs its own config/deploy.yml – the one Kamal already reads. KamalCloud parses it for the app’s shape and writes destination files beside it; it does not replace it. Nothing to deploy yet? Install an off-the-shelf one from Templates.

Then add what the environment needs:

The environment page tells you what is still standing in the way before you press deploy.

8. Deploy

Set up and deploy. KamalCloud clones your repository on the runner at the branch head, writes config/deploy.<environment>.yml and .kamal/secrets.<environment> next to it, and runs kamal setup -d <environment> from the official image. After the first time the button is Deploy, and runs kamal deploy. The output streams to the page as it happens.

When it lands, the version is recorded, the environment shows what is running, and your domains are served. Turn on auto-deploy and the next push does the same thing by itself.

After the first deploy