Apps, documents, APIs, MCP servers, pipelines and reports¶
This page describes what each kind of project becomes once velonde deploy has built it, at which
address it is reached, and who may reach it.
Apps and documents¶
A Shiny app in R or Python, a Streamlit or Dash app, a Shiny document, a static Quarto or R
Markdown document, or a Jupyter notebook becomes a tile on the apps page at
https://apps.velonde.<your domain>/app/<name>. It opens for anyone who
logs in with your identity provider and whom its access-groups or access-users admit. The workspace starts one container
per user when that user first opens it, from the image the deploy built. A static document is
rendered at build time, and its container only serves the files. Its readers share one
container, up to 50 to each, and the workspace keeps one container running, so the document opens at
once. Because of that container, every deploy of the document restarts the
apps server, as for an app with prestart. A
scheduled report is the exception: it gives each reader a small container of their own, so
that its renders restart nothing. The build has none of the
app's environment: no .Renviron, no env from velonde.yaml and no pipeline store. A document
that needs any of them must be a scheduled report, which renders in runs,
or a Shiny document, which runs when it is opened.
Opening an app takes a few seconds while its container starts. prestart: N in velonde.yaml
keeps N containers warm. To replace them with the new build, each deploy then restarts the
apps server (about a minute).
A Dash app is the exception. Dash needs the address of the user's session when it starts, and
a warm or shared container started before anyone opened it, so the deploy refuses prestart
and seats-per-container for a Dash app, and a public Dash app gets one container per visitor.
The workspace serves a Dash app with gunicorn and sets Dash's path prefixes itself, so the app must
not set url_base_pathname or requests_pathname_prefix. A Streamlit app runs with
streamlit run, on the workspace's port and address.
Jupyter notebooks¶
A notebook becomes a page with its cells and the outputs saved in it. The build does not run
it, so run all cells and save before you deploy. With execute: true in velonde.yaml, the build
runs the notebook first, with the project's packages from uv.lock and without the app's
secret or env:, like a static document. The notebook's kernel does not matter there: the
build runs it on the workspace's Python.
Who is using the app¶
In R, velonde::user(session) and velonde::groups(session) return the user and their groups, and
velonde::in_group("finance", session) tells whether the user is in a group. In Python, the same
values are in the request headers X-SP-UserId and X-SP-UserGroups: in Shiny for Python
session.http_conn.headers, in Streamlit st.context.headers, in Dash flask.request.headers
inside a callback. The workspace sets both on every request, and the browser cannot forge them. Group names arrive in upper case (FINANCE)
whatever your identity provider sends, so compare them without regard to case, as
in_group() does. Do not read SHINYPROXY_USERNAME from the environment: it describes the
container, and a warm container was started before any user opened it. When you run the app locally, both return nothing, so an
app that depends on them should handle that case.
Environment and secrets¶
When you deploy, a .Renviron or .env next to the sources becomes the app's secret, and the
app's process receives its contents as environment variables. velonde env set adds or overrides
keys without a deploy. Your workspace admin can also define an optional set of variables that reaches
every app in the same way (Variables for every app shows how). The app's process runs as an unprivileged user, with the limits that
resources sets: two cores and two gigabytes by default.
A static document is rendered by the build, which receives neither the secret nor the
variables under env: in velonde.yaml, so its code cannot read them. A document that needs them
must be a scheduled report or a Shiny document (server: shiny in Quarto,
runtime: shiny in R Markdown), which renders in its container on the workspace.
APIs¶
A plumber or plumber2 API in R, or a FastAPI application in Python, runs as one process behind
https://apps.velonde.<your domain>/api/<name>/. A FastAPI application must be the object named
app in its file, or api, the name that vetiver gives it. The workspace runs an R API with plumber2 when renv.lock lists plumber2 and not
plumber. When the lock file lists both or neither, it runs plumber2 if the API file uses it and
plumber otherwise. An API does not appear on the apps page. A redeploy or rollback
restarts it without failing any requests. access-groups and access-users in velonde.yaml
decide who may call it, and access-clients does the same for systems outside the workspace. The workspace checks every call
before the API sees it. There are three ways to call an API.
From the workspace, as yourself, without a credential. From an IDE session, a Shiny app or a
pipeline run, call the address inside the workspace, http://api-<name>/, which
velonde::api_url("<name>") returns. The workspace knows which user the calling process belongs to (for
a pipeline run, its owner) and checks access-groups. The API receives the caller in
X-SP-UserId and X-SP-UserGroups. A call from inside the workspace to the public URL carries no
identity, so use the internal address. A Shiny app with warm or shared containers (prestart,
or seats-per-container above 1) starts its containers before anyone opens it, so they belong
to no viewer: its calls are refused with 401 unless it sends the API key or a token.
From outside, with a token from your identity provider. Send Authorization: Bearer
<token> to the public URL. A token issued to the client that people log in with identifies that
user, with their groups. With Cognito, send the ID token. A token issued to another client
identifies a machine. The workspace admits it when its client id is in access-clients, and the API
sees the caller as client:<id>. This is standard OAuth and works from any language. The
administrator of your identity provider registers machine clients.
Tokens require api_token_issuer in the workspace's
configuration. Without it, the workspace
accepts no tokens. Tokens of people also require api_token_client_id, the client that people
log in with. Without it, the workspace treats every token as a machine's. With an identity provider
other than Cognito, api_token_user_claim and api_token_groups_claim name the claims that
carry the user and the groups.
With the key, for a caller that has no identity. velonde apikey <name> prints the URL, the
user api and the key. Only the owner of the API, its maintainers and workspace admins can see the key. Call the API
with curl -u api:<key> <url>. The key bypasses access-groups, so the owner decides whom to
give it to, and the API sees no caller.
--rotate replaces the key. The API's own documentation page (/__docs__/ for plumber, /docs
for FastAPI) asks the browser for the key.
Inside the API, velonde::user(request) and velonde::groups(request) return who is calling, or NULL
for a caller that uses the key. In plumber2, pass the handler's request argument. In plumber,
pass req. In Python, read the headers. To restrict one endpoint to a group in plumber2:
The API never receives the Authorization header that a caller sends. The workspace removes it once
it has checked the call, so neither a key nor a token reaches the API's code, and an API cannot
run a login of its own on that header. A request body may be up to 100 MB. The workspace refuses a
larger one with status 413.
Models with vetiver¶
A model API that vetiver writes deploys without changes: in R, vetiver_write_plumber() writes
a plumber.R, and in Python, vetiver.write_app() writes an app.py. Deploy the directory
with its lock file. The API's container must be able to read the model's pin. Use a folder
board inside the project, created with a relative path such as board_folder("board"), or a
cloud board whose credentials are in .Renviron or .env. An absolute path into your home
does not exist in the container, and board_connect() has no Connect server to reach.
Callers send rows to /predict.
Forwarded headers¶
A call to the public URL arrives with X-Forwarded-Proto: https and the caller's address first
in X-Forwarded-For. FastAPI reads both, so the links and redirects it builds use https. The
workspace also starts a FastAPI application with its root path set to /api/<name>, so its
redirects and its /docs page stay under the API's address. A process inside the workspace can set
these headers to any value, so an API must not decide who is calling from them.
MCP servers¶
A project whose _server.yml contains engine: mcptools and tools: tools.R deploys as an MCP
server. tools.R returns a named list of ellmer::tool() objects, and the workspace serves them over
HTTP at the same addresses as an API, with the same three ways in. The mcp template of
velonde::new_app() creates such a project. An MCP server does not appear on the apps page.
In Python, a file server.py, app.py or main.py that imports fastmcp deploys as an MCP
server of the kind mcp-python, and so does one that uses the FastMCP or MCPServer class of the
official MCP SDK.
The workspace serves the server object, named mcp or server, itself, over HTTP without sessions,
and does not run the file's __main__ block. A tool reads its caller with
fastmcp.server.dependencies.get_http_headers(). velonde new <name> --template mcp-python
creates such a project.
At every session start, the workspace registers in the user's Claude Code and Posit Assistant their
own MCP servers and those whose access-groups name one of their groups or whose
access-users name them. A server without either is open to everyone, but the workspace registers it only for users who ask for it with
velonde mcp add <name>: a server's tool descriptions and results reach the assistant, which runs
commands as its user, so nobody gets a colleague's server without choosing it. Each server is
registered under its name, at the internal address, without a credential. The session
identifies the user, and the workspace checks the groups on every call. Servers that no longer exist
are removed again. After you deploy a server, the agents of the colleagues its groups name have
its tools at their next session start. Your own agent has
them after a restart, or straight away if you run
claude mcp add --transport http <name> http://api-<name>/. velonde mcp lists the servers you
have.
A client outside the workspace, such as Claude Desktop on a laptop, uses the public URL that velonde mcp
shows and sends the key from velonde apikey <name> as a basic-auth header. To check a server
without any client, send a POST request with a JSON body to its internal address from a
session:
$ curl -s -X POST http://api-<name>/ -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Pipelines¶
A directory with _targets.R deploys as a pipeline. The workspace builds it like an app, with the
lock file, system libraries and load check, and then runs it as a job instead of a web app. A
pipeline does not appear on the apps page.
A script deploys as a pipeline too: an R file with type: script in velonde.yaml, or a Python
file with type: script-python, and the file as entry: (or pipeline.R or pipeline.py). A run
runs the file with Rscript or python, and its store is the directory that the environment
variable VELONDE_STORE names. In the IDE the variable is not set, so a script falls back to a
directory of its own, such as _store, which velonde deploy does not upload. The build of a
Python script imports what the script imports, and never runs the script. The script and
script-python templates create such a project.
velonde run <name>starts a run now and streams the log oftar_make().schedule:invelonde.yamladds a timetable, which the workspace reads in its own time zone. A pipeline runs once at a time.- When a run fails that nobody started by hand (a scheduled run, or one that follows another pipeline), the workspace mails the owner and the maintainers the end of its log. That needs a mail account on the workspace and user ids that are mail addresses in the workspace's mail domains.
velonde runs <name>lists runs, andvelonde logs <name> [run]prints a log. Runs are kept for seven days. Of the runs that the schedule starts, the workspace keeps at most the last ten that succeeded and the last ten that failed. Because a log can contain the pipeline's data, only the owner, the maintainers and admins can list the runs and read their logs.- Only the owner, the maintainers and admins can start a run.
access-groupshas no effect on a pipeline. - The store (
_targets, orVELONDE_STOREfor a script) is a persistent volume of sizestore-size, so runs are incremental, as they are locally. A run may last up totimeoutminutes, 120 by default. after:invelonde.yamlnames other pipelines. After every run of one of them that succeeds, this pipeline runs too, as its owner. The workspace checks once a minute, so a chain of pipelines runs in sequence without timetables that have to fit each other. A pipeline underafter:must be yours, list one of your groups in itsaccess-groupsor name you in itsaccess-users, as foruses:.- Secrets and
envreach a run in the same way as they reach an app. A run calls APIs on the workspace as its owner. velonde deleteremoves the store together with the pipeline.
Read a pipeline's results from an app¶
List the pipelines whose results an app needs under uses: in its velonde.yaml. The workspace then
mounts each store read-only at /srv/pipelines/<name>, and velonde::store("<name>") returns that
path, for example in targets::tar_read(x, store = velonde::store("sales-etl")). In the IDE, where
no store is mounted, the same call returns _targets, the store in the working directory. The
code runs unchanged there, and reads the results of the project you run it in.
You can use a pipeline that you own, or one that lists one of your groups in its
access-groups or names you in its access-users. The workspace checks this again whenever it starts the app, so a pipeline that no
longer admits you, or that someone else has deployed under the same name, is not mounted.
A static document cannot use a store, because the workspace renders it at build time, where no store
is mounted. The deploy refuses uses: for one. Make it a
scheduled report, whose runs mount the store, or a Shiny document
(runtime: shiny in R Markdown, server: shiny in Quarto), which reads the store when it is
opened.
This mounts one volume into several containers, which not every workspace can do. A workspace on one
machine can. On a cluster, it needs a storage class that supports it. On a workspace that cannot, the
deploy refuses uses: and says so.
Scheduled reports¶
A static document (Quarto, R Markdown or a Jupyter notebook) with schedule: or after: in
its velonde.yaml is a scheduled report. The workspace renders it in runs instead of in the build, so
the report can show fresh data and use what the build has not got: the app's secret from
.Renviron or .env, the variables under env:, the pipeline stores under uses:, and the
owner's identity when it calls APIs on the workspace.
- The deploy builds the image that renders the report and starts a first run. The report appears on the apps page when that run has rendered it, at the same address as any document.
schedule:renders on a timetable, in the workspace's time zone.after: [sales-etl]renders after every successful run of that pipeline, so the report always shows its newest results. A report may have both.velonde run <name>renders now,velonde runs <name>lists the renders andvelonde logs <name> [run]prints one. A render may take up totimeoutminutes.- Every render becomes a new version.
velonde history <name>lists them with the run that rendered each, andvelonde rollback <name>brings back an earlier one until the next render. The workspace keeps the last ten. - A notebook in a report always runs. Its kernel does not matter, because the run uses the
workspace's Python with the packages of
uv.lock. - To turn a report back into a document rendered at deploy, set
schedule: ""andafter: [].
Parameters and variants¶
params: in velonde.yaml sets parameters for every render and overrides the defaults in the
document. In Quarto they are the document's params: (with knitr) or the cell tagged
parameters (with Jupyter); in R Markdown they are the params: of the header. The values are
text, numbers or true and false. To render a Python document with parameters in the IDE,
add papermill to the project (uv add --dev papermill); the workspace's renders have it.
variants: renders the document once per named set of parameters, each on top of params:.
Each variant is published at <address>/<variant>/, and the address itself shows a page that
links them. All variants share the report's access groups. Parameters and variants also work
for a document rendered at deploy. A notebook takes parameters only when it runs, so it needs
execute: true or a schedule.
Mail after a render¶
email: lists addresses that receive a short mail after every render of a scheduled report,
with the report's title, the time and the link. The mail contains nothing of the report
itself: whoever opens the link logs in and needs to be in the report's access groups. The workspace
sends it through the mail account your workspace admin set up, and only to addresses in the domains
that the admin allows (report_email_domains, by default the domain of the workspace's sender). On a
workspace without a mail account, the deploy refuses email:.
Build from your own Dockerfile¶
If the directory contains a Dockerfile, the workspace skips detection and builds that file as it
is. Your Dockerfile has to copy in the sources itself. The workspace runs the result as the type
you give in velonde.yaml: an app on port 3838 by default, an API on port 8000 for plumber,
fastapi, mcp or mcp-python, or a pipeline for targets, script and script-python, whose
image runs it with the store mounted at /srv/app/_targets or /srv/app/_store. The deploy
refuses a type that is not one of the kinds on this page, and a
document built from your own Dockerfile is never a scheduled report. The workspace adds nothing to such an
image: no lock-file restore, no system libraries and no load check. Its container runs as the
user that the image names, without a few kernel capabilities that no app needs, such as raw
network access. An API or MCP server is stricter, because it shares its pod with the workspace's
authentication proxy: its image must name a user by number, and the number must not be 0 or
65532. End such a Dockerfile with a line like USER 1000. The deploy refuses the image
otherwise, after the build. An own Dockerfile skips what makes the workspace's apps consistent: our base images, which we keep
patched, the restore of the lock file, the load check and the tests. A workspace therefore refuses
it unless your workspace admin allows it with deploy_allow_dockerfile=true in the workspace's
configuration. The admin can also limit it to the members
of some groups (deploy_dockerfile_groups) and decide which base images a Dockerfile may start
from (deploy_dockerfile_images). Without that list, a Dockerfile may start from the workspace's own base
images only, velonde/shiny-base and velonde/python-base in the workspace's registry. A company usually lists
the registry of its own approved images there. A Dockerfile may never start from the workspace's IDE
images or from another deployed app, whatever the list says: the build refuses them in FROM
and in COPY --from. The deploy checks the FROM lines before the build and names an image
it refuses. An image chosen through an ARG is refused during the build.