Skip to content

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:

if (!velonde::in_group("finance", request)) plumber2::abort_forbidden()

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 of tar_make(). schedule: in velonde.yaml adds 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, and velonde 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-groups has no effect on a pipeline.
  • The store (_targets, or VELONDE_STORE for a script) is a persistent volume of size store-size, so runs are incremental, as they are locally. A run may last up to timeout minutes, 120 by default.
  • after: in velonde.yaml names 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 under after: must be yours, list one of your groups in its access-groups or name you in its access-users, as for uses:.
  • Secrets and env reach a run in the same way as they reach an app. A run calls APIs on the workspace as its owner.
  • velonde delete removes 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 and velonde logs <name> [run] prints one. A render may take up to timeout minutes.
  • Every render becomes a new version. velonde history <name> lists them with the run that rendered each, and velonde 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: "" and after: [].

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.

params:
  region: north
  year: 2026
variants:
  north: { region: north }
  south: { region: south }

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.