# keel.run documentation > The complete keel.run documentation in one file. Each page starts with a `Source:` line. --- Source: https://keel.run/docs.md # keel.run documentation keel.run is an EU developer cloud. It builds and runs container apps from Git or a local directory – web services, workers and cron jobs, with preview environments per pull request – and offers managed Postgres and serverless Valkey, on Hetzner servers in Germany and Finland. Everything you can do in the dashboard also works through the [REST API](/docs/api), the [`keel` CLI](/docs/cli) and a [remote MCP server](/docs/agents) for coding agents. > keel.run is in beta: there is no SLA yet. Current availability and incidents: [status.keel.run](https://status.keel.run). ## Start here - [Getting started](/docs/getting-started): sign up, deploy your first app from GitHub, GitLab or Codeberg, and use the CLI. - [Services](/docs/services): sources, builds, runtime settings, variables and domains. - [Databases](/docs/databases): managed Postgres, linking it to an app, connecting from your machine, backups and restores. - [Mail](/docs/mail): mailboxes for your domains, webmail, aliases and forwarding; [App mail](/docs/mail-sending) for transactional mail and inbound webhooks. - [Agents](/docs/agents): connect Claude Code or another MCP client, scopes and confirmations. - [Billing and limits](/docs/billing): plans, usage, spend limits and what happens when you reach them. - [Security](/docs/security): how tenants are isolated and where your data lives. ## Concepts ```text Workspace billing, plan, spend limit, API tokens └─ Project a group of things that belong together, e.g. "shop" └─ Environment production, staging, …: one isolated network each ├─ Service a container app built from Git or a container image │ └─ Deployment an immutable release: commit, image and configuration ├─ Database managed Postgres └─ Variables environment variables and secrets ``` - **Workspace** (`ws_…`): the billing unit. It has a plan, an optional spend limit, API tokens and an audit log. - **Project** (`prj_…`): groups environments. Every project starts with a `production` environment. - **Environment** (`env_…`): an isolated network. Services in the same environment reach each other by name (`http://api:8080`); nothing outside it can. - **Service** (`svc_…`): an app built from a Git repository or deployed from a container image. It gets an HTTPS hostname such as `https://web-shop.keelrun.app`. - **Deployment** (`dpl_…`): every deploy creates one. Its status goes `queued → building → built → releasing → deploying → active`, or ends as `failed` or `cancelled`. When a new deployment becomes active, the previous one becomes `superseded` and you can roll back to it. - **Database** (`db_…`): a managed Postgres cluster in an environment. IDs are stable; names can change. The API, CLI and MCP tools accept IDs everywhere and names where they are unique. ## For agents Every page of these docs is also available as Markdown: add `.md` to its URL, for example [/docs/getting-started.md](/docs/getting-started.md). [/llms.txt](/llms.txt) lists all pages, and [/llms-full.txt](/llms-full.txt) is the whole documentation in one file. ## Status and support - Platform status and incidents: [status.keel.run](https://status.keel.run). - Every API error carries an `X-Request-Id` header. Include it when you contact support. - Abuse reports: `abuse@keel.run`. --- Source: https://keel.run/docs/getting-started.md # 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://-.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 `). ## 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) --- Source: https://keel.run/docs/services.md # 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://-[-].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=` | proves that you own the domain | | `CNAME www.example.com` → `-.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://-.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 -- ` 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 `). 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-` 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 ``` --- Source: https://keel.run/docs/databases.md # Databases keel.run runs managed **Postgres 17 and 18** (default 18) with [CloudNativePG](https://cloudnative-pg.io). Each database is its own Postgres cluster in your environment, on local NVMe storage, with daily backups and point-in-time recovery. ## Plans | Plan | vCPU | RAM | Storage (default / max) | Instances | Point-in-time recovery | |---|---|---|---|---|---| | `pg-xs` | 0.25 | 256 MB | 1 GB / 10 GB | 1 | 7 days | | `pg-s` (default) | 0.5 | 1 GB | 10 GB / 100 GB | 1 | 7 days | | `pg-m` | 1 | 2 GB | 25 GB / 250 GB | 1 | 14 days | | `pg-m-ha` (Pro) | 1 | 2 GB | 25 GB / 250 GB | 2 (primary + standby, automatic failover) | 14 days | A database is billed like an app: RAM by reservation, CPU by use, plus storage. See [Pricing](/pricing). Storage can grow at any time (never shrink). Changing the plan restarts the instances; with `pg-m-ha` the standby is promoted first. ## Create a database In the dashboard: **New → Database** in an environment. Or with the CLI or API: ```bash keel db create main --plan pg-s # --version 17|18, --storage keel db list ``` ```bash curl -X POST https://api.keel.run/v1/environments/env_…/databases \ -H "Authorization: Bearer $KEEL_TOKEN" -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name": "main", "plan": "pg-s"}' ``` The status goes `provisioning → available`, usually within a few minutes. Other states: `restoring`, `degraded` (one instance is unhealthy), `paused` (the workspace is suspended), `failed`, `deleting`. The database has one database and one owner role, both called `app`. There is no superuser. ## Link a database to a service Linking writes the database's internal connection URL into a service's variables (default name `DATABASE_URL`) and redeploys the service: ```bash curl -X POST https://api.keel.run/v1/databases/db_…/link \ -H "Authorization: Bearer $KEEL_TOKEN" -H "Content-Type: application/json" \ -d '{"service_id": "svc_…"}' ``` Without `service_id`, the variable is set for every service in the environment. Pass `"variable": "PG_URL"` for another name, or `"redeploy": false` to roll out later. In the dashboard, use **Link** on the database page. Inside the environment, traffic to the database never leaves your environment's private network. When you rotate the password, keel.run updates every linked variable and redeploys the services that use it. ## Connect from your machine Every database is reachable from the internet through **keel-pgproxy** on port 5432 – over TLS only. The proxy reads the database from the TLS server name (SNI), so all databases share one address: ```text postgres://app:@db-01j….pg.keel.run:5432/app?sslmode=require ``` Get the URL (it contains the password, and every read is recorded in the audit log), or open `psql` directly: ```bash keel db url main # prints the connection URL keel db connect main # runs psql; the password is passed via PGPASSWORD, not the command line ``` Notes for clients: - **TLS is required.** Use `sslmode=require` or stricter; plain-text connections are refused. With `sslmode=verify-full` your client checks the certificate of `*.pg.keel.run`. - **SNI:** libpq 14 and newer (psql, most drivers built on it) and most native drivers send the host name automatically. Postgres 17+ clients can also use `sslnegotiation=direct`. - **Clients without SNI:** add `options=endpoint=` to the connection string, or use `app.` as the user name. - The proxy limits connections per IP address and per database. Use a connection pool in long-running apps. ## Read-only SQL for agents `POST /v1/databases/{id}/query` (and the MCP tool `run_sql`) runs a single statement in a read-only transaction as a separate role that can read your data but cannot write, with a 5-second timeout and at most 500 rows. The audit log records a hash of the statement, not its text. It needs the `databases:query` scope. ## Backups and restores - A **base backup** runs every day, and the write-ahead log is archived continuously to object storage at Hetzner, so you can restore to any point in time within the plan's recovery window. - `GET /v1/databases/{id}/backups` lists the backups and the earliest point you can restore to. - A **restore always creates a new database**; the original is never overwritten. This also works for a database you deleted, as long as it is within the recovery window. ```bash curl -X POST https://api.keel.run/v1/databases/db_…/restore \ -H "Authorization: Bearer $KEEL_TOKEN" -H "Content-Type: application/json" \ -d '{"to_time": "2026-11-17T09:30:00Z", "name": "main-restored"}' ``` Without `to_time`, the newest possible state is restored. Check the restored data, then link the new database to your service. ## Delete a database Deleting needs the `admin` scope (agents must confirm it in a second step). The database stops at once; its backups stay available for restores until the recovery window has passed. --- Source: https://keel.run/docs/kv.md # Key-value (Valkey) keel.run runs serverless **Valkey**, the open-source, Redis-compatible key-value store. Each database runs in your environment and is reached through keel's gateway in two ways: - **RESP over TLS** on port 6379 — any Redis client (`rediss://` URL). - **REST** — compatible with the Upstash REST API, so `@upstash/redis` works with a custom URL. Useful from edge and serverless runtimes that can't keep TCP connections. ## Plans | Plan | Memory | Notes | |---|---|---| | `kv-s` | 256 MB | default | | `kv-m` | 1 GB | | | `kv-l` | 4 GB | Pro plan | The eviction policy is `noeviction` (writes fail when memory is full, default) or `allkeys-lru` (use it as a cache). Data is persisted to its volume (append-only file, written every second). ## Create and connect ```bash keel kv create cache --plan kv-s --eviction allkeys-lru keel kv url cache # rediss:// URL with password keel kv url cache --rest # REST URL and token keel kv list ``` Link the database to a service and keel.run sets `REDIS_URL`, `KV_REST_API_URL` and `KV_REST_API_TOKEN` as secret variables and redeploys it. Apps inside keel.run reach the database through the in-cluster gateway (`keel kv url cache --internal`). ```ts import { Redis } from '@upstash/redis'; const redis = new Redis({ url: process.env.KV_REST_API_URL!, token: process.env.KV_REST_API_TOKEN! }); await redis.set('greeting', 'hello'); ``` Tokens and passwords can be rotated at any time; linked services are updated and redeployed. ## Commands and limits Administrative and dangerous commands (`CONFIG`, `DEBUG`, `MODULE`, `SHUTDOWN`, `REPLICAOF`, `MIGRATE`, and `FLUSHALL` unless you allow it) are blocked, also inside Lua scripts. `KEYS` and `FLUSHDB` are rate-limited. Request sizes, command rates and connections are limited per plan. ## Preview environments You cannot create KV databases in a preview environment yourself. Instead, every preview of a pull request gets an empty KV database for each one of its base environment, with the same name, on `kv-s` and with its own password and token. Linked variables point at it; production data and credentials never reach the preview. Preview KV databases do not count against your plan's database limit, are billed like other KV databases and are deleted with the preview. See [preview environments](/docs/services#preview-environments). ## Sleeping databases A database without requests for 24 hours goes to sleep: its data stays on the volume and it costs only storage. The next request wakes it; the gateway holds that request for up to 10 seconds while it starts. ## Billing You pay per command, for the volume, and for the plan's memory while the database is awake. See [pricing](/pricing) for the current prices. --- Source: https://keel.run/docs/dns.md # DNS keel DNS hosts the zones of your domains on keel's own nameservers: four nodes at two providers in four European cities, each answering from its last good state even if the rest of the platform is down. You manage zones in the dashboard, with the CLI, the API or an agent over MCP. DNSSEC is on by default. keel DNS is not a registrar. You keep your domain where it is and point it at keel's nameservers. ## Create a zone ```bash keel dns zone create example.com keel dns zone create example.com --import example.com.zone # with the export of your old provider keel dns zone create shop.example.com --project shop --no-dnssec ``` The answer lists **four nameservers**, for example: ``` terbium.keeldns.net dysprosium.keeldns.net holmium.keeldns.net erbium.keeldns.net ``` Every zone gets its own group of nameservers (the letter differs between zones). Set exactly these four at your registrar and remove all others. Until the delegation matches, the zone is `pending_delegation`: you can already add records and test them with `keel dns query`, but keel does not serve the zone yet. ### Why the zone waits for the delegation All customers share the same nameservers. So that nobody can take over a domain by creating a zone for it, a zone is only served once the parent zone delegates to **its** nameserver group, which is chosen at random when the zone is created. Setting the nameservers at the registrar is what proves the domain is yours; no TXT record is needed. keel checks the delegation every two minutes in the first hour, then every 15 minutes. To check now and see what the parent zone returns: ```bash keel dns zone verify example.com ``` ``` Delegation of example.com: status pending_delegation expected nameservers: terbium.keeldns.net ok dysprosium.keeldns.net ok holmium.keeldns.net missing erbium.keeldns.net missing other nameservers at the parent (remove them): ns1.oldprovider.example ``` Registrar changes can take up to a day to show. If the delegation of an active zone stops matching for seven days, the zone becomes `delegation_lost` (it is still served) and you get an e-mail. ### Registrars | Registrar | Where to set nameservers | DNSSEC (DS record) | |---|---|---| | INWX | Domain → Nameserver → "Use other nameservers" | Domain → DNSSEC → add key (DS) | | Namecheap | Domain List → Manage → Nameservers → "Custom DNS" | Advanced DNS → DNSSEC (Custom DNS only) | | GoDaddy | Domain → DNS → Nameservers → "I'll use my own nameservers" | DNS → DNSSEC → add DS record | | Strato | Domain → Domainverwaltung → Nameserver → "Externe Nameserver" | DNSSEC → DS-Eintrag hinzufügen | | IONOS | Domains → Nameservers → "Use custom nameservers" | Domain → DNS → DNSSEC (external DS) | Menu names change from time to time; your registrar's help has the current path. ## Records keel DNS works with **RRsets**: all records of one name and type share a TTL. Names are relative to the zone (`www`, `@` for the apex, `*.dev` for a wildcard). Record data is written as in a zone file. ```bash keel dns records example.com keel dns record add example.com www A 192.0.2.1 --ttl 300 keel dns record add example.com @ MX "10 mx1.example.net." "20 mx2.example.net." keel dns record set example.com @ TXT "v=spf1 include:_spf.example.net -all" # replaces the RRset keel dns record rm example.com old CNAME ``` `record add` fails if name and type exist; `record set` replaces them. TXT data without quotes is quoted for you. TTLs range from 60 seconds to one week; the zone's default is 3600 seconds (`keel dns zone update example.com --default-ttl 600`). | Type | Notes | |---|---| | A, AAAA | | | CNAME | alone at its name, never at the apex, one record | | MX, SRV, CAA, TXT | TXT strings longer than 255 bytes are split automatically | | NS, DS | only below the apex, to delegate a subdomain elsewhere | | SVCB, HTTPS | RFC 9460 | | TLSA | only under `_port._proto.name`; useful only with DNSSEC | | ALIAS | at any name, typically the apex: points at a keel service (`svc_…` or its generated hostname) and is answered as A/AAAA | PTR, NAPTR, SSHFP and other types are not supported; an import lists them as skipped. Records created by keel – for a custom domain of a service, or for mail – are **managed**: you see them with the owner in the "managed by" column and change them through their owner. If you already have a record with the same name and type, keel does not overwrite it and shows a conflict instead. Changes reach all nameservers within seconds. Test the current state of the zone, also before it is delegated: ```bash keel dns query example.com www A keel dns query example.com @ MX --dnssec ``` ## Custom domains of services When you add a custom domain to a service and the hostname is in one of your active zones, keel creates the records itself: a CNAME for subdomains, an ALIAS for the apex. The domain counts as verified (you own the zone), and certificates are issued over DNS-01, so wildcard domains like `*.example.com` work too. In the dashboard, the "Add domain" dialog offers this automatically. ## Import and export ```bash keel dns import example.com example.com.zone # adds what is missing, reports conflicts keel dns import example.com example.com.zone --replace # replaces all records not managed by keel keel dns export example.com > example.com.zone ``` Imports take BIND zone files (RFC 1035, `$ORIGIN` and `$TTL`; `$INCLUDE` and `$GENERATE` are rejected), up to 4 MiB. SOA, the apex NS records and DNSSEC records of the old provider are skipped and listed. Exports are sorted deterministically and contain no DNSSEC records, so they are easy to keep in Git. ## DNSSEC Zones are signed by default (ECDSA P-256, algorithm 13). To secure the domain, add the DS record at your registrar once the zone is active: ```bash keel dns dnssec example.com ``` ``` DNSSEC for example.com: signed_ds_missing DS record for your registrar (key tag, algorithm 13, digest type 2, digest): 2371 13 2 1F987CC6583E92DF0890718C4255C9D7B8B6F4C9D41E9FBE… ``` Some registrars ask for the DNSKEY instead; it is shown as well. Registries that scan CDS records (for example `.ch`, `.li`, `.se`, `.cz`) pick up the DS automatically. The state becomes `secure` when the DS at the parent matches; `ds_mismatch` means validating resolvers cannot resolve your domain – replace the DS with the one shown. Zone-signing keys roll over automatically every 90 days without any change at the registrar. A key-signing key rollover (`keel dns dnssec rollover example.com --ksk`) needs a new DS record. To turn DNSSEC off without breaking the domain, `keel dns dnssec disable example.com` publishes the delete signal and keeps signing until the DS is gone at the parent. `--force` (admin) switches off at once; the domain then fails for validating resolvers until you remove the DS. ## ACME DNS-01 and dynamic updates keel DNS accepts RFC 2136 dynamic updates signed with a TSIG key, so cert-manager, certbot, lego, acme.sh, Caddy, Traefik and external-dns work without a keel-specific plugin. ```bash keel dns tsig create example.com --acme ``` The key may only create TXT records under `_acme-challenge` (add `--name` to limit it to hostnames). The secret is shown once. The server is `update.dns.keel.run`, port 53, TCP only. cert-manager: ```yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt spec: acme: server: https://acme-v02.api.letsencrypt.org/directory privateKeySecretRef: { name: letsencrypt-account } solvers: - dns01: rfc2136: nameserver: update.dns.keel.run:53 tsigKeyName: tsig_01h….tsig.keeldns.net. tsigAlgorithm: HMACSHA256 tsigSecretSecretRef: { name: keel-tsig, key: secret } ``` certbot (`certbot-dns-rfc2136`), with `rfc2136.ini`: ```ini dns_rfc2136_server = update.dns.keel.run dns_rfc2136_port = 53 dns_rfc2136_name = tsig_01h….tsig.keeldns.net. dns_rfc2136_secret = dns_rfc2136_algorithm = HMAC-SHA256 ``` ```bash certbot certonly --dns-rfc2136 --dns-rfc2136-credentials rfc2136.ini -d example.com -d '*.example.com' ``` lego: ```bash RFC2136_NAMESERVER=update.dns.keel.run:53 RFC2136_TSIG_KEY=tsig_01h….tsig.keeldns.net. \ RFC2136_TSIG_SECRET= RFC2136_TSIG_ALGORITHM=hmac-sha256. \ lego --dns rfc2136 -d example.com -d '*.example.com' --email you@example.com run ``` ACME TXT records older than 24 hours are removed automatically. List and delete keys with `keel dns tsig list example.com` and `keel dns tsig rm tsig_…`. ## Analytics The dashboard and `keel dns analytics example.com --window 7d` show queries per hour by type and response code for the last 30 days. keel does not give out resolver IP addresses. ## Agents Agents use the MCP tools `list_dns_zones`, `get_dns_zone`, `create_dns_zone`, `create_dns_record`, `set_dns_record` and the others listed in [Agents and MCP](/docs/agents). Creating zones and records needs the `dns:write` permission; deleting a zone needs `admin`. Replacing or deleting records is destructive: the agent shows you the old and new records and needs your confirmation, and with [approvals](/docs/agents) on, a person approves the change in the dashboard. ## Limits | | Trial | Hobby | Pro | |---|---|---|---| | Zones | 1 | 10 | 100 | | RRsets per zone | 200 | 2,000 | 50,000 | | Records per RRset | 100 | 100 | 100 | | TSIG keys per zone | 2 | 5 | 20 | | New zones per day | 2 | 10 | 50 | ## Billing You pay per active zone and per million queries; every plan includes some zones and queries. Zones waiting for their delegation are free. If a payment fails, your zones keep being served for 14 days, so mail and websites of the domain keep working while you sort it out. See [pricing](/pricing) for the current prices. --- Source: https://keel.run/docs/mail.md # Mail keel.run hosts mailboxes for your own domains: IMAP, JMAP, POP3 and SMTP for every mail client, a webmail you sign in to with your keel account, aliases, catch-alls, forwarding, mailing lists, spam and virus filtering. Everything runs on keel's own mail servers in Germany; nobody at keel reads your mail, and no API – also not the one for agents – returns message content. Apps on keel.run can send mail too, with sending keys, and receive mail as webhooks: see [App mail](/docs/mail-sending). ## Add a domain ```bash keel mail domains add example.de # shows the records to create keel mail domains dns example.de --watch # checks every 30 s until the domain is active ``` In the dashboard: **Mail → Domains → Add domain**. **If the domain's zone is in [keel DNS](/docs/dns)** (same workspace), the domain is verified at once and keel writes every record itself as managed records (`managed_by: mail:mdom_…`). Nothing else to do: DKIM keys rotate, MTA-STS changes and new hosts all happen without you. If one of your own records blocks a managed one (for example an old MX), the domain shows a conflict with a hint. **Otherwise** create these records at your DNS provider (the dashboard and `keel mail domains dns` show the exact values with copy buttons): | Purpose | Name | Type | Value | |---|---|---|---| | Verification | `_keel-mail` | TXT | `keel-verify=…` | | Receiving | `@` | MX | `10 mx1.mail.keel.run.` and `10 mx2.mail.keel.run.` | | SPF | `@` | TXT | `v=spf1 include:_spf.mail.keel.run -all` (merge into an existing SPF record, never add a second one) | | DKIM | `keel-e1._domainkey`, `keel-e2._domainkey`, `keel-r1._domainkey`, `keel-r2._domainkey` | CNAME | `e1..dkim.mail.keel.run.` … | | DMARC (recommended) | `_dmarc` | TXT | `v=DMARC1; p=quarantine; …` | | MTA-STS, TLS reporting, autoconfig (recommended) | `_mta-sts`, `mta-sts`, `_smtp._tls`, `autoconfig`, `autodiscover`, SRV records | | as shown | The DKIM records are CNAMEs: keel rotates the keys every 6 months without any change on your side. keel checks the records every 6 hours; **Check now** (or `keel mail domains verify example.de`) checks at once. Each record gets a status (`ok`, `missing`, `wrong`, `conflict`) and a hint for the problem, for example "a second SPF record was found – only one is allowed". An unverified domain can be taken over by another workspace after 24 hours; a verified one never. ## Mailboxes ```bash keel mail mailbox create hallo@example.de --quota 10G --owner me keel mail app-password create hallo@example.de --name iphone # shown once ``` - A mailbox costs **€1.50 per month and includes 5 GB**. The storage is pooled: 5 GB × your mailboxes are included for the whole workspace, beyond that €0.10 per GB and month. - The **owner** (a member of the workspace) signs in to the webmail with their keel account. People without other rights get the workspace role `mail`: they see only their own mailboxes, create app passwords and set forwarding. - **App passwords** are what mail clients use (`kmp_…`, 24 random characters, shown once). Give each device its own, with scope `all`, `smtp-only` or `read-only`; revoking one ends its open sessions within seconds. Mailbox passwords chosen by people are off by default (workspace setting) because protocols like IMAP cannot do two-factor authentication. - **Options:** "File a copy of sent mail in Sent" (for clients that do not save sent mail themselves – most do, so it is off) and "POP3 deletes for good" (off: mail a POP3 client deletes goes to Trash). - Deleting a mailbox refuses its mail at once; its contents stay recoverable for 30 days. ### Mail clients Most clients set themselves up from the address (autoconfig, autodiscover and SRV records). Otherwise: | Protocol | Server | Port | |---|---|---| | IMAP | `imap.mail.keel.run` | 993 (TLS) | | SMTP | `smtp.mail.keel.run` | 465 (TLS) or 587 (STARTTLS) | | POP3 | `pop.mail.keel.run` | 995 (TLS) | | JMAP | `https://jmap.mail.keel.run/.well-known/jmap` | 443 | | ManageSieve | `sieve.mail.keel.run` | 4190 | The user name is always the full address, the password an app password. ### Webmail The webmail runs at `mail.keel.run`: sign in with your keel account (including passkeys and two-factor authentication) and every mailbox you own appears – no password is stored in the webmail. **Mail → Open webmail** in the dashboard links there. ## Aliases, catch-all, forwarding, lists ```bash keel mail alias add info@example.de --to hallo@example.de --send-as hallo@example.de keel mail catchall set example.de --to hallo@example.de keel mail forward set hallo@example.de --to privat@example.com --no-copy ``` - An alias delivers to up to 50 addresses (mailboxes, other aliases, external addresses); `--send-as` lets mailboxes send with it. - The **catch-all** (`*@example.de`) receives mail for every address without a mailbox, alias, list or route. Catch-alls attract spam, so their mail is filtered more strictly. - **Subaddressing** is on by default: `hallo+news@example.de` arrives at `hallo@`. - **Forwarding** to external addresses is rewritten with SRS and ARC-sealed, so SPF and DMARC still pass. Spam is never forwarded. Every change is audited and mailed to the mailbox owner – a quietly added forward is a typical sign of a taken-over account. - **Mailing lists** send a new message to each member with `List-Id` headers; who may write is `members`, `domain`, `anyone` or `moderated`. ## Spam, viruses and quarantine Incoming mail is checked during the SMTP session: SPF, DKIM, DMARC and ARC, keel's own reputation across all workspaces, content scoring and a virus scan. Mail is refused rather than bounced, so keel never sends backscatter. - From the **junk score** (default 6) mail goes to Junk; from the **quarantine score** (default 10) it is held in quarantine; from 15 it is refused. Change both under **Mail → Settings**. - Executable attachments are refused (or quarantined, per setting); Office documents with macros are quarantined. - Quarantined mail is kept for 30 days. Owners and admins see the sender's domain, size, score and the reason – never the subject – and can release (`keel mail quarantine release qmsg_…`) or delete it. Moving mail between Inbox and Junk in a client trains the filter for your workspace. ## Limits and deliverability | Limit | Hobby | Pro | |---|---|---| | Mail domains | 5 | 50 | | Mailboxes | 25 | 250 | | Aliases (incl. catch-alls) | 200 | 2000 | | Mailing lists / members per list | 5 / 500 | 50 / 5000 | | External recipients per day (all mailboxes) | 1000 | 10000 | | External recipients per hour and mailbox | 100 | 300 | | Recipients per message | 50 | 100 | | Largest message sent | 25 MB | 50 MB | | Largest mailbox | 20480 MB | 102400 MB | Incoming messages may be up to 50 MB. New workspaces send to at most 50 external recipients per day for their first 14 days. A downgrade is refused while the workspace has more mail domains, mailboxes or aliases than the target plan allows (`keel billing plans` lists what to reduce). keel computes a sending reputation for every workspace from hard bounces, complaints and outbound spam (**Mail → Reputation & limits**, `keel mail reputation`). Above the thresholds keel slows sending down or pauses it. A mailbox that looks compromised (new location plus unusual sending, many new recipients, a sudden external forward) gets a **sending hold**: only its sending stops, its app passwords are revoked, and the owners and the mailbox owner get an e-mail. Release it after creating new app passwords. Sending spam, phishing or bulk marketing mail breaks the [terms](/legal/agb) and leads to suspension. ## Billing suspension A workspace suspended for billing keeps **receiving mail for 30 days** – lost mail hurts more than a few days of storage – but logins and sending are refused with a clear message. After 30 days the mail servers answer "try again later", after 60 days they refuse mail. Data is kept until the workspace is closed. ## API, CLI and agents Everything above works through the API (`/v1/workspaces/{id}/mail/…`, `/v1/mail/…`, `/v1/mailboxes/…`, scopes `mail:read` and `mail:write`), the CLI (`keel mail --help`) and the [MCP tools](/docs/agents) (`list_mail_domains`, `create_mailbox`, …). There is deliberately no tool that sends or reads mail and none that hands out mailbox credentials. --- Source: https://keel.run/docs/mail-sending.md # App mail Apps send transactional mail – sign-up confirmations, password resets, receipts – with a **sending key**, over an HTTP API or SMTP. Delivery events (delivered, bounced, complained, …) arrive as **event webhooks**, and **inbound routes** post mail sent to an address of your domain to your app. App sending is enabled per workspace; ask support to enable it. There is no open- or click-tracking. | | Price | |---|---| | App mails (per recipient) | €0.40 per 1,000 | | Inbound route calls | €0.10 per 1,000 | App mails count against your plan: Hobby 50000 per month, Pro 500000 (more after a review). Newsletters and marketing mail are not allowed. ## Sending keys ```bash keel mail keys create --domain example.de --name shop ``` The key (`keelmail_…`) is shown once together with `MAIL_API_URL` and `SMTP_URL`. Store them as secret [variables](/docs/services) of your app. A key may only send from the verified domains or addresses it was created for. ### HTTP API ```bash curl https://send.mail.keel.run/v1/messages \ -H "Authorization: Bearer $MAIL_API_KEY" \ -H "Idempotency-Key: order-1234-receipt" \ -H "Content-Type: application/json" \ -d '{"from": "Shop ", "to": ["bob@example.com"], "subject": "Your order", "text": "Thanks for your order!", "tags": {"kind": "receipt"}}' ``` The answer (`202`) has the message ID (`msg_…`) and each recipient's status (`queued` or `suppressed`). `GET /v1/messages/{id}` shows the events. Up to 50 recipients per call; the same `Idempotency-Key` within 24 hours sends once. The OpenAPI description is at `https://send.mail.keel.run/openapi.json`. ### SMTP relay Use `SMTP_URL` (`smtps://:@smtp.mail.keel.run:465`) with any SMTP library: user name is the key ID (`mkey_…`), password the key. ## Message log and suppressions `keel mail log` (or **Mail → Log**) lists app mail with each recipient's status – metadata only, never subjects or content. Addresses that bounced hard or complained land on the **suppression list**; mail to them is not attempted (`suppressed`). Remove an address only when its owner asked for it: `keel mail suppressions remove bob@example.com`. Mailboxes are never affected by suppressions. ## Event webhooks ```bash keel mail webhooks add https://shop.keelrun.app/hooks/mail-events --events delivered,bounced,complained ``` Events: `queued`, `delivered`, `deferred`, `bounced` (`data.bounce` is `hard` or `soft`), `complained`, `rejected`, `suppressed`, `expired`, `route_delivered`, `route_failed`. Payload: ```json {"type": "bounced", "timestamp": "2026-11-18T10:06:00Z", "data": {"event_id": "evt_…", "message_id": "msg_…", "recipient": "bob@example.com", "tags": {"kind": "receipt"}, "bounce": "hard", "code": 550}} ``` Answer with any `2xx` within 10 seconds. Other answers are retried with backoff for 24 hours. ## Inbound routes ```bash keel mail routes add 'support+*@example.de' --url https://shop.keelrun.app/hooks/mail keel mail routes test support@example.de ``` A route is an address like a mailbox: `support@`, `support+*@` (every `support+anything@`) or `*@` (every address without a mailbox, alias or list). Mail to it is checked like mailbox mail (spam, viruses, DMARC); spam is discarded or quarantined, never posted. Optionally a mailbox gets a copy. The default mode `parsed` posts JSON with the envelope, headers, `from`, `to`, `cc`, `subject`, `text` and `html` (up to 1 MB each, `truncated` says so), `auth` (SPF, DKIM, DMARC, ARC results), `spam` and `attachments` with signed download links (valid 24 hours, like `raw_url` for the whole message). Mode `raw` posts the message itself as `message/rfc822`. After 24 hours of failed attempts the event `route_failed` is sent and the owners get an e-mail. Route URLs must be `https` and public: internal addresses are refused on every call. Apps on keel.run are reached through their public URL. ## Verify the signature Every call (event webhooks and routes) is signed per [Standard Webhooks](https://www.standardwebhooks.com/): headers `webhook-id`, `webhook-timestamp` and `webhook-signature` (`v1,`). The signature is HMAC-SHA256 with the secret (the part after `whsec_`, base64-decoded) over `..`. Check it on the raw body, refuse timestamps older than 5 minutes, and use `webhook-id` to ignore repeats. ```js import crypto from 'node:crypto'; export function verify(secret, headers, rawBody) { const id = headers['webhook-id'], ts = headers['webhook-timestamp'], sigs = headers['webhook-signature'] ?? ''; if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64'); const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64'); return sigs.split(' ').some((s) => { const got = s.replace(/^v1,/, ''); return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want)); }); } ``` ```go func verify(secret string, h http.Header, body []byte) bool { key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_")) ts, err2 := strconv.ParseInt(h.Get("webhook-timestamp"), 10, 64) if err != nil || err2 != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 { return false } mac := hmac.New(sha256.New, key) fmt.Fprintf(mac, "%s.%d.", h.Get("webhook-id"), ts) mac.Write(body) want := "v1," + base64.StdEncoding.EncodeToString(mac.Sum(nil)) for _, s := range strings.Fields(h.Get("webhook-signature")) { if hmac.Equal([]byte(s), []byte(want)) { return true } } return false } ``` Libraries for Standard Webhooks (`standardwebhooks` for Node, Python, Go, Ruby, …) work as well. The secret is shown when the webhook or route is created; you can also bring your own for a route (`secret: "whsec_…"`). --- Source: https://keel.run/docs/agents.md # Agents and MCP keel.run treats coding agents such as Claude Code as first-class users: an agent can do everything a person can – but only what you allow, and everything it does is in the audit log. | Way | For | Sign-in | |---|---|---| | **MCP server** `https://mcp.keel.run/mcp` | agents with MCP support (Claude Code, Claude Desktop, Cursor, …) | OAuth 2.1 in the browser, with a consent page | | **CLI** `keel` | terminals, scripts, CI, agents with a shell | `keel login` or `KEEL_TOKEN` | | **API** `https://api.keel.run/v1` | everything else | `Authorization: Bearer keel_…` | Agents use the CLI only with an agent token: create one with `keel tokens create --kind agent --scopes read,deploy` (or in the dashboard) and give the agent `KEEL_TOKEN=keel_agent_…`. When `CLAUDECODE` or `KEEL_AGENT` is set, the CLI refuses personal tokens and your own `keel login`, so the workspace's approval rules always apply to agents. ## Connect Claude Code ```bash claude mcp add --transport http keel https://mcp.keel.run/mcp ``` On the first tool call (or with `/mcp` → *Authenticate*), Claude Code opens your browser. Sign in to keel.run and choose: - the **workspace** – a connection always belongs to exactly one workspace, - optionally some **projects** – empty means all projects, - the **permissions** (scopes, see below) – preselected is what the client asks for; `admin` is never preselected, - the **expiry** – 1, 7, 30 or 90 days. The agent then gets an access token (`keel_agent_…`, valid for one hour) and a refresh token (30 days, at most until the expiry you chose). The refresh token changes on every use; if an old refresh token is ever used again, keel.run revokes the whole connection, because that means it was stolen. To disconnect, revoke the token "Claude Code (OAuth)" in the dashboard under **Settings → Tokens**, or run `claude mcp remove keel`. ### Other MCP clients Any client with Streamable HTTP and OAuth (dynamic client registration and PKCE) works. Clients without OAuth can send an agent token created in the dashboard as a header: ```bash claude mcp add --transport http keel https://mcp.keel.run/mcp --header "Authorization: Bearer keel_agent_…" ``` The MCP server accepts only agent tokens (`keel_agent_…`), not personal or CI tokens. ## Tools | Tool | Scope | Purpose | |---|---|---| | `list_projects` | `read` | projects with environments and services – start here to find IDs | | `get_service` | `read` | a service, its latest deployments, runtime status and domains | | `list_deployments` | `read` | deployments, newest first, paged with `cursor` | | `get_deployment` | `read` (+ `logs:read` for `log_lines`) | a deployment's status, optionally the end of its build log | | `diagnose_deployment` | `logs:read` | why a deployment failed or is unhealthy: phase, cause (e.g. `port_mismatch`, `missing_env_var`), relevant log lines, concrete fixes | | `get_logs` | `logs:read` | runtime or build logs, at most 500 lines, with a filter | | `list_databases` | `read` | databases of an environment | | `list_previews` | `read` | preview environments of a project's pull requests, with status and URLs | | `deploy_service` | `deploy` | deploy the branch head, a commit or an upload (`upload_id`); waits up to `wait_seconds` and returns the diagnosis of a failure | | `deploy_upload` | `deploy` | deploy a local directory: returns the CLI command and optionally a one-time upload URL | | `rollback_service` | `deploy` | go back to an earlier deployment (default: the previous one) | | `restart_service` | `deploy` | restart the instances | | `set_variables` | `config:write` (+ `deploy` to roll out) | set or delete variables (`null` deletes) | | `update_service` | `config:write` + `deploy` | change port, health check, size, instances, start or release command, builder, Dockerfile, root, branch; redeploys | | `get_approval` | `read` | status of a request that waits for a person's approval | | `run_command` | `deploy` + `config:write` | run a command once with the service's image and variables (migrations, seeds); returns status, exit code and output | | `get_run` | `read` (+ `logs:read` and `config:write` for the output) | status, exit code and output of a one-off or cron run; output can contain secret values, without both permissions it is hidden (`output_redacted`) | | `list_runs` | `read` | runs of a service, newest first | | `create_database` | `databases:write` | create a Postgres database | | `get_database_url` | `databases:read` | connection URL with password | | `run_sql` | `databases:query` | one SQL statement in a read-only transaction, with a row limit | | `list_kv` | `read` | serverless Valkey (KV) databases of an environment | | `create_kv` | `databases:write` | create a KV database | | `get_kv_credentials` | `databases:read` | `rediss://` URL, REST URL and token (Upstash-compatible), internal URLs | | `add_domain` | `domains:write` | add a custom domain; returns the DNS records to create | | `list_dns_zones`, `get_dns_zone` | `read` | [keel DNS](/docs/dns) zones: status, nameservers for the registrar, delegation check, DNSSEC state, issues | | `list_dns_records`, `export_dns_zone` | `read` | the records (RRsets) of a zone, or the zone as a BIND zone file | | `get_dnssec_ds` | `read` | DNSSEC state and the DS record for the registrar | | `test_dns_query` | `read` | ask keel's answer engine about the current zone, also before delegation | | `create_dns_zone`, `verify_dns_zone` | `dns:write` | create a zone (returns the nameservers and what to tell the user), check the delegation now | | `create_dns_record` | `dns:write` | add a new RRset (fails if it exists) | | `import_dns_zone` | `dns:write` | import a zone file; mode `add` directly, mode `replace` **destructive**, two steps | | `set_dns_record`, `delete_dns_record`, `apply_dns_changes` | `dns:write` | **destructive**, two steps; the preview shows the old and the new records | | `delete_dns_zone` | `admin` | **destructive**, two steps | | `delete_service` | `admin` | **destructive**, two steps | | `delete_database` | `admin` | **destructive**, two steps | | `delete_kv` | `admin` | **destructive**, two steps | | `list_mail_domains`, `get_mail_dns_status` | `mail:read` | [mail](/docs/mail) domains with their status; the DNS records with check results and a hint per problem | | `list_mailboxes`, `get_mail_log`, `get_mail_reputation` | `mail:read` | mailboxes (never their mail), the message log of app mail (metadata only), sending reputation, holds and limits | | `create_mail_domain`, `create_mailbox`, `create_mail_alias` | `mail:write` | add a domain (verified and configured at once when its zone is in keel DNS), a mailbox, an alias or the catch-all (`*`) | | `set_mail_forwarding` | `mail:write` | forward a mailbox; needs approval where approvals are on, and the mailbox owner is notified | | `create_sending_key` | `mail:write` | a key for app mail, returned once (store it as secret variables) | | `delete_mailbox`, `delete_mail_domain` | `admin` | **destructive**, two steps | | `reset_mailbox_password` | `mail:write` | **destructive**, two steps: removes the mailbox password and revokes every app password; the agent gets no new credential | No tool sends mail, reads mail or hands out mailbox credentials: a prompt injection could otherwise send spam or read your mailboxes. A typical loop: `list_projects` → `deploy_service` → poll `get_deployment` until `active` or `failed` → on failure `diagnose_deployment` → apply a suggestion (`update_service`, `set_variables`, or fix the code) → deploy again. A workspace can also require a person's approval for actions of agent tokens (every deletion, restores and credential rotations, or every change). Held requests answer `202` with an `approval_id`; poll `get_approval` until the request ran, and never send it again. ### Confirmations for destructive actions Destructive tools never delete on the first call. They return a preview of what would be deleted and a `confirmation_token`. Only a second call with exactly this token deletes. The token is valid for 5 minutes, works once, and is bound to the action, the target, the person and the workspace. For DNS changes it is also bound to the exact records and to the zone's version at the time of the preview: if the zone changed in between, the agent has to ask again. The tool descriptions tell the agent to show you the preview and to confirm only after you agreed. Errors carry a code and a hint, for example: `missing_scope: … Hint: ask the user to reconnect keel.run and tick "deploy"`. ## Scopes | Scope | Allows | |---|---| | `read` | read projects, services, deployments and settings | | `logs:read` | build and runtime logs | | `deploy` | deploy, roll back, restart | | `config:write` | change configuration and variables, read secret values, start runs and (with `logs:read`) read their output | | `databases:read` | databases and connection URLs (with password) | | `databases:write` | create and change databases | | `databases:query` | read-only SQL | | `domains:write` | add and remove domains | | `dns:write` | keel DNS: create and change zones and records (deleting a zone needs `admin`) | | `billing:read` | billing and usage | | `admin` | everything, including deletion and token management (destructive) | A good default for an agent that ships code: `read`, `logs:read`, `deploy`. Add `config:write` if it should manage variables, `databases:query` if it should look at data. A connection never has more rights than the person who granted it, and keel.run checks the person's current role whenever the token is refreshed. If the person loses access to the workspace, the connection ends. ## The CLI for agents Agents with a shell can use the CLI instead of MCP: - Every command takes `--json`: stable JSON on stdout, progress and logs on stderr. Errors are `{"error": {"code", "status", "detail", "hint", "request_id", "exit_code"}}` on stderr. - Without a terminal, commands that would ask for confirmation fail with exit code 2 unless you pass `--yes`. - Exit codes: 0 ok, 1 error, 2 usage or not linked, 3 not logged in, 4 forbidden (role, scope, plan, billing), 5 not found, 6 invalid or conflict, 7 temporary (retry later), 8 deployment failed, 130 interrupted. See the [CLI reference](/docs/cli). ## Docs for agents - Every docs page is available as Markdown at its URL plus `.md`, e.g. [/docs/agents.md](/docs/agents.md). - [/llms.txt](/llms.txt) summarizes keel.run for language models and links every page. - [/llms-full.txt](/llms-full.txt) contains the whole documentation in one file. ## Security - OAuth 2.1 with the authorization code flow and PKCE (S256) only; public clients without secrets; exact redirect URIs (https, or loopback where only the port may differ); codes are valid for 60 seconds and once. - Tokens for the MCP server are bound to `https://mcp.keel.run/mcp` (RFC 8707 resource indicators). The MCP server refuses tokens for other resources, and the API refuses MCP tokens that do not come through the MCP server. - The consent page is protected against CSRF and framing and runs no scripts. - Codes, refresh tokens and tokens are stored as hashes. Creating, refreshing and revoking is recorded in the audit log with the client's name. - Dynamically registered clients are rate-limited per IP address and removed after 90 days without use. --- Source: https://keel.run/docs/billing.md # Billing and limits keel.run has no free tier. Every plan has a small base price that includes usage of the same value; beyond that, usage is billed by the hour. All prices are in euros and **include VAT**. The [pricing page](/pricing) has a calculator. ## Plans | | Hobby | Pro | |---|---|---| | Base price per month | €5 | €20 | | Usage included | €5 | €20 | | Projects | 10 | 50 | | Services | 20 | 100 | | Databases | 5 | 25 | | Instances per service | 3 | 10 | | Log retention | 7 days | 30 days | | Build time limit | 20 min | 30 min | | Concurrent builds | 1 | 3 | | `xl` instances, HA databases (`pg-m-ha`) | – | ✓ | ## Trial The first subscription of a workspace starts with a **7-day trial** that includes **€5 of usage**. A card is required to start it – this keeps out the abuse that free plans attract. You are not charged during the trial, and usage in the trial is never billed. - If the trial credit is used up before the trial ends, your apps pause until you end the trial. - End the trial early in the dashboard under **Billing** or with `POST /v1/workspaces/{id}/billing/end-trial`; the paid plan starts at once. - Cancel before the trial ends and you pay nothing. Without a subscription, a workspace can create projects but no services, deployments or databases (the API answers `402 billing_required`). New workspaces have lower limits for their first 14 days: at most 2 services and instance sizes up to `m`. ## Usage prices | Resource | Price per month | Billed by | |---|---|---| | vCPU | €10 per vCPU | actual use, measured every minute | | RAM | €7 per GB | reservation: instance size × instances, or the database plan's RAM × instances | | Database storage | €0.20 per GB | size of the database volumes, also while paused | | Backup storage | €0.05 per GB | size of the backups | | Mailbox | €1.50 per mailbox | each mailbox, including 5 GB of storage pooled across the workspace | | Mail storage | €0.10 per GB | storage above 5 GB × mailboxes | | App mails | €0.40 per 1,000 | recipients of mail sent with [sending keys](/docs/mail-sending) (not monthly) | | Inbound mail webhooks | €0.10 per 1,000 | mails posted to your app by inbound routes (not monthly) | Monthly prices are converted to hourly ones with 730 hours per month. Usage is summed per hour, and only the part above your plan's included amount is billed at the end of the billing period. **Example:** an app with size `s` (512 MB) that runs all month and uses 5 % of a vCPU on average costs 0.5 × €7 + 0.05 × €10 = €4 of usage. That is within the €5 included in Hobby, so the month costs €5. Your current usage and a projection for the period are in the dashboard under **Billing** and in the API (`GET /v1/workspaces/{id}/usage`, scope `billing:read`). ## Spend limits A spend limit caps what a workspace can cost per billing period: the base price plus usage above the included amount. - At **80 %**, the workspace owners get an e-mail (once per period). - At **100 %**, the workspace is **suspended**: apps are scaled to zero and databases are paused. **No data is deleted**, and storage keeps being billed. - Raise or remove the limit at any time – also while suspended – and everything starts again right away. A new billing period lifts the suspension too. ```bash curl -X PUT https://api.keel.run/v1/workspaces/ws_…/billing/spend-limit \ -H "Authorization: Bearer $KEEL_TOKEN" -H "Content-Type: application/json" \ -d '{"spend_limit_cents": 2500}' ``` While a workspace is at its limit, actions that would cost more (new services, deployments, databases, scaling, domains) answer `402 spend_limit_reached`. Deleting things always works. ## Payment Payments are processed by Stripe. Invoices include VAT; businesses in the EU with a valid VAT ID are billed under the reverse-charge procedure. Change your card, download invoices or cancel in the billing portal, which you open from **Billing** in the dashboard. If a payment fails, Stripe retries it. If it is still unpaid 7 days after the first failure, the workspace is suspended in the same way as at a spend limit, until the invoice is paid. --- Source: https://keel.run/docs/security.md # Security The rule behind keel.run's design: **no customer can see, reach or slow down another customer.** This page explains how, and where your data lives. ## Where your data is - **Servers:** Hetzner data centers in Germany and Finland. No US hyperscaler is in the data path. - **Backups:** Hetzner Object Storage in the EU. - **Payments:** Stripe processes card payments; keel.run never sees your card number. - **E-mail:** sign-in links and billing notices are sent through a transactional e-mail provider, named in the data processing agreement. The [data processing agreement](/legal/avv) lists every subprocessor. ## Tenant isolation - **Sandboxed containers.** Every app runs in a [gVisor](https://gvisor.dev) sandbox, a user-space kernel between your code and the host. Pods run without host networking, host paths or privileges, and without access to the cluster API. - **One network per environment.** Each environment is its own Kubernetes namespace with network policies: services accept traffic only from their own environment and the platform's ingress, and they can reach their own environment and the internet – not other customers and not internal platform services. Outgoing mail (port 25) is blocked. - **Resource limits.** Each environment has quotas for CPU, memory, storage and pods derived from your plan. RAM is reserved, never overcommitted, so a neighbor cannot push your app out of memory. - **Isolated builds.** Each build runs in its own short-lived job with rootless BuildKit in a user namespace. The repository token exists only inside the clone step and is deleted afterwards. Builds can reach the internet, but not private networks. - **Private registry per workspace.** Images are pushed with a credential that is valid for one build and one service, and pulled with a credential of your workspace only. Images are deployed by digest. - **Separate domains.** Customer apps run under `keelrun.app`, which is on the Public Suffix List, never under `keel.run`. Apps cannot set cookies for each other or for keel.run. - **Databases.** Each database is its own Postgres cluster with its own credentials and no superuser. It accepts connections only from its own environment and from keel.run's database proxy, which requires TLS. ## Secrets and encryption - **Variables and database passwords** are encrypted with a key per workspace (envelope encryption with a platform master key) and bound to the row they belong to, so a value cannot be moved to another place in the database. - Secret values are hidden in listings. Revealing them needs the `config:write` scope and is recorded in the audit log, as is every read of a database password. - **Tokens, OAuth codes and refresh tokens** are stored only as hashes. - **In transit:** TLS 1.3 for keel.run's own endpoints, HTTPS with automatic certificates for every app, TLS for every external database connection. - **At rest:** databases live on local NVMe volumes on dedicated servers; backups are written to object storage. ## Accounts, tokens and agents - Sign-in with GitHub, GitLab, Codeberg or a one-time e-mail link; no passwords to steal. - Sessions are HttpOnly cookies; the API checks the origin of every state-changing browser request. - API tokens belong to one workspace, can be limited to projects and scopes, and never have more rights than the person who created them. Agent tokens always expire. - Destructive actions by agents need a second call with a short-lived confirmation token. - Every change is recorded in the workspace's **audit log** with the person, token and client that made it. Details: [Agents and MCP](/docs/agents#security) and [API authentication](/docs/api#authentication). ## Backups Databases are backed up daily, and the write-ahead log is archived continuously, so you can restore to any point in your plan's recovery window. Restores always create a new database. ## Reporting a vulnerability Please report security issues and abuse of the platform to `abuse@keel.run`, with enough detail to reproduce the issue. Do not access other customers' data while testing. --- Source: https://keel.run/docs/cli.md # CLI reference This page is generated from the `keel` command tree (`make site-gen`), so it matches the CLI of this release. Run `keel --help` for the same text in your terminal. ## keel ```text keel is the command line interface of keel.run, the EU developer cloud. Every command supports --json for machine-readable output. Exit codes: 0 ok, 1 error, 2 usage/not linked, 3 not logged in, 4 forbidden, 5 not found, 6 invalid/conflict, 7 temporary (retry), 8 deployment failed, 9 waiting for approval; keel run exits with the command's exit code. Usage: keel [command] Available Commands: approvals List requests of agents that wait for (or got) a person's approval billing Plan and costs of the workspace (needs billing:read; changes need admin) completion Generate the autocompletion script for the specified shell config Show the service's source, build and runtime settings db Manage databases of the environment deploy Upload and deploy the linked directory (or a git commit with --git) diagnose Explain why a deployment failed or is unhealthy, with concrete fixes dns Manage keel DNS zones, records, DNSSEC and TSIG keys domains Manage the service's domains env Manage environment variables help Help about any command kv Manage serverless Valkey (Redis-compatible) databases of the environment link Link this directory to a project, environment and service login Log in (opens the browser; --token for CI) logout Revoke and forget the stored token logs Show runtime logs of the service, or a deployment's build log mail Manage mail domains, mailboxes, aliases and app sending open Open the linked service (or a deployment) in the dashboard previews Preview environments of pull requests projects List the projects of the workspace rollback Roll back to an earlier deployment (default: the previous one) run Run a command once in the service's image (like heroku run) runs List one-off and scheduled runs of the service services List the services of the environment status Show the linked service: deployments, runtime and domains tokens Manage API tokens of the workspace (needs admin) version Show the CLI version and whether a newer release is available whoami Show the logged-in user, token scopes and linked service Flags: --api-url string API URL (env KEEL_API_URL, default https://api.keel.run) -e, --environment string environment ID or name (default: linked) -h, --help help for keel --json print machine-readable JSON --project string project ID or name (default: linked) -s, --service string service ID or name (default: linked) -v, --version version for keel --workspace string workspace ID (env KEEL_WORKSPACE; default: linked or only workspace) -y, --yes do not ask for confirmation (non-interactive) Use "keel [command] --help" for more information about a command. ``` ## keel approvals ```text List requests of agents that wait for (or got) a person's approval Usage: keel approvals [flags] keel approvals [command] Available Commands: get Show an approval; --wait polls until a person decided Flags: -h, --help help for approvals --status string only this status: pending, executed, failed, denied, expired Use "keel approvals [command] --help" for more information about a command. ``` ### keel approvals get ```text Approvals are decided by people in the dashboard. With --wait the command polls until the request was executed, failed, denied or expired. Exit codes: 0 executed, 4 denied, 6 failed, 9 still pending (or expired). Usage: keel approvals get [flags] Flags: -h, --help help for get --wait duration poll until decided, at most this long (e.g. 10m) ``` ## keel billing ```text Plan and costs of the workspace (needs billing:read; changes need admin) Usage: keel billing [command] Available Commands: plan Change the plan (upgrades are charged prorated now, downgrades credited on the next invoice) plans List the plans, their limits and what blocks a downgrade status Show the plan, subscription and the cost of this period Flags: -h, --help help for billing Use "keel billing [command] --help" for more information about a command. ``` ### keel billing plan ```text Change the workspace's plan in place. An upgrade charges the prorated difference at once; a downgrade credits it on the next invoice and is refused while the workspace uses more than the smaller plan allows (the error lists what to reduce). The plan changes once the payment provider confirms it; --wait waits for that. Usage: keel billing plan hobby|pro [flags] Flags: -h, --help help for plan --wait wait until the new plan is active ``` ### keel billing plans ```text List the plans, their limits and what blocks a downgrade Usage: keel billing plans [flags] Flags: -h, --help help for plans ``` ### keel billing status ```text Show the plan, subscription and the cost of this period Usage: keel billing status [flags] Flags: -h, --help help for status ``` ## keel config ```text Show the service's source, build and runtime settings Usage: keel config [flags] keel config [command] Available Commands: set Change settings (redeploys the service) Flags: -h, --help help for config Use "keel config [command] --help" for more information about a command. ``` ### keel config set ```text Changes source, build or runtime settings of the service; only the flags you pass change. Changing source or build starts a new build, runtime changes roll out the running image again. Examples: keel config set --port 3000 keel config set --healthcheck /healthz --size m keel config set --builder railpack keel config set --start "" # use the image's own command Usage: keel config set [flags] Flags: --branch string branch to deploy --builder string auto, dockerfile or railpack --dockerfile string path of the Dockerfile, relative to the build root --healthcheck string HTTP path for readiness checks; "" checks the TCP port only -h, --help help for set --image string container image (image sources only) --instances int number of instances --port int port the app listens on (also passed as PORT) --release-command string command run before each rollout, e.g. migrations --root string directory in the repository to build; "" for the repository root --size string instance size: xs, s, m, l, xl --start string start command; "" uses the image's own ``` ## keel db ```text Manage databases of the environment Usage: keel db [command] Available Commands: connect Open psql connected to the database create Create a database (default: postgres) list List databases url Print the connection URL (contains the password) Flags: -h, --help help for db Use "keel db [command] --help" for more information about a command. ``` ### keel db connect ```text Open psql connected to the database Usage: keel db connect NAME|ID [-- psql args] [flags] Flags: -h, --help help for connect ``` ### keel db create ```text Create a database (default: postgres) Usage: keel db create NAME [flags] Flags: --engine string database engine (default "postgres") -h, --help help for create --plan string plan: pg-xs, pg-s (default), pg-m, pg-m-ha --storage int storage in GB (default: the plan's) --version string Postgres major version, 17 or 18 (default: latest) ``` ### keel db list ```text List databases Usage: keel db list [flags] Flags: -h, --help help for list ``` ### keel db url ```text Print the connection URL (contains the password) Usage: keel db url NAME|ID [flags] Flags: -h, --help help for url ``` ## keel deploy ```text In a linked directory, uploads the working tree and deploys it: files ignored by .gitignore are left out, as are .git, .env* files, node_modules and .keel (re-include them with negations such as !.env.production in a .keelignore). --dry-run lists what would be uploaded. Limits: 200 MiB compressed, 1 GiB, 50,000 files. --git (or --commit) deploys the service's branch head (or a commit) instead; services from a container image deploy their image again. Outside a linked directory, git services deploy from git and upload services upload the current directory (or --dir). With --watch (default on a terminal), streams the build and release log and waits until the deployment is active (exit 0) or failed (exit 8). With --json, the log goes to stderr and the final deployment to stdout. Usage: keel deploy [flags] Flags: --commit string deploy this commit from git (implies --git) --dir string upload this directory (default: the linked directory) --dry-run list the files that would be uploaded, upload nothing --git deploy the head of the service's branch from git instead of uploading -h, --help help for deploy --timeout duration how long --watch waits (default 30m0s) -w, --watch stream the build log and wait for the result (default on a terminal) ``` ## keel diagnose ```text Prints the phase (build, release, rollout, runtime), a machine-readable cause (e.g. port_mismatch, missing_env_var, oom_killed), the most relevant log lines (secrets masked) and suggestions with the exact command to run. Without an argument it diagnoses the newest deployment of the linked service. Needs the logs:read scope. Usage: keel diagnose [deployment] [flags] Flags: -h, --help help for diagnose ``` ## keel dns ```text keel DNS hosts the zones of your domains on keel's nameservers. Create a zone, set the four nameservers it shows at your registrar, and the zone becomes active once the delegation matches. Zones are given by name (example.com) or ID (zone_…); record names are relative to the zone (www, @ for the apex). Usage: keel dns [command] Available Commands: analytics Queries of a zone by type and response code dnssec Show the DNSSEC state and the DS record for your registrar export Print the zone as a BIND zone file (without DNSSEC records) import Import a BIND zone file (- reads stdin) query Ask keel's answer engine about the current zone (also before delegation) record Add, replace or remove an RRset (all records of one name and type) records List the records (RRsets) of a zone tsig TSIG keys for ACME DNS-01 and dynamic updates (RFC 2136) zone Create, show, verify, change and delete a zone zones List the DNS zones of the workspace Flags: -h, --help help for dns Use "keel dns [command] --help" for more information about a command. ``` ### keel dns analytics ```text Queries of a zone by type and response code Usage: keel dns analytics ZONE [flags] Flags: -h, --help help for analytics --window string 24h, 7d or 30d (default "24h") ``` ### keel dns dnssec ```text Show the DNSSEC state and the DS record for your registrar Usage: keel dns dnssec ZONE [flags] keel dns dnssec [command] Available Commands: disable Turn DNSSEC off in order: remove the DS at the registrar first, then the zone goes unsigned enable Sign the zone (then add the DS record at your registrar) rollover Start a key rollover (KSK: you must update the DS at your registrar) Flags: -h, --help help for dnssec Use "keel dns dnssec [command] --help" for more information about a command. ``` #### keel dns dnssec disable ```text Publishes the delete signal (CDS 0 3 0 AA==) and waits until the parent no longer has a DS record before serving the zone unsigned. --force (admin) switches off at once: the domain does not resolve for validating resolvers until the DS is removed. Usage: keel dns dnssec disable ZONE [flags] Flags: --force switch off at once (needs admin) -h, --help help for disable ``` #### keel dns dnssec enable ```text Sign the zone (then add the DS record at your registrar) Usage: keel dns dnssec enable ZONE [flags] Flags: -h, --help help for enable ``` #### keel dns dnssec rollover ```text Start a key rollover (KSK: you must update the DS at your registrar) Usage: keel dns dnssec rollover ZONE --zsk|--ksk [flags] Flags: -h, --help help for rollover --ksk roll the key-signing key (needs a new DS at the registrar) --zsk roll the zone-signing key (automatic, no registrar change) ``` ### keel dns export ```text Print the zone as a BIND zone file (without DNSSEC records) Usage: keel dns export ZONE [flags] Flags: -h, --help help for export ``` ### keel dns import ```text Adds the RRsets of the file that do not exist yet and reports conflicts. --replace instead replaces all records not managed by keel (destructive; asks first). SOA, apex NS, DNSSEC records and unsupported types are skipped and listed; $INCLUDE and $GENERATE are rejected. Usage: keel dns import ZONE FILE [flags] Flags: -h, --help help for import --replace replace all unmanaged records (destructive) ``` ### keel dns query ```text Ask keel's answer engine about the current zone (also before delegation) Usage: keel dns query ZONE NAME [TYPE] [flags] Flags: --dnssec set the DO bit (include signatures) -h, --help help for query ``` ### keel dns record ```text CONTENT is the record data in zone-file presentation format, one argument per record: `192.0.2.1`, `"10 mx1.example.com."` for MX, `"v=spf1 -all"` for TXT (quotes are added for TXT if missing). ALIAS takes a keel service (svc_…) or its generated hostname. Usage: keel dns record [command] Available Commands: add Create an RRset (fails if name and type already exist) rm Remove an RRset set Replace an RRset with these records (or create it) Flags: -h, --help help for record Use "keel dns record [command] --help" for more information about a command. ``` #### keel dns record add ```text Create an RRset (fails if name and type already exist) Usage: keel dns record add ZONE NAME TYPE CONTENT... [flags] Flags: --comment string a note shown in the dashboard -h, --help help for add --ttl int TTL in seconds (default: the zone's default TTL) ``` #### keel dns record rm ```text Remove an RRset Usage: keel dns record rm ZONE NAME TYPE [flags] Flags: -h, --help help for rm ``` #### keel dns record set ```text Replaces all records of NAME and TYPE. With an agent token and approvals for destructive actions, this waits for a person's approval (exit code 9). Usage: keel dns record set ZONE NAME TYPE CONTENT... [flags] Flags: -h, --help help for set --if-version keel dns zone show only apply if the zone is still at this version (from keel dns zone show) --ttl int TTL in seconds (default: the zone's default TTL) ``` ### keel dns records ```text List the records (RRsets) of a zone Usage: keel dns records ZONE [flags] Flags: -h, --help help for records --name string only this name (relative, @ for the apex) --type string only this type (A, AAAA, CNAME, MX, TXT, …) ``` ### keel dns tsig ```text TSIG keys for ACME DNS-01 and dynamic updates (RFC 2136) Usage: keel dns tsig [command] Available Commands: create Create a TSIG key; prints the secret once list List a zone's TSIG keys (without secrets) rm Delete a TSIG key (clients using it stop working) Flags: -h, --help help for tsig Use "keel dns tsig [command] --help" for more information about a command. ``` #### keel dns tsig create ```text --acme allows only TXT records under _acme-challenge (cert-manager, certbot, lego, acme.sh); --name limits it to these hostnames. The secret is shown once and cannot be retrieved again. Usage: keel dns tsig create ZONE --acme|--purpose update [flags] Flags: --acme key for ACME DNS-01 challenges only -h, --help help for create --name strings limit the key to these names (repeatable) --purpose string acme or update ``` #### keel dns tsig list ```text List a zone's TSIG keys (without secrets) Usage: keel dns tsig list ZONE [flags] Flags: -h, --help help for list ``` #### keel dns tsig rm ```text Delete a TSIG key (clients using it stop working) Usage: keel dns tsig rm TSIG_ID [flags] Flags: -h, --help help for rm ``` ### keel dns zone ```text Create, show, verify, change and delete a zone Usage: keel dns zone [command] Available Commands: create Create a zone; prints the nameservers to set at your registrar delete Delete a zone (needs a token with admin; its nameservers stop answering for it at once) show Show status, nameservers, DNSSEC and issues of a zone update Change the default TTL, the negative TTL or the project of a zone verify Check the delegation at the parent zone now Flags: -h, --help help for zone Use "keel dns zone [command] --help" for more information about a command. ``` #### keel dns zone create ```text Creates the zone in status pending_delegation and assigns it four nameservers. Records can be edited right away (and checked with `keel dns query`); the zone is served once your registrar delegates to exactly these nameservers. --import reads a BIND zone file (- for stdin); SOA, apex NS and DNSSEC records of the old provider are skipped. --project binds the zone to a project (project-restricted tokens only see zones of their projects). Usage: keel dns zone create NAME [flags] Flags: -h, --help help for create --import string BIND zone file to import (- reads stdin) --no-dnssec create the zone unsigned (DNSSEC is on by default) ``` #### keel dns zone delete ```text Delete a zone (needs a token with admin; its nameservers stop answering for it at once) Usage: keel dns zone delete ZONE [flags] Flags: -h, --help help for delete ``` #### keel dns zone show ```text Show status, nameservers, DNSSEC and issues of a zone Usage: keel dns zone show ZONE [flags] Flags: -h, --help help for show ``` #### keel dns zone update ```text Change the default TTL, the negative TTL or the project of a zone Usage: keel dns zone update ZONE [flags] Flags: --default-ttl int TTL for records without one, 60–604800 seconds -h, --help help for update --negative-ttl int how long resolvers cache "does not exist", 60–3600 seconds --zone-project string bind the zone to a project (ID or name, - to unbind) ``` #### keel dns zone verify ```text Asks the parent zone's nameservers which nameservers (and DS records) it delegates to, compares them with the zone's nameservers and prints the result. A matching delegation activates the zone. Usage: keel dns zone verify ZONE [flags] Flags: -h, --help help for verify ``` ### keel dns zones ```text List the DNS zones of the workspace Usage: keel dns zones [flags] Flags: -h, --help help for zones ``` ## keel domains ```text Manage the service's domains Usage: keel domains [command] Available Commands: add Add a custom domain list List domains remove Remove a domain Flags: -h, --help help for domains Use "keel domains [command] --help" for more information about a command. ``` ### keel domains add ```text Add a custom domain Usage: keel domains add HOSTNAME [flags] Flags: -h, --help help for add ``` ### keel domains list ```text List domains Usage: keel domains list [flags] Flags: -h, --help help for list ``` ### keel domains remove ```text Remove a domain Usage: keel domains remove HOSTNAME|ID [flags] Flags: -h, --help help for remove ``` ## keel env ```text Manage environment variables Usage: keel env [command] Available Commands: list List variables (environment-wide and the service's own) pull Write all variables, with secret values, to a .env file set Set variables (on the linked service, or environment-wide with --shared) unset Delete variables Flags: -h, --help help for env Use "keel env [command] --help" for more information about a command. ``` ### keel env list ```text Secret values are hidden unless --reveal is given (needs the config:write scope; the reveal is audited). Usage: keel env list [flags] Flags: -h, --help help for list --reveal show secret values --shared only environment-wide variables ``` ### keel env pull ```text Merges environment-wide and service variables (service wins) and writes them with values revealed (needs config:write; audited). Use -o - for stdout. Usage: keel env pull [flags] Flags: -h, --help help for pull -o, --output string file to write, or - for stdout (default ".env") ``` ### keel env set ```text Values are stored encrypted as secrets unless --plain. Running services are redeployed with the new values unless --no-redeploy. Use KEY=- to read a value from stdin. Usage: keel env set KEY=value... [flags] Flags: -h, --help help for set --no-redeploy do not roll out running services --plain store as non-secret (value visible in listings) --shared set environment-wide (all services) ``` ### keel env unset ```text Delete variables Usage: keel env unset KEY... [flags] Flags: -h, --help help for unset --no-redeploy do not roll out running services --shared delete environment-wide variables ``` ## keel kv ```text Manage serverless Valkey (Redis-compatible) databases of the environment Usage: keel kv [command] Available Commands: create Create a KV database delete Delete a KV database and its data (needs a token with admin) list List KV databases url Print the connection URL (contains the password) Flags: -h, --help help for kv Use "keel kv [command] --help" for more information about a command. ``` ### keel kv create ```text Create a KV database Usage: keel kv create NAME [flags] Flags: --allow-flushall allow FLUSHALL (needs a token with admin) --eviction string eviction policy: noeviction (default) or allkeys-lru (cache) -h, --help help for create --plan string plan: kv-s (256 MB, default), kv-m (1 GB), kv-l (4 GB, pro) ``` ### keel kv delete ```text Delete a KV database and its data (needs a token with admin) Usage: keel kv delete NAME|ID [flags] Flags: -h, --help help for delete ``` ### keel kv list ```text List KV databases Usage: keel kv list [flags] Flags: -h, --help help for list ``` ### keel kv url ```text Prints the rediss:// URL through the gateway (TLS). --rest prints the REST URL and token (@upstash/redis: url and token), --internal the URL for services in the cluster. Usage: keel kv url NAME|ID [flags] Flags: -h, --help help for url --internal print the URL for services inside the cluster --rest print the REST URL and token instead ``` ## keel link ```text Writes .keel/project.json. Pick interactively, or pass --workspace, --project, --environment and --service (IDs or names). Without a terminal, every choice that is not unique must be given as a flag. Usage: keel link [flags] Flags: -h, --help help for link ``` ## keel login ```text Log in to keel.run. Without flags, keel opens the browser to approve a token for this device; the token is stored in the OS keychain (or ~/.config/keel/credentials.json, mode 0600). In CI, set KEEL_TOKEN instead, or run `keel login --token -` and pass the token on stdin. Usage: keel login [flags] Flags: -h, --help help for login --name string device name shown on the approval page (default: hostname) --no-browser print the URL instead of opening the browser --token string use this API token instead of the browser ("-" reads it from stdin) ``` ## keel logout ```text Revoke and forget the stored token Usage: keel logout [flags] Flags: -h, --help help for logout ``` ## keel logs ```text Prints log lines (with --json: one JSON object per line). -f keeps following until interrupted. Usage: keel logs [flags] Flags: --deployment string show this deployment's build and release log -f, --follow keep streaming new lines -h, --help help for logs --since string how far back to start (e.g. 10m, 2h) (default "1h") --tail int runtime logs: lines per instance (default 100, max 1000) ``` ## keel mail ```text keel mail hosts mailboxes for your domains (IMAP, JMAP, POP3, SMTP, webmail) and sends app mail with sending keys. Domains are given by name (example.de) or ID (mdom_…), mailboxes by address or ID (mbx_…). Usage: keel mail [command] Available Commands: alias Add, list and remove aliases app-password Create, list and revoke app passwords of a mailbox catchall Set or remove the catch-all of a domain (an alias *@domain) domains List, add, check and remove mail domains forward Set or turn off the forwarding of a mailbox keys List, create and revoke sending keys for app mail log Message log of app mail (metadata only), newest first mailbox Create, list, change and delete mailboxes quarantine Quarantined mail (metadata only): list, release, delete reputation Sending reputation, holds and limits routes Inbound routes: post mail to an address to your app as a webhook suppressions Addresses app mail is not sent to (hard bounces, complaints) webhooks Event webhooks for app mail (delivered, bounced, complained, …) Flags: -h, --help help for mail Use "keel mail [command] --help" for more information about a command. ``` ### keel mail alias ```text Add, list and remove aliases Usage: keel mail alias [command] Aliases: alias, aliases Available Commands: add Add an alias list List the aliases of a domain remove Remove an alias Flags: -h, --help help for alias Use "keel mail alias [command] --help" for more information about a command. ``` #### keel mail alias add ```text Add an alias Usage: keel mail alias add ADDRESS --to TARGET[,TARGET] [flags] Flags: -h, --help help for add --send-as string mailboxes that may send as this address (comma-separated) --to string targets (comma-separated) ``` #### keel mail alias list ```text List the aliases of a domain Usage: keel mail alias list DOMAIN [flags] Flags: -h, --help help for list ``` #### keel mail alias remove ```text Remove an alias Usage: keel mail alias remove ADDRESS [flags] Flags: -h, --help help for remove ``` ### keel mail app-password ```text Create, list and revoke app passwords of a mailbox Usage: keel mail app-password [command] Aliases: app-password, app-passwords Available Commands: create Create an app password (shown once) list List app passwords revoke Revoke an app password (open sessions end) Flags: -h, --help help for app-password Use "keel mail app-password [command] --help" for more information about a command. ``` #### keel mail app-password create ```text Create an app password (shown once) Usage: keel mail app-password create ADDRESS [flags] Flags: -h, --help help for create --name string a name for the device, e.g. iphone --scope string all (default), smtp-only or read-only ``` #### keel mail app-password list ```text List app passwords Usage: keel mail app-password list ADDRESS [flags] Flags: -h, --help help for list ``` #### keel mail app-password revoke ```text Revoke an app password (open sessions end) Usage: keel mail app-password revoke ADDRESS ID [flags] Flags: -h, --help help for revoke ``` ### keel mail catchall ```text Set or remove the catch-all of a domain (an alias *@domain) Usage: keel mail catchall [command] Available Commands: remove Remove the catch-all set Deliver mail to unknown addresses of the domain to TARGET (catch-alls attract spam) Flags: -h, --help help for catchall Use "keel mail catchall [command] --help" for more information about a command. ``` #### keel mail catchall remove ```text Remove the catch-all Usage: keel mail catchall remove DOMAIN [flags] Flags: -h, --help help for remove ``` #### keel mail catchall set ```text Deliver mail to unknown addresses of the domain to TARGET (catch-alls attract spam) Usage: keel mail catchall set DOMAIN --to TARGET[,TARGET] [flags] Flags: -h, --help help for set --to string targets (comma-separated) ``` ### keel mail domains ```text List, add, check and remove mail domains Usage: keel mail domains [flags] keel mail domains [command] Available Commands: add Add a mail domain and show the DNS records it needs dns Show the DNS records of a domain with their status and hints remove Delete a mail domain with its mailboxes, aliases and routes (needs admin) verify Check the DNS records now Flags: -h, --help help for domains Use "keel mail domains [command] --help" for more information about a command. ``` #### keel mail domains add ```text Adds the domain. If its zone is in keel DNS (same workspace), keel verifies it and sets all records itself. Otherwise add the shown records at your DNS provider and run `keel mail domains verify DOMAIN`. Usage: keel mail domains add DOMAIN [flags] Flags: -h, --help help for add ``` #### keel mail domains dns ```text Show the DNS records of a domain with their status and hints Usage: keel mail domains dns DOMAIN [flags] Flags: --all also optional and app-sending records -h, --help help for dns --watch check every 30 seconds until the domain is active ``` #### keel mail domains remove ```text Delete a mail domain with its mailboxes, aliases and routes (needs admin) Usage: keel mail domains remove DOMAIN [flags] Flags: -h, --help help for remove ``` #### keel mail domains verify ```text Check the DNS records now Usage: keel mail domains verify DOMAIN [flags] Flags: -h, --help help for verify ``` ### keel mail forward ```text Set or turn off the forwarding of a mailbox Usage: keel mail forward [command] Available Commands: off Turn forwarding off set Forward incoming mail (audited and mailed to the mailbox owner; spam is never forwarded) Flags: -h, --help help for forward Use "keel mail forward [command] --help" for more information about a command. ``` #### keel mail forward off ```text Turn forwarding off Usage: keel mail forward off ADDRESS [flags] Flags: -h, --help help for off ``` #### keel mail forward set ```text Forward incoming mail (audited and mailed to the mailbox owner; spam is never forwarded) Usage: keel mail forward set ADDRESS --to TARGET[,TARGET] [flags] Flags: -h, --help help for set --keep-copy keep a copy in the mailbox (default) (default true) --no-copy do not keep a copy in the mailbox --to string targets (comma-separated, up to 10) ``` ### keel mail keys ```text List, create and revoke sending keys for app mail Usage: keel mail keys [flags] keel mail keys [command] Available Commands: create Create a sending key (shown once) revoke Revoke a sending key Flags: -h, --help help for keys Use "keel mail keys [command] --help" for more information about a command. ``` #### keel mail keys create ```text Create a sending key (shown once) Usage: keel mail keys create --domain DOMAIN [flags] Flags: --domain string sender domains or addresses (comma-separated) --environment-id string the environment that uses the key (env_…) -h, --help help for create --name string a name (default: the first domain) ``` #### keel mail keys revoke ```text Revoke a sending key Usage: keel mail keys revoke ID [flags] Flags: -h, --help help for revoke ``` ### keel mail log ```text Message log of app mail (metadata only), newest first Usage: keel mail log [flags] Flags: -f, --follow keep printing new messages and status changes -h, --help help for log --limit int number of messages (at most 200) (default 50) --status string only messages with a recipient in this state (delivered, bounced, deferred, …) --to string only messages to this address ``` ### keel mail mailbox ```text Create, list, change and delete mailboxes Usage: keel mail mailbox [command] Aliases: mailbox, mailboxes Available Commands: create Create a mailbox (1.50 € per month including 5 GB) delete Delete a mailbox (needs admin; contents recoverable for 30 days) list List mailboxes set Change quota, name, status or options of a mailbox Flags: -h, --help help for mailbox Use "keel mail mailbox [command] --help" for more information about a command. ``` #### keel mail mailbox create ```text Create a mailbox (1.50 € per month including 5 GB) Usage: keel mail mailbox create ADDRESS [flags] Flags: -h, --help help for create --name string display name --owner string the keel user who uses the mailbox: usr_… of a workspace member, or me --quota string quota, e.g. 10G (default 5G) ``` #### keel mail mailbox delete ```text Delete a mailbox (needs admin; contents recoverable for 30 days) Usage: keel mail mailbox delete ADDRESS [flags] Flags: -h, --help help for delete ``` #### keel mail mailbox list ```text List mailboxes Usage: keel mail mailbox list [flags] Flags: --domain string only this domain -h, --help help for list ``` #### keel mail mailbox set ```text Only the given flags change. --status disabled refuses logins and incoming mail. --save-sent true files a copy of SMTP-sent mail in Sent; --pop3-delete true makes POP3 delete for good. Usage: keel mail mailbox set ADDRESS [flags] Flags: -h, --help help for set --name string display name --pop3-delete string true: POP3 deletes for good instead of moving to Trash --quota string quota, e.g. 20G --save-sent string true: file a Sent copy of SMTP submissions --status string active or disabled ``` ### keel mail quarantine ```text Quarantined mail (metadata only): list, release, delete Usage: keel mail quarantine [command] Available Commands: delete Delete a quarantined message for good list List quarantined mail release Deliver a quarantined message to its recipient Flags: -h, --help help for quarantine Use "keel mail quarantine [command] --help" for more information about a command. ``` #### keel mail quarantine delete ```text Delete a quarantined message for good Usage: keel mail quarantine delete ID [flags] Flags: -h, --help help for delete ``` #### keel mail quarantine list ```text List quarantined mail Usage: keel mail quarantine list [flags] Flags: -h, --help help for list ``` #### keel mail quarantine release ```text Deliver a quarantined message to its recipient Usage: keel mail quarantine release ID [flags] Flags: -h, --help help for release ``` ### keel mail reputation ```text Sending reputation, holds and limits Usage: keel mail reputation [flags] Flags: -h, --help help for reputation ``` ### keel mail routes ```text Inbound routes: post mail to an address to your app as a webhook Usage: keel mail routes [flags] keel mail routes [command] Available Commands: add Add a route (ADDRESS may be support@d, support+*@d or *@d) remove Remove a route test Post a signed test payload to the route's URL Flags: -h, --help help for routes Use "keel mail routes [command] --help" for more information about a command. ``` #### keel mail routes add ```text Add a route (ADDRESS may be support@d, support+*@d or *@d) Usage: keel mail routes add ADDRESS --url URL [flags] Flags: --copy-to string also deliver a copy into this mailbox -h, --help help for add --quarantine-spam quarantine spam instead of discarding it --raw post the message as message/rfc822 instead of parsed JSON --url string https URL of your app ``` #### keel mail routes remove ```text Remove a route Usage: keel mail routes remove ADDRESS|ID [flags] Flags: -h, --help help for remove ``` #### keel mail routes test ```text Post a signed test payload to the route's URL Usage: keel mail routes test ADDRESS|ID [flags] Flags: -h, --help help for test ``` ### keel mail suppressions ```text Addresses app mail is not sent to (hard bounces, complaints) Usage: keel mail suppressions [command] Available Commands: list List suppressed addresses remove Send app mail to an address again (only when the recipient asked for it) Flags: -h, --help help for suppressions Use "keel mail suppressions [command] --help" for more information about a command. ``` #### keel mail suppressions list ```text List suppressed addresses Usage: keel mail suppressions list [flags] Flags: -h, --help help for list ``` #### keel mail suppressions remove ```text Send app mail to an address again (only when the recipient asked for it) Usage: keel mail suppressions remove ADDRESS [flags] Flags: -h, --help help for remove ``` ### keel mail webhooks ```text Event webhooks for app mail (delivered, bounced, complained, …) Usage: keel mail webhooks [flags] keel mail webhooks [command] Available Commands: add Add an event webhook (the signing secret is shown once) remove Delete an event webhook Flags: -h, --help help for webhooks Use "keel mail webhooks [command] --help" for more information about a command. ``` #### keel mail webhooks add ```text Add an event webhook (the signing secret is shown once) Usage: keel mail webhooks add URL [flags] Flags: --events string event types (comma-separated; default all) -h, --help help for add ``` #### keel mail webhooks remove ```text Delete an event webhook Usage: keel mail webhooks remove ID [flags] Flags: -h, --help help for remove ``` ## keel open ```text Open the linked service (or a deployment) in the dashboard Usage: keel open [flags] Flags: --deployment string open this deployment (dpl_…) -h, --help help for open ``` ## keel previews ```text Preview environments of pull requests Usage: keel previews [command] Available Commands: approve Approve the current commit of a forked pull request delete Delete a preview environment list List the project's previews Flags: -h, --help help for previews Use "keel previews [command] --help" for more information about a command. ``` ### keel previews approve ```text Forked pull requests never build on their own: their code would get the environment's variables. Review the commit first; approval covers exactly that commit, every new commit needs a new approval. Usage: keel previews approve PR|ID [flags] Flags: -h, --help help for approve --sha string the commit you reviewed (refuses if the pull request moved on) ``` ### keel previews delete ```text Delete a preview environment Usage: keel previews delete PR|ID [flags] Flags: -h, --help help for delete ``` ### keel previews list ```text List the project's previews Usage: keel previews list [flags] Flags: --all include closed previews -h, --help help for list ``` ## keel projects ```text List the projects of the workspace Usage: keel projects [flags] Flags: -h, --help help for projects ``` ## keel rollback ```text Roll back to an earlier deployment (default: the previous one) Usage: keel rollback [deployment] [flags] Flags: -h, --help help for rollback -w, --watch wait for the rollback to finish ``` ## keel run ```text Starts a one-off run with the image and variables of the service's active deployment, streams its output and exits with the command's exit code (124 when it timed out, 130 when cancelled, 8 when it could not start). Without a command, the service's start command runs (e.g. a cron service now). Several arguments are quoted for /bin/sh; a single argument is passed as a shell command line. Ctrl-C cancels the run unless --detach is set. With --json, output goes to stderr and the final run to stdout. Usage: keel run [flags] -- [args...] Flags: -d, --detach start the run and return without waiting -h, --help help for run --size string instance size xs, s, m, l or xl (default: the service's size) --timeout duration maximum run time, e.g. 30m (default 15m; the maximum depends on the plan) ``` ## keel runs ```text List one-off and scheduled runs of the service Usage: keel runs [flags] keel runs [command] Available Commands: cancel Stop a pending or running run list List runs (newest first) logs Show a run's log (needs logs:read and config:write) Flags: -h, --help help for runs --limit int number of runs (max 100) (default 20) Use "keel runs [command] --help" for more information about a command. ``` ### keel runs cancel ```text Stop a pending or running run Usage: keel runs cancel [flags] Flags: -h, --help help for cancel ``` ### keel runs list ```text List runs (newest first) Usage: keel runs list [flags] Flags: -h, --help help for list --limit int number of runs (max 100) (default 20) ``` ### keel runs logs ```text Show a run's log (needs logs:read and config:write) Usage: keel runs logs [flags] Flags: -f, --follow keep streaming until the run ends -h, --help help for logs ``` ## keel services ```text List the services of the environment Usage: keel services [flags] keel services [command] Available Commands: create Create a service (web, worker or cron) and deploy it Flags: -h, --help help for services Use "keel services [command] --help" for more information about a command. ``` ### keel services create ```text Creates a service in the environment and starts its first deployment. Kinds: web (default) serves HTTP on --port; worker runs continuously without a port; cron runs --start on --schedule (5 fields, e.g. "*/15 * * * *", or @hourly/@daily/@weekly/@monthly) in --timezone. Examples: keel services create api --image ghcr.io/acme/api:1 --port 3000 keel services create jobs --repo acme/app --kind worker --start "bin/worker" keel services create nightly --image ghcr.io/acme/app:1 --kind cron --schedule "0 3 * * *" --timezone Europe/Berlin --start "bin/report" Usage: keel services create [flags] Flags: --branch string branch to deploy (default main) --concurrency string cron: forbid (default) or replace a run that is still going --health-command string worker: liveness check command -h, --help help for create --image string container image, e.g. ghcr.io/acme/app:1.2 --instances int number of instances (web, worker) --kind string web (default), worker or cron --port int web: port the app listens on (default 8080) --provider string git provider: github, gitlab or forgejo (default "github") --release-command string command run before each rollout, e.g. migrations --repo string git repository owner/name (public, or through a connected provider) --retries int cron: retries of a failed run --root string directory inside the repository --schedule string cron: schedule, e.g. "*/15 * * * *" or @daily --size string instance size xs, s, m, l or xl (default s) --start string start command (cron: the command each run executes) --timeout duration cron: maximum run time (default 15m) --timezone string cron: IANA time zone of the schedule (default UTC) ``` ## keel status ```text Show the linked service: deployments, runtime and domains Usage: keel status [flags] Flags: -h, --help help for status ``` ## keel tokens ```text Manage API tokens of the workspace (needs admin) Usage: keel tokens [command] Available Commands: create Create a token (the secret is shown once) list List tokens revoke Revoke a token Flags: -h, --help help for tokens Use "keel tokens [command] --help" for more information about a command. ``` ### keel tokens create ```text Create a token (the secret is shown once) Usage: keel tokens create [flags] Flags: --expires-days int expiry in days (agent tokens: default 30) -h, --help help for create --kind string pat, svc (CI) or agent (default "pat") --name string token name --project strings limit to project IDs (repeatable) --scopes strings comma-separated scopes (default [read]) ``` ### keel tokens list ```text List tokens Usage: keel tokens list [flags] Flags: -h, --help help for list ``` ### keel tokens revoke ```text Revoke a token Usage: keel tokens revoke TOKEN_ID [flags] Flags: -h, --help help for revoke ``` ## keel version ```text Show the CLI version. Unless --no-check is given, keel also asks the API (GET /v1/meta, no login needed) which release keel.run runs and prints how to update when the CLI is older. The check never fails the command. Usage: keel version [flags] Flags: -h, --help help for version --no-check do not ask the API for the current release ``` ## keel whoami ```text Show the logged-in user, token scopes and linked service Usage: keel whoami [flags] Flags: -h, --help help for whoami ``` --- Source: https://keel.run/docs/api.md # API Everything in keel.run is available through a REST API with JSON. The dashboard, the CLI and the MCP server use the same public API, so anything you can do there, you can do with the API. - **Base URL:** `https://api.keel.run/v1` - **OpenAPI 3.1 document:** [`https://api.keel.run/openapi.json`](https://api.keel.run/openapi.json), generated from the server code - **Interactive reference:** [`https://api.keel.run/docs`](https://api.keel.run/docs) ## Authentication Send a token as a bearer token: ```bash curl https://api.keel.run/v1/me -H "Authorization: Bearer $KEEL_TOKEN" ``` | Token | Prefix | For | Created | |---|---|---|---| | Personal | `keel_pat_…` | you, in the CLI and scripts | by `keel login`, or in the dashboard | | Service | `keel_svc_…` | CI pipelines | in the dashboard or with `keel tokens create --kind svc` | | Agent | `keel_agent_…` | coding agents (MCP) | by the MCP OAuth flow, or in the dashboard; always expire | - A token belongs to **one workspace** and can be limited to **some projects**. - A token never has more rights than the person who created it, and it ends when that person loses access to the workspace. - Agent and service tokens cannot create other tokens. A personal token with `admin` can; the new token expires no later than its parent and is revoked with it. - Tokens are stored only as hashes. A new token is shown once. Revoke a token in the dashboard (**Settings → Tokens**), with `keel tokens revoke`, or with `POST /v1/oauth/revoke`. ## Scopes | Scope | Allows | |---|---| | `read` | read projects, services, deployments and settings | | `logs:read` | build and runtime logs | | `deploy` | deploy, roll back, restart | | `config:write` | change configuration and variables, reveal secret values, start runs and (with `logs:read`) read their output | | `databases:read` | databases and their connection URLs (with password) | | `databases:write` | create and change databases | | `databases:query` | read-only SQL | | `domains:write` | add and remove domains | | `dns:write` | keel DNS: create and change zones and records (deleting a zone needs `admin`) | | `billing:read` | billing and usage | | `admin` | everything, including deletion and token management | Members of a workspace (role `member`) cannot grant `admin` or `billing:read`. ## Errors Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details (`Content-Type: application/problem+json`) with a stable, machine-readable `code` and a `hint` that says what to do next: ```json { "title": "Forbidden", "status": 403, "code": "missing_scope", "detail": "Redeploying needs the deploy scope.", "hint": "Send redeploy=false or use a token with deploy." } ``` - **Unknown and forbidden resources both answer `404`**, so a token cannot probe what exists in other workspaces. - `402` with `code: billing_required` or `spend_limit_reached` means the action costs money and the workspace has no active plan or reached its spend limit. - `422` (`invalid`) carries an `errors` list with the fields that failed validation. - `5xx` responses never contain internals. Every response has an `X-Request-Id` header; include it when you contact support. ## Idempotency Send an `Idempotency-Key` header (up to 200 characters, e.g. a UUID) with every `POST`. If you repeat the request with the same key – after a timeout, say – the API returns the first response instead of doing the work twice, with the header `Idempotent-Replayed: true`. - The same key with a different body or path answers `422 idempotency_mismatch`. - Responses that contained a secret (a new token) are never stored. Repeating such a request answers `409 idempotency_replay_unavailable`: list the resource to see what the first request created. - `429` and `5xx` answers are not stored, so retry them with the same key. The CLI sends idempotency keys and retries network errors, `429` and `502`–`504` automatically. ## Pagination Lists that can grow (deployments, audit log) are sorted newest first and take `limit` and `before`: pass the ID of the oldest item you have as `before` to get the next page. A page shorter than `limit` is the last one. (The MCP tools wrap this as `cursor` and `next_cursor`.) ## Streams Logs are [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html): ```bash curl -N "https://api.keel.run/v1/services/svc_…/logs?since=1h&follow=true" -H "Authorization: Bearer $KEEL_TOKEN" curl -N "https://api.keel.run/v1/deployments/dpl_…/logs?follow=true" -H "Authorization: Bearer $KEEL_TOKEN" ``` - `event: log` with `{"ts", "stream", "instance", "line"}` for each line. - `event: end` when a finished deployment's log is complete. - A `: ping` comment every 15 seconds keeps proxies from closing the connection. - Runtime logs take `since` (e.g. `10m`, `1h`, `2d`; at most 7 days), `tail` (lines per instance, at most 1000), `deployment` and `instance`. - Streams end after 30 minutes; reconnect if you need more. At most 5 streams per token at a time. ## Rate limits Reads are limited per token (20 per second, bursts up to 200); writes have a stricter limit. Over the limit, the API answers `429` with `code: rate_limited`; wait and retry. ## Main resources | Resource | Endpoints | |---|---| | Me, workspaces | `GET /v1/me`, `GET/PATCH /v1/workspaces/{id}`, `GET /v1/workspaces/{id}/audit` | | Projects | `GET/POST /v1/workspaces/{id}/projects`, `GET/PATCH/DELETE /v1/projects/{id}` | | Environments | `GET/POST /v1/projects/{id}/environments`, `GET/DELETE /v1/environments/{id}` | | Services | `GET/POST /v1/environments/{id}/services`, `GET/PATCH/DELETE /v1/services/{id}`, `GET /v1/services/{id}/status`, `GET /v1/services/{id}/metrics`, `POST /v1/services/{id}/restart` | | Deployments | `GET/POST /v1/services/{id}/deployments`, `GET /v1/deployments/{id}`, `POST /v1/deployments/{id}/rollback` | | Variables | `GET/PATCH /v1/environments/{id}/variables` (`service_id` for a service's own) | | Databases | `GET/POST /v1/environments/{id}/databases`, `GET/PATCH/DELETE /v1/databases/{id}`, `GET /v1/databases/{id}/credentials`, `POST /v1/databases/{id}/link`, `POST /v1/databases/{id}/rotate-password`, `POST /v1/databases/{id}/query`, `GET /v1/databases/{id}/backups`, `POST /v1/databases/{id}/restore` | | Domains | `GET/POST /v1/services/{id}/domains`, `GET/DELETE /v1/domains/{id}`, `POST /v1/domains/{id}/verify` | | Tokens | `GET/POST /v1/workspaces/{id}/tokens`, `DELETE /v1/workspaces/{id}/tokens/{token_id}` | | Billing | `GET /v1/workspaces/{id}/billing`, `GET /v1/workspaces/{id}/usage`, `PUT /v1/workspaces/{id}/billing/spend-limit` | The [OpenAPI document](https://api.keel.run/openapi.json) has every field, every parameter and every error code.