Configure keelson.yaml

keelson.yaml tells Keelson how to start your app, whether it needs a database, and which tasks to run on a schedule. Place it in the root folder of the app you deploy (the project root).

Your AI agent normally creates and updates this file when you ask it to deploy. This page explains the settings worth reviewing. For all fields and their detailed requirements, see the keelson.yaml reference.

Example configuration

This Python web app uses a Keelson database.

slug: my-app              # App identifier
runtime: python-slim      # Python runtime
command: "python app.py"  # Command that starts the web server
db:
  mode: libsql            # Use Keelson Managed SQLite

Field	What to check
slug	The name that identifies the app. It forms part of https://<workspace>--<slug>.keelson.run
runtime	The runtime for your app’s language: Python, Node.js, or Go
command	The command that starts the app’s web server. Dependencies are installed during the build
db.mode	Use libsql for a Keelson database, or none if you do not need one or use an external database

db.mode: libsql provisions a database. Your app also needs code to connect to it and read and write data. This setting alone does not switch an existing SQLite file to Managed SQLite.

An app that only uses the Files / Media SDK can use db.mode: none. No configuration is needed to declare Files or Media usage.

Settings for each app structure

Every app needs slug, runtime, and db.mode. The other fields depend on its structure.

App structure	Main settings
Web app	Set command to the startup command
Static site / SPA	Set type: web and assets; omit command
Static frontend + API server (hybrid)	Set both assets and command
Scheduled jobs only	Set crons; omit the web server command

You can add crons to a web app with server-side processing. In that case, do not set type: web: type: web and crons cannot be combined. See Scheduled jobs.

Static site / SPA

This example serves prebuilt files. Set assets.dir to the build output folder.

slug: my-site
type: web
runtime: node-slim
db:
  mode: none
assets:
  dir: dist
  fallback: index.html # Return index.html when an SPA route is opened directly

Build static sites locally before deploying. Keelson does not install dependencies or run a build for them. Omit fallback for a regular static site if missing pages should not fall back to index.html.

Static frontend + API server

This example sends requests under /api to the server and serves prebuilt frontend files for other paths.

For this structure too, build the frontend locally and put its output in assets.dir before deploying. Keelson builds the server-side code, but the files served as assets are the ones you upload.

slug: my-app
runtime: node-slim
command: "node server.js"
db:
  mode: libsql
assets:
  dir: dist
  fallback: index.html
  api: /api

Optional settings

What you want to do	Setting	Learn more
Describe the app	description	Reference
Pass configuration values to the app	env	Environment variables and secrets
Use API keys or other secrets	Declare the required names in secrets. Do not write secret values here	Environment variables and secrets
Change database tables or columns during deployment	db.migrate	Database (Managed SQLite)
Run work at specific times or intervals	crons	Scheduled jobs
Set the page used to check startup	health.path	Reference
Call the app’s API from another system	Declare paths and methods in auth.endpoints, and issue an app token separately	External integrations

Before deploying

• Check the app name and storage choice. Make sure slug identifies the intended app and db.mode matches the database you want to use.
• Check for API keys or passwords written directly in the file. Declare only names and descriptions in secrets; set the values through the console or another supported method.
• Check recurring work. Review the crons schedules instead of relying on timers inside the app.

You can ask your agent to check the startup command and dependency files. This command checks the configuration and files to be uploaded without uploading them:

keelson deploy --check --json

This check alone does not confirm that the app will start or fit within your plan’s limits. After deployment, open the app URL and test it.

After changing the configuration

Changes to keelson.yaml take effect on the next deployment. Ask your agent to update the configuration and redeploy.

Keelson sets environment variables such as PORT. When reusing an older configuration, remove or replace retired fields. See the keelson.yaml reference for required changes and validation errors.

Next steps

• keelson.yaml reference
• Deploy your app
• Supported apps and constraints — Runtime versions and constraints