Get started

The cloudhost.toml file

A project's settings in one file next to its code: name, type, entry file, static files, variables, database, cache and bucket bindings, crons and a build command. cloudhost deploy with no arguments reads it.

Make one#

init

cd my-api
cloudhost init
# wrote cloudhost.toml for my-api; edit it, then: cloudhost deploy
cloudhost deploy

cloudhost init [name] writes a cloudhost.toml in the current folder; the name defaults to the folder's. In a folder with no package.json it is written for a function, otherwise for an app; cloudhost apps init always writes an app.

A full example#

cloudhost.toml

name = "guestbook"
type = "function"
main = "index.ts"
runtime_date = "2026-11-01"

[vars]
GREETING = "salam"

[[db]]
binding = "DB"
database = "notes"

[[cache]]
binding = "CACHE"
name = "sessions"

[[bucket]]
binding = "BUCKET"
name = "uploads"

[[queues.producers]]
binding = "JOBS"
queue = "emails"

[triggers]
crons = ["0 3 * * *"]

Keys#

Key	What it is
`name`	Required. One DNS label: lowercase letters, digits and hyphens, 1–63 characters, no `--`. The project's address is `<name>.fn.trustpage.ir` or `<name>.app.trustpage.ir`.
`type`	`"function"` or `"app"`. Default: an app when there are `assets` or a framework, otherwise a function.
`main`	The function's entry file (TypeScript or JavaScript). Optional for an app: a function for paths with no file.
`assets`	The app's folder of static files.
`runtime_date`	`YYYY-MM-DD`; pins the runtime's behaviour to that date. Default: today.
`spa`	`true`: serve `/index.html` for unknown paths, in an app that also has a function. An app without one works it out itself.
`framework`	`"none"` turns off Next.js and Astro detection.
`[vars]`	Plain values, read as `env.NAME`. Not for secrets: set those with `secrets put`.
`[[db]]`	`binding` (default `DB`) and `database`: one of the team's databases as `env.DB`.
`[[cache]]`	`binding` (default `CACHE`) and `name`.
`[[bucket]]`	`binding` (default `BUCKET`) and `name`.
`[[queues.producers]]`	`binding` and `queue`: the function sends with `env.<binding>.send(body, {delaySeconds})` and `sendBatch([...])`. The older `[[queue]]` with `binding` (default `QUEUE`) and `name` is still accepted.
`[[queues.consumers]]`	`queue`, and optionally `max_batch_size`, `max_batch_wait_ms`, `max_concurrency`, `max_retries`, `retry_delay`, `visibility_timeout` and `dead_letter_queue`. Each deploy makes this function the queue's consumer (its `queue(batch, env, ctx)` handler) and updates the queue's settings.
`[triggers] crons`	Up to 5 crons. Each deploy replaces the project's list with this one, in the `Asia/Tehran` time zone. Without `[triggers]` the crons are left as they are.
`[build] command`	A command run before deploying, such as `npm run build`.

Deploying with it#

cloudhost deploy in a folder with a cloudhost.toml runs the build command, builds Next.js or Astro if it finds them, uploads the files and code, deploys the version and sets the crons. With --branch feature-x it makes a preview instead of production.

cloudhost build and git push read the same file on our servers. With no cloudhost.toml in the repository, the build uses the project's name and type, and an app with no package.json is served from the repository root as static files.

Secrets are never in this file and a deploy does not change them: cloudhost functions secrets put <name> <KEY>.