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 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 for plans, usage prices and spend limits.
3. Deploy from Git
- Create a project, for example
shop. It starts with aproductionenvironment. - Click New service and pick Git repository.
- 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.
- Choose the repository and branch (default
main). If the app lives in a subdirectory of a monorepo, set the root directory. - 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:
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 setsPORT(default8080, configurable per service) and routes HTTPS traffic to it. Listen on0.0.0.0, notlocalhost. - Be stateless. Instances can be replaced at any time; keep data in a database.
- Log to stdout and stderr. Logs are collected from there.
How the image is built: see Services → Builds.
4. Install and use the CLI
Install the keel CLI on macOS or Linux:
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 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:
brew install keel-run/tap/keel
On Windows, download keel_windows_amd64.zip (or keel_windows_arm64.zip) and put keel.exe on your PATH. Every release has a 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.
keel login
Link a local checkout to the service, then deploy, watch and read logs:
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:
keel tokens create --name ci --kind svc --scopes read,deploy
Every command supports --json for machine-readable output. See the CLI reference.
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:
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
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.