Concepts

Account

The tenant. Everything belongs to one: connections, servers, apps, keys, buckets, tokens. An account has users with roles, a subscription, and a pair of SSH keys it reaches everything with.

Accounts are addressed by an id in the URL, so one person in several accounts switches between them without signing out.

Connection (credential)

One set of credentials for one provider project. A Hetzner project, a DigitalOcean team, an AWS account and region – or self-hosted, which is a namespace rather than a token.

An account can hold several connections to the same provider; that is the point. Production in one Hetzner project and staging in another are two connections.

Server

A machine. Either one KamalCloud built at a provider, or one of your own that KamalCloud was told about. Two questions decide what can be done with it:

• Registered – KamalCloud knows how to reach it over SSH. Everything done over SSH is gated on this: hardening, preparing a runner, deploying.
• API-managed – there is a provider API behind it. Building, resizing, powering on and off, pricing and traffic figures need this. A self-hosted machine is registered but not API-managed.

SSH keys

Every account uses two key pairs. They are not made when the account is created: an admin generates them, or pastes in existing ones, on Account → Access keys. Until they exist, KamalCloud refuses to add a runner or a server.

• The control key, which reaches runners and does the administrative work.
• The deploy key, which is what lands on servers so Kamal can reach them.

Both are pushed to each provider’s keyring so new machines are built trusting them. See SSH keys.

Git connection

One connection to a git host: a GitHub App installation, a GitLab or Gitea authorisation, or a Bitbucket token. It lists repositories and branches, clones on the runner, and receives push events. An account can hold several.

Runner

The machine Kamal runs on. KamalCloud reaches it over SSH with the control key and runs the pinned official Kamal image against its Docker daemon.

A runner holds a checkout of each app it deploys and the Docker images it builds. It is not where your app runs – it is where the deploy happens from. One runner serves as many apps as you like.

App

A repository deployed with Kamal, or an image installed from a template. It names the git connection, the repository and the runner. It holds environments.

Environment

One Kamal destination of an app: production, staging, eu. This is the unit almost everything hangs off. An environment has:

branch	what gets checked out, and what a push has to match to auto-deploy
hosts	servers, each pinned to a Kamal role
variables	plain env vars, and secrets Kamal passes by name
domains	hostnames kamal-proxy answers for
certificate	a supplied pair, where Let’s Encrypt cannot be used
ports	raw TCP or UDP the proxy cannot front
accessories	databases and caches Kamal boots alongside
volumes	data the containers mount
tasks	commands on a schedule
deployments	one run of Kamal each

Host

One server pinned to one Kamal role – web, worker, job. Several hosts in a role is several machines in that role, in the order Kamal should boot them. See Hosts and roles.

Deployment

One run of Kamal against an environment. The kind says which:

• Releasing – deploy, redeploy, rollback, setup. These put a version on the servers, and the newest of them names what is running.
• Traffic – maintenance, live. These only decide whether kamal-proxy serves.
• Housekeeping – bootstrap (Docker and directories, no deploy), reboot (restart what is already there), lock_release.
• Accessory – boot, reboot, start, stop, restart, remove for one accessory.

Every deployment has a status (queued, running, succeeded, failed, cancelled) and a log that streams as it happens.

Accessory

A database or cache Kamal runs alongside the app, from a small catalog: PostgreSQL, MySQL, Redis, Valkey. Its generated password and connection URL become secrets the app reads.

Volume

Data the containers mount, rather than a container Kamal runs: a Docker volume or a directory on the host. It has no lifecycle of its own. What it has is backups.

Bucket

An S3-compatible bucket where backups go. Account-level: any environment can use one. KamalCloud reaches it through a throwaway mc container on a runner, not from its own host.

Change request

Something the API or the CLI proposes and a person agrees to. Reads never go through here; every change does. See Change requests.