Skip to content

Deploy Kaeso on Render

Run Kaeso on Render from the blueprint in the repository, with a public edge, a private gateway and console, Render Postgres and Key Value. Step by step, from the master key to your own domain.

Published
Reading time
3 min
Author
Kaeso Team
A pale gradient of orange, pink and violet, folding diagonally upward, with a warm light in one corner

Render reads a blueprint, render.yaml, and creates every service in it. Kaeso's repository has one at its root, pinned to the latest release. It runs Kaeso on five Render resources, with only one of them public.

What you get

  • kaeso-edge
    Type
    Web service
    Image
    The console image, running kaeso-edge
    Plan
    0.5 CPU, 512 MB
  • kaeso-gateway
    Type
    Private service
    Image
    The gateway image
    Plan
    2 CPU, 4 GB
  • kaeso-console
    Type
    Private service
    Image
    The console image
    Plan
    0.5 CPU, 512 MB
  • kaeso-valkey
    Type
    Key Value
    Image
    Render's, with noeviction
    Plan
    256 MB
  • kaeso-postgres
    Type
    Postgres
    Image
    Render's, version 18
    Plan
    1 CPU, 2 GB

Only the edge is public. It sends the APIs, the MCP server and its sign-in to the gateway and every other path to the console, over Render's private network. Postgres and Key Value have an empty ipAllowList, so only the services reach them. Every service has autoDeployTrigger: off: Render never redeploys on a commit, and your install stays on the release you chose.

Change a plan or the region in the blueprint before you create it; Render keeps them from then on.

Before you start

You need a Render account, an SMTP server for Kaeso's emails, and Docker on your computer to generate the master key:

docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate

Keep the key in a password manager. Kaeso encrypts provider keys with it, so a database backup can't be read without it.

For request logs, you also need a ClickHouse, such as ClickHouse Cloud. Without one, request logs are off, and usage, limits and budgets work the same.

Deploy

  1. Open Deploy to Render (opens in a new tab). It creates a Blueprint from the repository logicplanes/kaeso on the branch prod, which holds the latest release.

  2. Fill in the values the blueprint asks for:

    ValueWhat to enter
    KAESO_PUBLIC_URLhttps:// and the edge's address, such as https://kaeso-edge.onrender.com
    KAESO_MASTER_KEYSThe master key
    KAESO_SETUP_EMAILYour address; the gateway emails the setup link there
    KAESO_SMTP_HOST, KAESO_SMTP_USER, KAESO_SMTP_PASSWORD, KAESO_SMTP_FROMYour SMTP server
    KAESO_CLICKHOUSE_URLA ClickHouse HTTP URL with user and password, or empty
  3. Apply the blueprint, and wait until every service is live.

  4. Open the one-time setup link the gateway emailed to KAESO_SETUP_EMAIL, and create the first user. The gateway sends a new link at every start until a user exists.

From there, add a provider key in the console, create a project key, and send a first request to https://kaeso-edge.onrender.com/v1.

Your own domain

Add the domain to kaeso-edge under Settings, and point its DNS record where Render says. Then set KAESO_PUBLIC_URL on kaeso-gateway to https:// and the domain, and redeploy the gateway.

How client addresses stay honest

Kaeso's limits, logs and audit entries record the client's address, so it must not be something a caller can make up. Public traffic reaches Cloudflare before Render, and Render appends to the caller's X-Forwarded-For rather than replacing it. The edge therefore reads CF-Connecting-IP, which Cloudflare overwrites, and sends the gateway one address. The gateway trusts only the edge.

The gateway listens on port 8080 and keeps its metrics on its loopback address, because Render treats the one port a private service binds on every interface as its port.

Update and roll back

A release changes the image tags in render.yaml on prod. On the blueprint's page, Manual sync redeploys the services on the new release, and the gateway migrates the database at start. To roll back, use Rollback on each service to its previous deploy. Migrations only move forward, so a rollback past a release whose migrations the earlier version can't run stays where it is, as on any install.

What was tested

On 2026-11-07, during the release candidates, the blueprint was created from an empty Render project in Frankfurt. It created all five resources, the setup email arrived, the health and readiness checks passed, and a streamed completion reached the console's request log. The test also found that Render appends to X-Forwarded-For, which led to the CF-Connecting-IP change above; that change passes the local edge test and the configuration check, but hasn't been retested live.

Next steps

By Kaeso Team

On this page

Own the gateway.Own the record.

curl -fsSLhttps://kaeso.app/install.sh | sh