Variables and secrets

Each environment holds its own variables. Every one is written into the destination config KamalCloud generates:

• Plain variables go under env.clear in config/deploy.<environment>.yml. They are visible in the config and visible to anyone who can read the environment.
• Secret variables go under env.secret by name, with the value written to .kamal/secrets.<environment> on the runner. Kamal reads the file; the config carries only the name.

Secret values are encrypted at rest in KamalCloud. Admins can reveal them on the Variables page; other users see only the name. Change one by setting a new value.

Naming

Names are upper case: capital letters, digits and underscores, not starting with a digit (DATABASE_URL, _PRIVATE). Values are written into a dotenv-style file, so real newlines survive inside quotes and $VAR and $(...) are escaped rather than expanded – a value containing a dollar sign arrives at the container as itself.

What is set for you

Accessories generate their own passwords when they are created, and a connection URL, both as secrets, named after the accessory so two of a kind in one environment never share. An accessory called postgres gets POSTGRES_PASSWORD and POSTGRES_URL; one called analytics gets ANALYTICS_POSTGRES_PASSWORD and ANALYTICS_URL. The _URL secret is derived, and KamalCloud writes it again on every deploy from the current password, user, database and service name – so edit the password, not the URL. See Accessories.

Templates generate whatever secrets they declare at install: a session key, an admin password, whatever the image needs. See Templates.

A supplied certificate is stored as two secrets, because that is how Kamal reads one. See Domains and TLS.

Secrets your deploy.yml names

If your repository’s deploy.yml names a secret under env.secret and the environment does not have it, the environment is blocked – the deploy is refused rather than attempted, and the page tells you which name is missing. This is the most common first-deploy stumble and it is deliberately loud.

Registry credentials

Registry credentials come from your deploy.yml the same way they do when you run Kamal yourself, with the password as a secret on the environment.

Changing a variable

Variables are written into the destination config and the secrets file at deploy time. Adding, changing or removing one does not touch a running container. Deploy again, or reboot the environment – reboot rewrites the two files and boots the image already on the hosts, so new values take effect without a build.