velonde.yaml reference¶
velonde.yaml sits next to an app's sources and holds the app's settings on the workspace. This page lists
every key, its default and what changing it costs.
Every key is optional. The workspace 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 key as null
(audience: null) and deploy, or run velonde config unset KEY, which writes that for you.
There is one exception. Only the owner of an app or an admin can change maintainers and
maintainer-groups. When a maintainer deploys a velonde.yaml whose maintainer keys differ from
the app's, the workspace refuses the deploy before it builds anything, and the message shows the
values the app has.
velonde new, velonde::new_app() and the first deploy of a directory without the file write a velonde.yaml that
sets name and title and lists the other keys of the project's kind,
commented out, with their defaults. velonde 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 velonde.yaml. Put them in .Renviron or .env, which the deploy stores as
the app's secret, or set them with velonde env set.
No value in velonde.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 value may be up to 4096 characters long, and the file may not use YAML anchors and aliases.
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, velonde, 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 | In R one of shiny, rmarkdown, quarto, plumber, targets, script, mcp or package, in Python one of shiny-python, streamlit, dash, fastapi, notebook, quarto-python, script-python, mcp-python or package-python. Each kind is one language: the Python twin of an R kind ends in -python. Set it when detection would get the kind wrong, for a directory with its own Dockerfile, and always for a script, which the workspace never detects. |
entry |
detected | The main document, notebook, API file, app file or tools file, as a path inside the directory. Set it when the directory has more than one candidate. A Shiny app in R takes none: it is app.R, or ui.R and server.R, at the top of the directory you deploy. An .R file needs its type next to it, unless it is a plumber file. |
title |
the name | Shown on the apps page. velonde 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. |
audience |
internal |
Who the app, document, API or MCP server is for. internal means the people who log in to the workspace. external means the people who log in to the workspace's second login, such as your customers. public means anyone on the internet, without a login. The last two need servers that an admin adds to the workspace. See Publish outside the company. A pipeline is always internal. |
access-groups |
[] |
Only members of these groups see the app or may call the API or MCP server. If this list and access-users are both empty, everyone of the app's audience may, or, on a workspace with default_access=owner in its configuration, only the app's owner and maintainers. The names are the groups your identity provider sends, or, for an external app, the groups of the second login. A public app ignores the key. A pipeline does not use it: only its owner, its maintainers and workspace admins can run it. |
access-users |
[] |
User ids of people who see the app or may call the API or MCP server, besides the members of access-groups. Write each id as velonde apps shows owners, such as alice@example.com. The workspace compares ids without regard to case. With this key alone, only the people it names may open the app, so list yourself as well. For an external app, the ids are those of the second login. A public app ignores the key. On a pipeline, it names the people whose apps may read its store under uses:. |
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 velonde 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 workspace 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. The names and values together may take up to 16 KB. |
|
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. velonde 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 workspace refuses to deploy while a committed file has changes, while velonde.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. The files of a git submodule are not part of the commit and are left out, with a warning. |
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. Your workspace admin sets the most an app may ask for, by default 8Gi and 4. An app or an API reserves a quarter of the memory and an eighth of the CPUs on the workspace and may use up to the limits; a pipeline run reserves all of them. A static document's container gets 256 MB and half a CPU whatever this key says; for a scheduled report, the key sets the limits of its render runs. |
uses |
[] |
Pipelines whose store this app reads. Each store is mounted read-only at /srv/pipelines/<name>, and velonde::store("<name>") returns the path. This needs a workspace that can share store volumes. If yours cannot, the deploy output says so. A static document cannot use it, a scheduled report can. |
volumes |
[] |
Shared volumes of the workspace that this app reads, at /srv/volumes/<name> as in your session. The app can write to one only if the workspace administrator allows apps to write to it and, where the share names who may write, you as the app's owner are one of them. A share that is a personal folder per user is for sessions only. The share must admit the app's owner, and only apps of the audience internal can use one. Everyone who may open the app reads what it shows of the share. A static document cannot use it, a scheduled report can. |
Apps and documents¶
These keys apply to shiny, shiny-python, streamlit, dash, rmarkdown, quarto,
quarto-python and notebook:
| 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. At most 3 unless your workspace admin allows more. A Dash app cannot use it. |
seats-per-container |
1, for a static document without a schedule 50, for a public app 10 |
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 workspace also keeps at least one container warm, and every deploy or rollback restarts the apps server, as with prestart. A Dash app always has a container per user. |
max-users |
0, for a public app 50 |
The number of people who may use the app at the same time. 0 means no limit. Once the limit is reached, a further visitor sees a page saying that the server has no capacity, until someone leaves. |
execute |
false |
Notebooks only. With true, the build runs the notebook before it renders it, without the app's secret or env:. With false, the page shows the outputs saved in the notebook. |
APIs and MCP servers¶
These keys apply to plumber, fastapi, mcp and mcp-python:
| 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 and scheduled reports¶
These keys apply to targets, script and script-python, and the first, second and last also to a static
document, which they make a scheduled report:
| Key | Default | Meaning |
|---|---|---|
schedule |
A cron timetable with five fields, such as "0 6 * * *" for six every morning. It is read in the workspace's time zone, which the deploy output names. Without a schedule, the pipeline runs only when you call velonde run. To remove a timetable, set the key to "" or null (velonde config unset schedule writes null) and deploy. |
|
after |
[] |
Pipelines whose successful runs start a run of this one, as its owner. Each must be yours or list one of your groups in its access-groups. A chain that leads back to this pipeline is refused. |
store-size |
10Gi |
The size of the persistent store (_targets, or VELONDE_STORE for a script), 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. At most 50Gi unless your workspace admin allows more. |
timeout |
120 |
The number of minutes a run or a render may take before the workspace stops it, at least 1 and at most 1440 unless your workspace admin allows more. |
These keys apply to static documents (quarto, quarto-python, rmarkdown, notebook):
| Key | Default | Meaning |
|---|---|---|
params |
Parameters of every render, as a mapping such as region: north, overriding the document's own. Values are text, numbers or true and false. A notebook takes them only when it runs. See Parameters and variants. |
|
variants |
Named sets of parameters, such as north: { region: north }. The document is rendered once per variant, each at <address>/<variant>/, with a page linking them at the address. At most 50. |
|
email |
[] |
Scheduled reports only: addresses that receive a short mail with the link after every render, in the domains your workspace admin allows. See Mail after a render. |
Packages¶
These keys apply to package and package-python (R and Python packages). Of
the keys above, a package uses name, type, maintainers, maintainer-groups and
require-clean, and an R package also system-packages: its build installs them, and so does
the build of every app that uses the package. The name on the workspace is the package's name in
lower case, with dots and underscores replaced by dashes.
| Key | Default | Meaning |
|---|---|---|
check |
false |
With true, the build runs R CMD check (R) or pytest (Python) before it publishes. A check that ends with an error, or a failing test, stops the publication. Notes and warnings appear in the output. |
What a change costs¶
A change takes effect at the next deploy. Because velonde.yaml is part of the directory, every
change makes that deploy build the app and adds an entry to velonde 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,max-users,usesorvolumesrestarts the apps server (about a minute). A change toaudiencemoves the app to another server and restarts both. - 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,usesandvolumes, and the deploy updates or removes the timetable ofschedule. store-sizehas no effect once the store exists.- A change to
maintainersormaintainer-groupsrestarts nothing. It applies to the next command a maintainer runs. name: a new name creates a new app. The old app stays until you runvelonde delete.
To edit one key from the terminal, run velonde config set KEY VALUE. velonde config get shows the
file.