hub.yaml reference¶

hub.yaml sits next to an app's sources and holds the app's settings on the hub. This page lists every key, its default and what changing it costs.

Every key is optional. The hub applies the keys that are present on every deploy and leaves the app as it is for keys that are absent. The defaults are set when the app is created, and a key you remove keeps its last value. To go back to the default, write the default and deploy. There is one exception. Only the owner of an app or an admin can change maintainers and maintainer-groups. When a maintainer deploys a hub.yaml whose maintainer keys differ from the app's, the hub refuses the deploy before it builds anything, and the message shows the values the app has.

hub::new_app() and the first deploy of a directory without the file write a hub.yaml that sets name and title and lists the other keys of the project's kind, commented out, with their defaults. hub init writes every key, or with --type the keys of one kind. Uncomment a key only when you want to change it.

Do not put secrets in hub.yaml. Put them in .Renviron or .env, which the deploy stores as the app's secret, or set them with hub env set.

No value in hub.yaml may contain ${ or #{. The apps server would read them as references to its own settings, so the deploy refuses such a file. A value that needs these characters belongs in .Renviron.

A typical file for a Shiny app:

name: sales
title: Sales dashboard
description: Monthly figures by region, from the warehouse.
access-groups: [finance, sales]

Every kind¶

Key	Default	Meaning
`name`	the directory's name	The app's id and the last part of its URL. Lowercase letters, digits and dashes, at most 40 characters, starting and ending with a letter or digit. The platform reserves `r-btw`, `btw`, `hub`, `claude`, `proxy`, `proxyspec` and `route`. On the first deploy, `--name` can set it, and the deploy records it here. After that, a `--name` that differs from this key is refused.
`type`	detected	One of `shiny`, `rmarkdown`, `quarto`, `plumber`, `shiny-python`, `fastapi`, `targets` or `mcp`. Set it when detection would get the kind wrong, and for a directory with its own `Dockerfile`.
`entry`	detected	The main document, API file, app file or tools file, as a path inside the directory. Set it when the directory has more than one candidate.
`title`	the name	Shown on the apps page. `hub mcp` shows an MCP server's title. An API or a pipeline does not use it.
`description`	`Deployed by <owner>`	One line, shown on the apps page under the title.
`access-groups`	`[]`	Only members of these groups see the app or may call the API or MCP server. If the list is empty, everyone on this hub may. The names are the groups your identity provider sends. A pipeline does not use it: only its owner, its maintainers and hub admins can run it.
`maintainers`	`[]`	User ids of people who may deploy and manage the app as its owner can, except delete it, change the two maintainer keys and hand it to another owner. Write each id as `hub apps` shows owners, such as `alice@example.com`. Only the owner or an admin can change this key. See Work on an app as a team.
`maintainer-groups`	`[]`	Groups whose members are maintainers of the app. The hub compares the names without regard to case, as for `access-groups`. Only the owner or an admin can change this key.
`env`		Non-secret environment variables of the app's process, as a mapping such as `LOG_LEVEL: info`. Each value reaches the app as written, so `007` stays `007` and `true` stays `true`. A variable without a value is refused. Write `""` for an empty one. The mapping replaces the app's variables as a whole, so a variable you remove from it is removed from the app. Anyone who can read the app's settings sees them.
`renviron`	`true`	Store `.Renviron` or `.env` as the app's secret on every deploy. With `false`, the deploy leaves the file out.
`system-packages`	`[]`	apt packages to install into the image in addition to those the lock file needs. `hub sysreqs` shows what the lock file needs. Not available in stack mode.
`check-packages`	`true`	Load every package of the lock file at the end of the build. A missing system library then fails the build instead of the app's first start.
`require-clean`	`false`	With `true`, the hub refuses to deploy while a committed file has changes, while `hub.yaml` is not committed, or outside a git repository, and it uploads only the files of the commit (plus `.Renviron` or `.env`). What runs then always matches a commit.
`resources.memory`, `resources.cpu`	`2Gi`, `2`	The limits of the app's container, an API's process, or a pipeline run, as Kubernetes quantities: `2Gi` or `512Mi` for memory, `"2"`, `"0.5"` or `500m` for CPU.
`uses`	`[]`	Pipelines whose store this app reads. Each store is mounted read-only at `/srv/pipelines/<name>`, and `hub::store("<name>")` returns the path. This needs a hub that can share store volumes. If yours cannot, the deploy output says so. A static document cannot use it.

Apps and documents¶

These keys apply to shiny, shiny-python, rmarkdown and quarto:

Key	Default	Meaning
`prestart`	`0`	The number of containers kept warm, so that the app opens at once instead of after a start of a few seconds. To replace them with the new build, every deploy or rollback then restarts the apps server, which takes about a minute.
`seats-per-container`	`1`	The number of users who share one container. More than one costs less and suits an app that keeps no per-user state in memory. With more than one, the hub also keeps at least one container warm, and every deploy or rollback restarts the apps server, as with `prestart`.

APIs and MCP servers¶

These keys apply to plumber, fastapi and mcp:

Key	Default	Meaning
`access-clients`	`[]`	Client ids of your identity provider, such as a CI system or another service, that may call this API with their own token. The API sees such a caller as `client:<id>`. See APIs.

Pipelines¶

These keys apply to targets:

Key	Default	Meaning
`schedule`		A cron timetable with five fields, such as `"0 6 * * *"` for six every morning. It is read in the hub's time zone, which the deploy output names. Without a schedule, the pipeline runs only when you call `hub run`. To remove a timetable, set the key to `""` (`hub config unset schedule` writes that) and deploy.
`store-size`	`10Gi`	The size of the persistent `_targets` store, a Kubernetes quantity such as `10Gi` or `500Mi`, set when the first deploy creates it. A later change has no effect on the existing store.
`timeout`	`120`	The number of minutes a run may take before the hub stops it.

What a change costs¶

A change takes effect at the next deploy. Because hub.yaml is part of the directory, every change makes that deploy build the app and adds an entry to hub history. The build reuses the cached layers of the packages, unless the change is to system-packages.

For an app or document, a change to title, description, access-groups, env, resources, prestart, seats-per-container or uses restarts the apps server (about a minute).
An API or MCP server restarts with every build, without failed requests.
A pipeline has nothing to restart. Its next run uses the new values of env, resources, timeout and uses, and the deploy updates or removes the timetable of schedule.
store-size has no effect once the store exists.
A change to maintainers or maintainer-groups restarts nothing. It applies to the next command a maintainer runs.
name: a new name creates a new app. The old app stays until you run hub delete.

To edit one key from the terminal, run hub config set KEY VALUE. hub config get shows the file.