Get started

Services

A service is a container app in an environment. It has a source (where the code or image comes from), build settings, runtime settings, variables and domains. Every change that affects what runs creates a new deployment.

Sources

Source What keel.run does
Git repository Clones a branch of a repository on GitHub, GitLab or Codeberg/Forgejo, builds an image and deploys it. Optionally builds only a subdirectory (root), for monorepos.
Container image Deploys an image from a public registry, e.g. ghcr.io/acme/app:1.2. No build.

Git settings:

  • Provider and repository, e.g. github and acme/shop. For self-hosted GitLab or Forgejo instances, set the base URL (https://git.example.com).
  • Branch (default main): pushes to this branch deploy automatically when auto-deploy is on and the repository is connected through a Git connection. keel.run reports the build result back to the commit as a status.
  • Root directory: the directory inside the repository to build (default: the repository root).

Connections to your Git providers are managed in the dashboard. For GitHub, keel.run uses a GitHub App that you install on the repositories you choose; keel.run never sees your password, and its access ends when you uninstall the app.

Builds

Each build runs in its own short-lived, isolated job with rootless BuildKit. The builder is chosen per service:

Builder When
auto (default) dockerfile if the root directory contains a Dockerfile, otherwise railpack
dockerfile Builds the Dockerfile at dockerfile (default Dockerfile, relative to the root directory)
railpack Detects the language and framework with Railpack and builds an image without a Dockerfile (for example Node.js, Python, Go, PHP, Java and static sites)

Builds have a time limit per plan (see Billing and limits). Images are stored in keel.run's private registry; each workspace can only pull its own images.

A good Dockerfile for keel.run is an ordinary one: multi-stage, small final image, the app listening on $PORT.

FROM golang:1.27 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/web

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /app /app
ENTRYPOINT ["/app"]

Runtime settings

Setting Default Meaning
port 8080 The port your app listens on. Also passed to the app as PORT.
healthcheck – HTTP path for readiness checks, e.g. /healthz. Without one, keel.run checks that the port accepts TCP connections.
size s Instance size: xs, s, m, l, or xl (Pro). See sizes and prices.
instances 1 Number of instances (up to your plan's limit).
start – Overrides the image's start command.
release_command – Runs before each rollout with the new image and the same variables, e.g. database migrations.

RAM is reserved per instance and never overcommitted; CPU is shared up to the size's limit. New workspaces can use sizes up to m and 2 services during their first 14 days.

Deploys and rollbacks

A deployment is triggered by a push (with auto-deploy), by Deploy in the dashboard, by keel deploy, by the API (POST /v1/services/{id}/deployments) or by your agent's deploy_service tool. Changing variables or runtime settings also rolls out a new deployment, with the same image and without a rebuild.

queued → building → built → releasing → deploying → active
  • releasing: the release command runs as a one-off job (up to 15 minutes). If it fails, the deployment fails and nothing changes.
  • deploying: a rolling update starts new instances and stops old ones only when the new ones are ready – no downtime when your health check is right. If the new version does not become ready within 10 minutes, the deployment fails and the previous one keeps serving.
  • A newer deployment cancels older ones that have not finished.

Roll back to the previous deployment (or any earlier one) without rebuilding:

keel rollback              # the previous deployment
keel rollback dpl_01j…     # a specific one

Variables

Variables are set per service or shared by every service in an environment (the service's own value wins). Values are encrypted with a key per workspace and stored as secrets by default: listings show them only when you reveal them, which needs the config:write scope and is recorded in the audit log.

keel env set API_KEY=- < key.txt         # read a value from stdin, not the shell history
keel env set LOG_LEVEL=debug --plain     # not secret: visible in listings
keel env set SENTRY_DSN=… --shared       # for every service in the environment
keel env unset LOG_LEVEL
keel env pull                            # write .env with all values (mode 0600)

Running services are redeployed with the new values unless you pass --no-redeploy.

keel.run sets these variables itself; you cannot override them: PORT, KEEL_SERVICE, KEEL_ENVIRONMENT, KEEL_DEPLOYMENT. Linking a database adds DATABASE_URL (or a name you choose).

Services in the same environment reach each other by service name: http://api or http://api:8080.

Domains

Every service gets a generated hostname that never changes:

https://<service>-<project>[-<environment>].keelrun.app

keelrun.app is on the Public Suffix List, so services cannot set cookies for each other, and customer apps never run under keel.run.

Custom domains

Add up to 10 domains per service:

keel domains add www.example.com

keel.run answers with two DNS records to create at your DNS provider:

Record Purpose
TXT _keel-verify.www.example.com = keel-verify=<token> proves that you own the domain
CNAME www.example.com → <service>-<project>.keelrun.app routes traffic (for an apex domain use the A/AAAA records shown instead)

keel.run checks the records every few minutes. Once they are right, it requests a Let's Encrypt certificate and the domain becomes active; certificates renew automatically. Domain status: pending_dns → issuing → active, or error if DNS stops pointing to keel.run (the route then stays up for 72 hours while you fix it).

A domain that was added but never verified can be claimed by another workspace after 24 hours, so verify it soon after adding it.

Logs and metrics

  • Build logs stream live during a build and are kept for 30 days.
  • Runtime logs are what your app writes to stdout and stderr. Follow them live or search back up to 7 days (keel logs -f --since 1h), filter by deployment or instance. Retention depends on your plan.
  • Metrics: CPU and memory per service in the dashboard and through the API.

Secret variable values are masked as ******** in logs.

Workers, cron jobs and one-off commands

A service's kind decides how it runs:

Kind Runs Address
web (default) continuously, serves HTTP on port https://<service>-<project>.keelrun.app and custom domains
worker continuously, no port (queues, bots, consumers) none
cron its start command on a schedule (5 fields or @hourly, @daily, in a time zone you choose) none
keel services create mailer --repo acme/app --kind worker
keel services create nightly --repo acme/app --kind cron --schedule "0 3 * * *" --timezone Europe/Berlin

keel run -- <command> runs a command once with the service's current image and variables — migrations, seeds, scripts. It streams the output and exits with the command's exit code. Every cron execution and every one-off command is recorded as a run with its log (keel runs list, keel runs logs <run>). Runs are billed for the time they actually run.

A run can read every variable of the service, and its output can contain secret values that masking does not catch (for example base64-encoded ones). Reading the output therefore needs the same right as starting a run: config:write, together with logs:read. Without it, status, exit code and timings stay visible, the output is hidden (output_redacted: true in the API, a notice in the dashboard) and keel runs logs says which scope is missing. Every read of run output is recorded in the audit log (run.logs.read).

Preview environments

Turn on previews in the project settings and every pull request (GitHub), merge request (GitLab) or pull request (Codeberg/Forgejo) gets its own environment pr-<number> with the PR's code, its own URLs and — if you choose — a branch of the production database. keel.run comments the preview URLs on the PR and removes the environment when the PR is closed or merged, or after a few idle days.

Pull requests from forks never build on their own: a member of your workspace approves each new commit (keel previews approve), so untrusted code never sees your secrets. Variables can be excluded from previews, and database credentials of the base environment are never copied.

Key-value databases come along as fresh, empty ones: for every KV database of the base environment the preview gets its own with the same name on the smallest plan (kv-s), with new credentials. Linked variables such as REDIS_URL, KV_REST_API_URL and KV_REST_API_TOKEN point at the preview's database, so your app works unchanged and never touches production data. They are billed like any KV database and deleted with the preview. If they cannot be created (for example because billing refuses new databases), the preview still deploys and the PR comment says which KV databases were skipped. With the database setting none, previews get no KV databases either.

keel previews list
keel previews delete <preview>

View as Markdown