# keel.run > keel.run is an EU developer cloud (servers in Germany): it builds and runs container apps from Git and offers managed Postgres. Coding agents are first-class users: everything is available through a remote MCP server, the `keel` CLI and a REST API, with scoped tokens, confirmation for destructive actions and a full audit log. Concepts: a workspace (`ws_…`) contains projects (`prj_…`); a project has environments (`env_…`, every project starts with `production`); an environment has services (`svc_…`, built from a Git repository, a container image, or a directory uploaded with `keel deploy`) Postgres databases (`db_…`) and serverless Valkey/Redis-compatible KV databases (`kv_…`, RESP over TLS and an Upstash-compatible REST API, billed per command). A service's `runtime.kind` is `web` (default, serves HTTP on `port`), `worker` (runs continuously, no port) or `cron` (runs `runtime.start` on `runtime.schedule`, 5 fields or `@hourly`/`@daily`…, in `runtime.timezone`). Every cron execution and every one-off command is a run (`run_…`) with status, exit code and log. Every deploy creates a deployment (`dpl_…`) with status queued → building → built → releasing → deploying → active (or failed/cancelled); the previous active deployment becomes superseded and can be rolled back to. Apps get `PORT` and their environment variables; services are reachable at `https://-[-].keelrun.app` or custom domains. ## Connect an agent (MCP) - MCP endpoint (Streamable HTTP): `https://mcp.keel.run/mcp` - Claude Code plugin (MCP server + deploy-to-keel skill + `/keel-deploy`, `/keel-logs`, `/keel-status`): `claude plugin marketplace add Keel-run/claude-code-plugin` and `claude plugin install keel@keel-run`. - Claude Code without the plugin: `claude mcp add --transport http keel https://mcp.keel.run/mcp`, then authenticate in the browser (OAuth 2.1 with dynamic client registration and PKCE). The user picks the workspace, optional projects, permissions and expiry. - Discovery: unauthenticated requests get `401` with `WWW-Authenticate: Bearer resource_metadata="https://mcp.keel.run/.well-known/oauth-protected-resource/mcp"`; the authorization server is `https://api.keel.run` (`/.well-known/oauth-authorization-server`). - Without OAuth: send an agent token from the dashboard as `Authorization: Bearer keel_agent_…`. Only agent tokens are accepted. Tools (scope in brackets): - `list_projects` [read]: projects with environments and services. Start here to find IDs. - `get_service` [read]: service settings, last 5 deployments, runtime status, domains. - `list_deployments` [read]: newest first; paginate with `cursor` = `next_cursor`. - `get_deployment` [read]: poll after deploys until `active` or `failed`; `log_lines` returns the end of the build log. - `diagnose_deployment` [logs:read]: why a deployment failed or is unhealthy: `phase` (build, release, rollout, runtime), `cause` (e.g. `dockerfile_missing`, `build_command_failed`, `oom_killed`, `crash_loop`, `port_mismatch`, `localhost_binding`, `healthcheck_failed`, `image_pull`, `quota_exceeded`, `release_command_failed`, `missing_env_var`, `timeout`), at most 30 relevant log lines (secrets masked), the relevant config, and `suggestions` with the exact `mcp` tool call, `cli` command and `api` request. Deterministic rules, no AI. - `update_service` [config:write + deploy]: change `port`, `healthcheck`, `size`, `instances`, `start`, `release_command`, `builder`, `dockerfile`, `root`, `branch`; only the fields passed change; redeploys. - `get_approval` [read]: poll a request that waits for a person's approval. - `get_logs` [logs:read]: runtime logs of a service (`since`, `filter`) or build log of a deployment; at most 500 lines, newest last. - `list_databases` [read], `create_database` [databases:write], `get_database_url` [databases:read], `run_sql` [databases:query, read-only transaction, row limit]. - `deploy_service` [deploy]: waits up to `wait_seconds` (default 30, max 110); a deployment that failed within the call comes with its `diagnosis`. - `rollback_service`, `restart_service` [deploy]. - `deploy_upload` [deploy]: deploy the user's local directory (uncommitted changes included). Returns the exact CLI command to run in the project directory (preferred) and a one-time upload URL + `curl` command for small archives without the CLI; then `deploy_service` with `upload_id`. - `run_command` [deploy + config:write]: run a command once with the service's image and variables (migrations, seeds, scripts); waits up to `wait_seconds` (default 60) and returns status, `exit_code` and the last output lines. `get_run` [read; output needs logs:read + config:write, since it can contain secret values; without them `output_redacted: true`] reads a run later, `list_runs` [read] lists one-off and cron runs. - `list_previews` [read]: preview environments of pull requests (state, status, URLs per service, database mode, note). - `list_kv` [read], `create_kv` [databases:write], `get_kv_credentials` [databases:read]: KV databases; services get `REDIS_URL`, `KV_REST_API_URL` and `KV_REST_API_TOKEN` by linking (`POST /v1/kv/{id}/link`). Admin commands (CONFIG, DEBUG, …) are refused; KEYS is rate-limited, use SCAN. - `set_variables` [config:write]: `{"KEY": "value"}` sets, `{"KEY": null}` deletes; running services are redeployed unless `redeploy: false`. - `add_domain` [domains:write]: returns the DNS records the user must create. - keel DNS (authoritative DNS hosting, `zone_…`; give zones by ID or name): `list_dns_zones`, `get_dns_zone`, `list_dns_records`, `export_dns_zone`, `get_dnssec_ds`, `test_dns_query` [read]; `create_dns_zone`, `verify_dns_zone`, `create_dns_record`, `import_dns_zone` (mode `add`) [dns:write]. A new zone is `pending_delegation` until the registrar delegates to exactly the four returned nameservers (four element names like `hydrogen.keeldns.net`; always use the ones returned): tell the user. Record data is zone-file presentation format; names are relative (`www`, `@`). Records with `managed_by` belong to keel (domains, services, mail). Check changes with `test_dns_query`. - `set_dns_record`, `delete_dns_record`, `apply_dns_changes`, `import_dns_zone` (mode `replace`) [dns:write, destructive] and `delete_dns_zone` [admin, destructive]: two steps; the preview shows old and new records; the token is bound to exactly these changes and the zone version of the preview. - Mail (keel-mail; mail domains `mdom_…`, mailboxes `mbx_…`; give them by name/address or ID): `list_mail_domains`, `get_mail_dns_status` (records with status and hint per problem; `refresh: true` checks now), `list_mailboxes`, `get_mail_log` (app mail metadata only), `get_mail_reputation` [mail:read]; `create_mail_domain` (verified at once and records set when the zone is in keel DNS), `create_mailbox`, `create_mail_alias` (local_part `*` = catch-all), `set_mail_forwarding` (sends someone's mail elsewhere: only on the user's explicit request; destructive in the API), `create_sending_key` (returned once: store as secret variables) [mail:write]. No tool sends mail, reads mail content or returns mailbox credentials; the user creates app passwords in the dashboard. - `delete_mailbox`, `delete_mail_domain` [admin, destructive] and `reset_mailbox_password` [mail:write, destructive: removes the mailbox password and revokes all app passwords, returns no new credential]: two steps like the other destructive tools. - `delete_service`, `delete_database`, `delete_kv` [admin, destructive]: the first call returns a preview and a `confirmation_token`; call again with the token only after the user explicitly agreed. Tokens expire after 5 minutes and work once. Typical flow: `list_projects` → `deploy_service` → poll `get_deployment` → on failure `diagnose_deployment` → apply a suggestion (`update_service`, `set_variables`, or fix code and push) → deploy again. Approvals: a workspace can require a person to approve actions of agent tokens (`agent_approvals`: `off`, `destructive` = every DELETE plus database restore and password rotation, and KV password and token rotation, `all_writes` = every non-GET request). A held request is not executed; tools then return `approval_pending` with `approval_id` and `approval_url` (REST: `202` with header `Keel-Approval-Id` and body `{"approval_id", "status": "pending", "code": "approval_pending", "hint", "approval_url", "expires_at"}`). Show the link to the user, poll `get_approval` (`GET /v1/approvals/{id}`) until `executed`, `failed`, `denied` or `expired`, and never send the request again: once approved, keel runs it exactly once and puts the response into the approval. Approvals expire after 24 hours. For `delete_*` tools the confirmation token comes first, the approval second. ## CLI - Install the CLI with `curl -fsSL https://keel.run/install.sh | sh` (macOS/Linux) or `brew install keel-run/tap/keel`, then `keel login` (browser; token in the OS keychain) or set `KEEL_TOKEN` in CI. - `keel link` writes `.keel/project.json` (IDs only, safe to commit). Non-interactive: `keel link --project --environment production --service `. - `keel deploy --watch` prints the diagnosis of a failed deployment (with `--json`: a `diagnosis` field next to the deployment). `keel diagnose [dpl_…]` diagnoses the newest or a given deployment. `keel config` shows and `keel config set --port 3000 --healthcheck /healthz --size m --builder railpack …` changes settings. `keel approvals [--status pending]` and `keel approvals get apr_… --wait 30m` follow approvals. - `keel deploy` in a linked directory uploads the working tree (honours `.gitignore`, `.keelignore`; never `.git`, `.env*`, `node_modules` unless re-included with `!pattern` in `.keelignore`) and deploys it; `--dry-run` lists the files; `--dir PATH` uploads another directory (also without a link); `--git` or `--commit SHA` deploys from Git. For agents: `keel deploy --service svc_… --dir . --watch --json` (log on stderr, deployment JSON on stdout, exit 8 if it failed). Limits: 200 MiB compressed, 1 GiB, 50,000 files. - `keel status`, `keel deploy [--git] [--commit SHA] [--watch]`, `keel logs [-f] [--since 1h] [--deployment dpl_…]`, `keel rollback [dpl_…]`, `keel env list|set|unset|pull`, `keel db list|create|url|connect`, `keel kv list|create|url [--rest] [--internal]|delete`, `keel dns zones`, `keel dns zone create|show|verify|update|delete`, `keel dns records [--name] [--type]`, `keel dns record add|set|rm [content…]`, `keel dns import [--replace]`, `keel dns export `, `keel dns dnssec ` (DS for the registrar; `enable|disable|rollover --zsk|--ksk`), `keel dns tsig list|create --acme|rm`, `keel dns query [type]`, `keel dns analytics `, `keel domains list|add|remove`, `keel tokens list|create|revoke`, `keel projects`, `keel services`, `keel services create --image …|--repo … [--kind web|worker|cron --schedule "0 3 * * *" --timezone Europe/Berlin --start …]`, `keel run [--timeout 30m] -- ` (streams the output, exits with the command's exit code; 124 timed out, 130 cancelled, 8 could not start), `keel runs [list|logs [-f]|cancel ]`, `keel whoami`, `keel open`. - Add `--json` for stable JSON on stdout (logs and progress go to stderr; errors are `{"error": {"code", "detail", "hint", "exit_code"}}` on stderr). Add `--yes` for commands that ask for confirmation. - Exit codes: 0 ok, 1 error, 2 usage/not linked/confirmation missing, 3 not logged in, 4 forbidden (role, scope, plan, billing), 5 not found, 6 invalid or conflict, 7 temporary (retry later), 8 deployment failed, 9 waiting for a person's approval (not executed; see `approval_id` and `approval_url` in the JSON error), 130 interrupted. ## API - Base URL `https://api.keel.run/v1`, `Authorization: Bearer keel_…`. OpenAPI: `https://api.keel.run/openapi.json`, docs: `https://api.keel.run/docs`. - Errors are RFC 9457 problem details with a stable `code` and a `hint` saying what to do next. Unknown and forbidden resources both answer 404. - Send `Idempotency-Key` on POSTs; repeating a request with the same key replays the first answer. - `GET /v1/deployments/{id}/diagnosis` [logs:read] returns the diagnosis described above. - Logs are Server-Sent Events: `GET /v1/services/{id}/logs?since=1h&follow=true`, `GET /v1/deployments/{id}/logs?follow=true`, `GET /v1/runs/{id}/logs?follow=true` (`event: log`, `event: end`; a run's end event carries `status` and `exit_code`; run output needs `logs:read` + `config:write`, otherwise 403 `missing_scope` and runs show `output_redacted: true`). - DNS: `GET/POST /v1/workspaces/{id}/dns/zones`, `GET/PATCH/DELETE /v1/dns/zones/{id}`, `POST …/verify`, `GET/POST …/rrsets`, `PUT/DELETE …/rrsets/{name}/{type}`, `POST …/changes {if_version, changes[]}`, `POST …/import`, `POST …/import/replace`, `GET …/export` (`text/dns`), `POST …/test-query`, `GET/PUT …/dnssec`, `POST …/dnssec/disable|rollover`, `GET …/analytics?window=24h|7d|30d`, `GET/POST …/tsig-keys`, `DELETE /v1/dns/tsig-keys/{id}`. RFC 2136 updates (cert-manager, certbot, lego) with a TSIG key at `update.dns.keel.run:53` (TCP). - Runs: `POST /v1/services/{id}/runs {"command": "…", "timeout_seconds": 900}` (202), `GET /v1/services/{id}/runs`, `GET /v1/runs/{id}`, `POST /v1/runs/{id}/cancel`. ## Tokens and scopes - Scopes: `read`, `logs:read`, `deploy`, `config:write`, `databases:read`, `databases:write`, `databases:query`, `domains:write`, `dns:write`, `billing:read`, `admin` (everything, including deletion; destructive). - Token kinds: `keel_pat_…` (personal, CLI), `keel_svc_…` (CI), `keel_agent_…` (agents; must expire). Tokens belong to one workspace and can be limited to projects. A token never has more rights than the person who granted it. - OAuth access tokens live 1 hour; refresh tokens rotate on every use and reusing an old one revokes the whole connection. ## Docs - [Documentation](https://keel.run/docs.md): How keel.run works – workspaces, projects, environments, services and databases – and where to start. - [Getting started](https://keel.run/docs/getting-started.md): Sign up, start the trial, deploy your first app from GitHub, GitLab or Codeberg, and use the keel CLI. - [Services](https://keel.run/docs/services.md): Sources, builds with a Dockerfile or Railpack, runtime settings, deploys and rollbacks, variables and custom domains. - [Databases](https://keel.run/docs/databases.md): Managed Postgres on keel.run – create a database, link it to a service, connect from your machine through keel-pgproxy with SNI, and use backups and point-in-time restores. - [Key-value (Valkey)](https://keel.run/docs/kv.md): Serverless Valkey on keel.run – a Redis-compatible key-value store over TLS and an Upstash-compatible REST API, billed per command. - [DNS](https://keel.run/docs/dns.md): keel DNS – authoritative DNS hosting for your domains with DNSSEC on by default, zone file import, ACME DNS-01 and automatic records for your services. - [Mail](https://keel.run/docs/mail.md): Mailboxes for your own domains on keel.run – DNS setup (automatic with keel DNS), mail clients and app passwords, webmail, aliases, forwarding, filters, limits, deliverability and prices. - [App mail](https://keel.run/docs/mail-sending.md): Send transactional mail from your apps on keel.run with sending keys (HTTP API and SMTP relay), follow delivery events with webhooks, and receive mail in your app with inbound routes – including signature verification. - [Agents and MCP](https://keel.run/docs/agents.md): Connect Claude Code or another MCP client to keel.run – OAuth consent, scopes, the MCP tools, confirmations for destructive actions, and docs for agents. - [Billing and limits](https://keel.run/docs/billing.md): Plans, the trial, how usage is metered and billed, spend limits, suspension, plan limits and VAT on keel.run. - [Security](https://keel.run/docs/security.md): How keel.run isolates tenants, encrypts secrets, hosts data in the EU, protects accounts and tokens, and handles backups. - [CLI reference](https://keel.run/docs/cli.md): Every keel command with its flags, generated from the CLI itself. - [API](https://keel.run/docs/api.md): The keel.run REST API – base URL, OpenAPI document, authentication, tokens and scopes, errors, idempotency, pagination, streams and rate limits. ## Optional - [All docs in one file](https://keel.run/llms-full.txt): every page above, concatenated - [Pricing](https://keel.run/pricing): plans and unit prices