runlot.json
A configuration file placed in the project directory. It records the name, entry point, assets directory, and connected services.
web/apps/cli/src/config.ts and internal/bundle/bundle.go. The docs build generates this content from that source.{
"name": "my-app",
"org": "me",
"main": "src/index.ts",
"assets": "public",
"database": true
}Fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The project name. Used as the first label of the deployment URL. |
org | string | No | The organization slug. The --org option, if specified, takes precedence over this setting. |
main | string | No | The worker's entry point. If not specified, only static assets are deployed. |
assets | string | No | Static assets directory. |
notFound | "404" | "spa" | No | The response for paths not in the assets. With spa, paths without an extension get /index.html (client-side routing). Default is 404. |
compatibilityDate | string | No | The workerd compatibility date. The format is YYYY-MM-DD. |
database | boolean | No | A declaration that you use a database. runlot deploy reads it and creates one if it does not exist. |
storage | boolean | No | A declaration that you write to file storage. runlot deploy reads it, and creates it if it does not exist. |
email | boolean | No | A declaration that the app sends and receives email. runlot deploy reads it and creates the project address if it does not exist. |
ai | boolean | No | env.ai 선언 (docs/ai.md §2.2) |
auth | boolean | No | This declares that the app uses user authentication. runlot deploy reads it and turns it on if it is missing. It also creates a database. |
framework | "next" | No | The framework adapter. Currently the only supported value is next. |
triggers | { crons: string[] } | No | Scheduled execution. Write a 5-field cron expression in crons, in UTC. See Scheduled execution for details. |
name is required. You must specify at least one of main or assets. Without either, there is no worker or static asset to serve. Projects that specify framework are an exception, since the build process generates the entry point and assets.
Fields that declare services
database, storage, and auth are declarations. runlot deploy reads these values and creates any service that does not yet exist. This plays the same role as binding declarations in a wrangler configuration, and there is no separate command or dashboard button to turn it on. Creation is idempotent, so deploying multiple times with the same declaration still produces a single service.
Deleting the declaration does not remove the service. Deletion happens with runlot pg delete, runlot storage delete, or runlot auth delete, and each asks for confirmation. auth requires a database, so adding only "auth": true also creates the database.
Each service can be attached only once per project, so you declare it as true instead of a service name. In the worker, access them as env.db, env.storage, and env.auth respectively.
Bundle manifest
runlot deploy does not upload this configuration file as is. The CLI generates a separate runlot.json manifest in the bundle that references the build output. You do not need to write it yourself, but the validation rules below apply.
| Field | Description |
|---|---|
main | The worker entry module included in the bundle. If omitted, an entry point that serves only static assets is added automatically. |
assets | The asset directory included in the bundle. / and extensionless paths return index.html, and Content-Type is determined by the file extension. |
notFound | 404 (default) or spa. With spa, extensionless paths return /index.html. |
compatibilityDate | The format is YYYY-MM-DD. If not specified, 2024-09-23 is used. |
compatibilityFlags | An allowlist-based compatibility flag. Currently the only available value is nodejs_compat. |
modules | A list of additional modules. Only the wasm type is supported. |
framework | The framework adapter. Currently the only supported value is next. |
triggers | A scheduled run. crons is a 5-field cron expression (UTC), parsed at deploy time, and invalid ones are rejected. main is required. |
compatibilityFlags uses an allow list. No manifest should be able to enable a flag that grants user code process-wide control. If the bundle imports Node built-in modules, it needs nodejs_compat, so the CLI sets it automatically.
You can include WASM only through the modules field. workerd does not allow compiling by calling new WebAssembly.Module(bytes) inside the bundle. The Prisma query compiler is affected by this restriction.
Bundle limits
| Item | Limit |
|---|---|
| Compressed upload size | 64 << 20 |
| Total size after decompression | 512 << 20 |
| Size of a single file | 64 << 20 |
| Number of files | 20_000 |
The bundle can contain only regular files. Symbolic links, paths that point outside the project root, and duplicate entries are all rejected.