# Getting started

This guide takes you from sign-up to a running app in a few minutes. You need a Git repository with an app that listens on a port – with or without a Dockerfile.

## 1. Sign up

Open [the dashboard](https://app.keel.run/login) and sign in with GitHub, GitLab or Codeberg, or with a link sent to your e-mail address. Your first workspace is created for you.

## 2. Start the trial

keel.run has no free tier. Your workspace's first subscription starts with a **7-day trial with €5 of usage**; a card is required, and you are charged only after the trial ends. Choose a plan under **Billing** in the dashboard. Until then you can create projects, but no services or databases.

See [Billing and limits](/docs/billing) for plans, usage prices and spend limits.

## 3. Deploy from Git

1. Create a **project**, for example `shop`. It starts with a `production` environment.
2. Click **New service** and pick **Git repository**.
3. Connect your Git provider once: **GitHub** (install the keel.run GitHub App on the repositories you want), **GitLab** or **Codeberg/Forgejo**. Public repositories also work without a connection, but then keel.run cannot deploy on push.
4. Choose the repository and branch (default `main`). If the app lives in a subdirectory of a monorepo, set the **root directory**.
5. Create the service. keel.run clones the branch, builds an image and deploys it.

The build log streams live. When the deployment is `active`, the service answers at its generated hostname:

```text
https://<service>-<project>.keelrun.app
```

Environments other than `production` add their name: `https://web-shop-staging.keelrun.app`.

From now on, every push to the branch deploys automatically (you can turn this off per service). A failed build or a failing health check never replaces the running version.

### What keel.run expects from your app

- **Listen on `$PORT`.** keel.run sets `PORT` (default `8080`, configurable per service) and routes HTTPS traffic to it. Listen on `0.0.0.0`, not `localhost`.
- **Be stateless.** Instances can be replaced at any time; keep data in a [database](/docs/databases).
- **Log to stdout and stderr.** Logs are collected from there.

How the image is built: see [Services → Builds](/docs/services#builds).

## 4. Install and use the CLI

Install the `keel` CLI on macOS or Linux:

```bash
curl -fsSL https://keel.run/install.sh | sh
```

The script downloads the release for your OS and CPU from `https://keel.run/download/cli/`, verifies its SHA-256 checksum (and the Sigstore signature of the checksums if [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) is installed) and puts `keel` into `/usr/local/bin` if you can write there, otherwise into `~/.local/bin`. It never uses `sudo`. Set `KEEL_INSTALL_DIR` for another directory or `KEEL_VERSION=v1.2.3` for a specific release.

With Homebrew:

```bash
brew install keel-run/tap/keel
```

On Windows, download [`keel_windows_amd64.zip`](https://keel.run/download/cli/latest/keel_windows_amd64.zip) (or [`keel_windows_arm64.zip`](https://keel.run/download/cli/latest/keel_windows_arm64.zip)) and put `keel.exe` on your `PATH`. Every release has a [`checksums.txt`](https://keel.run/download/cli/latest/checksums.txt) to verify the download, signed with Sigstore (`checksums.txt.sigstore.json`). A specific release lives under `https://keel.run/download/cli/v1.2.3/` with the same file names.

`keel version` shows the installed version and tells you when a newer release is available.

Then log in. `keel login` opens your browser; the token is stored in your operating system's keychain.

```bash
keel login
```

Link a local checkout to the service, then deploy, watch and read logs:

```bash
cd my-app
keel link                      # pick project, environment and service
keel deploy --watch            # deploy the branch head and stream the build log
keel logs -f --since 10m       # follow the runtime logs
keel status                    # deployments, runtime status, domains
```

`keel link` writes `.keel/project.json` with IDs only; it is safe to commit. Without a terminal (CI, agents), pass `--project`, `--environment` and `--service` instead of answering prompts.

In CI, set `KEEL_TOKEN` to a token created in the dashboard (**Settings → Tokens**) or with `keel tokens create`:

```bash
keel tokens create --name ci --kind svc --scopes read,deploy
```

Every command supports `--json` for machine-readable output. See the [CLI reference](/docs/cli).

## 5. Deploy from a local directory

`keel deploy` in a linked directory uploads the folder (uncommitted changes included) and keel.run builds and deploys it — no Git push needed:

```bash
keel link            # once per directory
keel deploy          # upload, build, deploy, stream the build log
keel deploy --dry-run   # list the files that would be uploaded
```

Files listed in `.gitignore` are left out, as are `.git`, `.env*` and `node_modules`. A `.keelignore` excludes more or re-includes files (`!.env.production`). To deploy the service's Git branch instead, use `keel deploy --git` (or `--commit <sha>`).

## 6. Add a database

```bash
keel db create main --plan pg-s
```

Then link it to your service in the dashboard (**Database → Link**): keel.run writes `DATABASE_URL` into the service's variables and redeploys it. See [Databases](/docs/databases).

## Next steps

- [Add your own domain](/docs/services#domains)
- [Set variables and secrets](/docs/services#variables)
- [Connect Claude Code](/docs/agents)
- [Set a spend limit](/docs/billing#spend-limits)
