# 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](#deploys-and-rollbacks).

## 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](https://railpack.com) 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](/docs/billing#plans)). 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`.

```dockerfile
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](/pricing). |
| `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.

```text
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:

```bash
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.

```bash
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](/docs/databases#link-a-database-to-a-service) 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:

```text
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:

```bash
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 |

```bash
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.

```bash
keel previews list
keel previews delete <preview>
```
