Skip to content

Deploying from the IDE

velonde deploy, run in a project directory, builds the project inside the workspace and publishes it. This page covers what the workspace recognises, what it uploads and builds, how to read the output when a build fails, and how several people work on one app.

You need neither Docker on your machine nor any cluster configuration. The workspace reads the files, works out what kind of project they are, builds an image with the packages the project records, pushes it to the workspace's registry and registers the result. Run the command in a terminal of an IDE session on the workspace, because the session is how the workspace knows who is deploying. Outside a session the command reports that it cannot reach the deploy service. In R, velonde::deploy() and the other functions of the velonde package do the same from the console. In VS Code, the Deploy button in the status bar runs the same deploy, and in RStudio the addin "Deploy to the workspace" does (see The IDEs).

What deploys, and how it is recognised

In the directory Kind Runs as
app.R, or ui.R and server.R shiny an app on the apps page
_targets.R targets a pipeline that runs as jobs, now or on a schedule, with nothing on the apps page
_server.yml with engine: mcptools mcp an MCP server at /api/<name>/, registered in your colleagues' coding agents
plumber.R plumber an API at https://apps.velonde.<your domain>/api/<name>/
app.py, main.py, streamlit_app.py or server.py importing fastmcp mcp-python an MCP server of Python tools, as above
the same files importing fastapi or vetiver, with the application object named app or api fastapi an API at /api/<name>/
the same files importing shiny shiny-python an app on the apps page
the same files importing streamlit streamlit an app on the apps page
the same files importing dash dash an app on the apps page
*.qmd with server: shiny, *.Rmd with runtime: shiny Shiny document an app on the apps page
*.qmd, _quarto.yml or *.Rmd without Shiny static document rendered at build time and served as files on the apps page
*.ipynb notebook a Jupyter notebook, rendered at build time and served as files on the apps page
type: script or type: script-python in velonde.yaml, with an R or a Python file as entry script, script-python a pipeline that runs the file as jobs, with nothing on the apps page
a static document with schedule: or after: in velonde.yaml scheduled report rendered in runs, each render a new version on the apps page

The workspace checks the files in the order of the table, and Quarto files before R Markdown files and notebooks. A Quarto document is a quarto-python document, rendered with the Jupyter engine, when a pyproject.toml, uv.lock or requirements.txt is next to it, or when it has Python chunks and no R chunks. A Shiny document in Python becomes a Shiny for Python app. Every kind is one language: the Python twin of an R kind ends in -python. To override detection, set type: and entry: in velonde.yaml. A directory with several documents needs entry:, unless one of them is index.qmd or index.Rmd, or the directory has a _quarto.yml, which the workspace renders as a Quarto project.

A directory with its own Dockerfile is built from that file, if your workspace allows it. Build from your own Dockerfile explains how.

Kinds describes what each kind does once it runs and how you reach it.

Dependencies

R packages come from renv.lock. Run renv::snapshot() before you deploy, and the build restores exactly those packages on top of the workspace's package stack. Python packages come from uv.lock, which uv lock writes. A requirements.txt also works, but it pins nothing.

The workspace looks up the system libraries that the R packages in the lock file need and installs them. velonde sysreqs shows that list in advance. If the lookup misses a library, add it under system-packages in velonde.yaml.

A workspace in stack mode (deploy_mode in its configuration) restores no packages. An app may use the packages of the workspace's stack and no others, and builds take seconds. The deploy output says which mode the workspace is in.

Install R packages inside the project, with renv::install() or install.packages() while the project is active. A package you install in a plain session outside a project goes into your personal library, which renv does not record.

What is uploaded

The workspace uploads everything in the directory except .git, .Rproj.user, .Rhistory, .RData, .Ruserdata, renv's library and staging directories, .claude, .posit, .quarto, .venv, _targets, _store and the usual caches. These names are left out at any depth, and the deploy says so for a _targets or _store directory below the top of the project. .gitignore does not apply. The upload is compressed and limited to 200 MB, so keep large data files outside the project, or leave them out with .velondeignore. velonde deploy checks the size before it uploads anything.

A file named .velondeignore at the top of the project lists what else the upload leaves out. It takes the patterns of a .gitignore: a name matches at any depth, a pattern with a slash counts from the top of the project, a trailing slash means directories only, and a line that starts with ! takes a path back.

# .velondeignore
data/raw/
*.parquet
!data/lookup.parquet
tests/

The deploy lists what the file left out. velonde.yaml is always uploaded. An app bound to a repository is built from the repository, not from an upload, so .velondeignore has no effect there: mark such paths with export-ignore in a .gitattributes file in the app's directory.

A symbolic link to a file or directory inside the project is uploaded as what it points to, so a data link to raw/data reaches the app as a directory. A link to a path outside the project is left out, and the deploy names it in a warning: the build cannot see that path.

With require-clean: true in velonde.yaml, the workspace uploads the files of the last commit and the .Renviron or .env, and nothing else in the directory.

The workspace takes .Renviron (R) or .env (Python) out of the upload and stores it as the app's secret, so the file never enters the image. See Secrets and environment.

The first deploy

$ velonde deploy
velonde: packing /home/rstudio/sales as 'sales'
velonde: building sales as registry.velonde.acme.example/apps/sales:latest (shiny; mode: renv, Dockerfile: generated, renv.lock: yes)
velonde: system packages: libcurl4-openssl-dev libssl-dev
...
velonde: pushed registry.velonde.acme.example/apps/sales:latest (sha256:3f9c1a7e2b04)
velonde: app registered; the apps server restarts (about a minute)
velonde: https://apps.velonde.acme.example/app/sales
velonde: wrote velonde.yaml (app name 'sales'); edit it to change title, groups, env, sizing

The app takes the directory's name in lower case, unless --name or velonde.yaml sets another. A new app restarts the apps server, so its URL may take about a minute to open.

The first deploy writes a velonde.yaml that sets name and title and lists the other keys of the project's kind, commented out, with their defaults. Edit it next: set the title that the apps page shows and, if not everyone on the workspace should see the app, the groups that may.

In a git repository, the deploy records the commit it was built from. It warns when the directory has changed or untracked files, or files that git ignores, because the upload takes those as well and what runs then differs from the commit. With require-clean: true in velonde.yaml, the deploy refuses while a committed file has changes or velonde.yaml itself is not committed, and uploads the commit's files only, so untracked and ignored files neither block the deploy nor reach the app. A directory outside git deploys as well.

Redeploys

If you run velonde deploy again and neither the directory nor the workspace's base image has changed, the workspace skips the build. The output says nothing changed since the last deploy, and the workspace still stores .Renviron or .env as the app's secret. Use --force to build anyway.

If anything in the directory has changed, velonde.yaml included, the build runs. It reuses the cached layers of the packages unless the lock file or the system packages changed. The workspace pushes the image under the same name and adds an entry to velonde history. New sessions of the app start the new image, and open sessions keep the old one.

For an app or document, a change to title, description, access-groups, env, resources, prestart, seats-per-container or uses in velonde.yaml restarts the apps server (about a minute). An API or MCP server restarts with every new build, without failed requests. The velonde.yaml reference lists what a change to each key costs.

Reading the output

Every line starts with velonde:. These are the lines to look for:

  • warning: N changed or untracked file(s) …: the deploy goes ahead, and velonde history marks it with *. Commit first if the deploy should match a commit.
  • warning: N git-ignored file(s) or folder(s) … are uploaded as well: the same for files that git ignores, such as rendered output. Delete them, or set require-clean: true.
  • nothing changed since the last deploy …; not rebuilding: see Redeploys.
  • waiting for a build slot: other builds are running (the workspace's max_builds). The deploy continues by itself. When several people wait, the one with fewer builds running goes first.
  • system packages: …: the apt packages the build installs for the lock file and system-packages.
  • N variable(s) from .Renviron stored as the app's secret, followed by kept the values set with 'velonde env set' for: … for the keys that velonde env set overrides.
  • pushed … (sha256:…): the build succeeded. velonde history lists this digest.
  • app registered, new sessions of the app use this build, app settings changed, pre-started app: the apps server restarts …: what happened to a running app.
  • API service rolling out, MCP server rolling out, pipeline registered: the kinds that are not apps. The line says how to reach the result.
  • moves from internal to public (or another pair): audience changed, and the app moved to the other server. public: anyone can open it without login follows for a public app, with the number of viewers per container and the limit.
  • connection to the deploy service lost: the deploy service restarted or the network dropped. The build continues and the workspace records it when it ends. velonde history NAME shows it a minute later. The command exits with status 0, because the deploy has not failed.
  • The last line is the URL. If the output ends in velonde: FAILED, the lines above it are the build log. Read it from the bottom up.

A problem with what you uploaded stops the deploy before any build starts. It shows as a single line with an HTTP status, such as velonde: 400: velonde.yaml: …, without velonde: FAILED.

Checks before a deploy

Every deploy runs four checks. Your workspace admin decides for each one whether a finding stops the deploy, is only listed, or is not looked for (check_* in the workspace's configuration). The table shows the default. The checks run on the workspace, so the same rules apply to everyone who deploys, to the coding agents and to apps that deploy from a repository.

Check Default What it looks for
Secrets stops the deploy Passwords, API keys, tokens and private keys in any file of the project, including a password in a connection URL such as postgresql://user:password@host/db. The check uses the rules of gitleaks and two of the workspace's own.
Vulnerabilities stops the deploy Packages in renv.lock, uv.lock or the pinned lines of requirements.txt with a published vulnerability. The deploy stops when the vulnerability is rated high or critical, or has no rating, and a fixed version exists. Every other vulnerability is listed. The workspace keeps its own copy of the OSV database, so your package list does not leave the workspace.
Code listed Patterns that are a common way in for an attacker: running a shell command, building SQL by pasting text together, putting user input into HTML unescaped (HTML(input$…), unsafe_allow_html=True, tables with escape = FALSE), running code made from text (eval(parse(text = …)), eval()), loading pickles or YAML unsafely, and turning off the check of TLS certificates. Python code is checked with bandit.
Tests stops the deploy Every R and Python file parses, and the project's tests pass: tests/testthat with testthat for R, tests/ with pytest for Python. This check runs in the build, after the packages are installed.

An app with its own Dockerfile and an R or Python package get the first three checks. The workspace does not run tests in a Dockerfile it did not write, and a package runs its own with check: true in velonde.yaml (R and Python packages).

To see the result before you deploy, run velonde check in the project's directory (velonde::deploy_check() in R). It runs all four checks, the tests in your session, and changes nothing on the workspace.

The first three run before the build. When one of them stops the deploy, the output is a single message that starts with velonde: 422: the checks before the deploy found …. It lists each finding with its file and line, and nothing is built. Findings that do not stop the deploy appear as lines starting with warning: before the build log.

Fix a finding

  • A secret. Move it into .Renviron or .env next to the sources. The workspace stores those files as the app's secret and passes their values to the app as environment variables (see Environment and secrets). velonde env set does the same without a deploy. Then replace the secret where it was issued, because it has been in your code and possibly in your git history.
  • A vulnerability. Update the package: renv::update("pkg") and renv::snapshot() in R, uv lock --upgrade-package pkg in Python. The message names the version that fixes it.
  • Code. Change the code, for example to glue::glue_sql() or the params argument of DBI::dbGetQuery() for SQL.
  • A test. Run the tests in your session (testthat::test_dir("tests/testthat"), uv run pytest), fix them and deploy again.

Mark a finding as accepted

If a finding is not a problem for your app, mark it in the project. The mark is part of your code and visible to anyone who reviews it.

Check How
Secrets # gitleaks:allow at the end of the line, or the finding's fingerprint in a .gitleaksignore file.
Vulnerabilities An entry in osv-scanner.toml next to the lock file, with a reason and an end date: [[IgnoredVulns]], id = "GHSA-…", ignoreUntil = 2026-12-31, reason = "…".
Code # nosec on the line.

What the build has for tests

The tests run without the app's secrets, environment variables and network shares, because the build has none of them. A test that needs them can skip itself in the build: testthat::skip_on_ci() in R, or a check of the CI environment variable in Python, which the build sets. Tests that drive a browser (shinytest2, Playwright, Selenium) are left out, because the build has no browser.

When a build fails

Fix the first real error in the log. Lines starting with #N are build steps.

Message Cause Fix
cannot open shared object file in the load check A package needs a system library at run time. Run velonde sysreqs and add the apt package under system-packages.
there is no package called 'X' in the load check X is not in renv.lock. Run renv::install("X") and renv::snapshot(), then deploy again.
this workspace builds apps from a fixed package stack after a package that does not load In stack mode, the app uses a package outside the workspace's stack. Remove the package, or ask your workspace admin to extend the stack.
renv::restore() fails to install a package A compile error, usually from a missing -dev library. Run velonde sysreqs, then add the package under system-packages.
ModuleNotFoundError in python -c 'import …', or imports what is not installed A dependency is missing from uv.lock. Run uv add … and deploy again.
AttributeError: module 'app' has no attribute 'app' The FastAPI application object has another name. Name it app or api.
quarto render writes the Shiny document's app to this file A Shiny document in Python sits next to an app.py of yours. Rename your file, or move the document to a directory of its own.
a Dash app cannot run in warm or shared containers velonde.yaml of a Dash app sets prestart or seats-per-container. Remove both keys.
type script needs entry: <file>.R (or .py for script-python) A script needs its file named, unless the directory has a pipeline.R (or pipeline.py). Set entry: in velonde.yaml.
after: there is no pipeline …, after: pipeline … belongs to … A pipeline under after: does not exist, or does not admit the owner. Deploy it first, or ask its owner to add one of your groups to its access-groups.
email: this workspace sends report mail to … only An address under email: is outside the domains your workspace admin allows. Use an address of your company, or ask your workspace admin.
Requirement name … matches project name uv refuses because the directory has the same name as a package. Rename the project in pyproject.toml.
several .qmd files … set entry The directory has more than one document. Set entry: in velonde.yaml.
app.py … found but none of shiny, streamlit, dash, fastapi, vetiver or fastmcp is imported Detection could not tell the kind. Set type: in velonde.yaml.
velonde.yaml: … The manifest is invalid. The message names the key. Fix velonde.yaml.
uses: mounts a pipeline's store … needs a ReadWriteMany storage class This workspace cannot share store volumes between pods. Remove uses, or ask your workspace admin.
502: could not resolve system dependencies The package manager API did not answer. Retry. If it keeps failing, list system-packages by hand.
403: app 'X' belongs to … Another user owns an app of that name. Choose another name in velonde.yaml (--name on a first deploy), or ask the owner to add you as a maintainer.
403: velonde.yaml changes maintainers … You are a maintainer, and your velonde.yaml lists other maintainers than the app has. Write the values from the message into velonde.yaml, and ask the owner to make the change.
400: velonde.yaml: audience: external, but this workspace has no external apps server The workspace has no server for that audience. Ask your workspace admin to add it, or remove audience.
413: upload larger than 200 MB The directory contains large files, and the compressed upload exceeds 200 MB. Move them out.
exceeded quota on an app that will not start The workspace's quota is used up. Ask your workspace admin.

If an app builds, starts and then fails, it shows its error in the browser, and velonde logs NAME prints what it wrote to its output (Logs). Reproduce the error in your session first: run shiny::runApp(port = 3838) in one terminal and curl -s http://127.0.0.1:3838/ in another, or run uv run shiny run app.py.

Work on an app as a team

The person who deploys an app first owns it. There are two ways for others to work on the same app.

Maintainers. The owner lists people by user id under maintainers in the app's velonde.yaml, or groups under maintainer-groups, and deploys:

maintainers: [alice@example.com, bob@example.com]
maintainer-groups: [sales-analysts]

A maintainer can do with the app what its owner can do. They can deploy it and roll it back, set its secret variables, see its history and the key of an API, run a pipeline and read its logs, and bind the app to a repository or unbind it. Three things remain with the owner and workspace admins: deleting the app, changing the two maintainer keys, and handing the app to another owner with velonde owner, which also removes the maintainers. If a maintainer deploys a velonde.yaml whose maintainer keys differ from the app's, the workspace refuses the deploy, so that the file and the app do not drift apart. The maintainer then asks the owner to make the change.

The app keeps its owner when a maintainer deploys it. The pipelines under uses: must admit the owner, and a pipeline's runs call APIs as the owner.

A shared repository. Bind the app to a branch with velonde git bind, as Deploying from a repository describes. Every push to the branch deploys the app, so the people who may push to the branch decide what runs, and they need no session on the workspace to do it. The velonde commands on the app, such as velonde env set or velonde logs, remain with the owner, the maintainers and admins. A push that changes the maintainer keys in velonde.yaml fails to deploy, and velonde git status says why. The owner applies such a change by running velonde git bind again.

To get the code of an app that a colleague owns, run velonde clone <app>, as Working on an app's code together describes. That page also covers creating a repository for a new project on your company's git server.

Anyone who can deploy an app can read its secrets, because the code they deploy runs with them. This applies to maintainers and to everyone who may push to a bound branch. List only people you would give the app's secret variables to.

Publish outside the company

By default an app is for the people who log in to the workspace. The audience key in velonde.yaml publishes it to others. A workspace admin decides which audiences a workspace has, and each one has a host name of its own.

audience Who can open it Address
internal (the default) The people who log in to the workspace the apps host
external The people who log in to the workspace's second login, typically your customers with accounts at their own identity provider the external host
public Anyone on the internet, without a login the public host
title: Price calculator
audience: public

The deploy output ends with the address, and velonde apps shows the audience of every app. To move an app to another audience, change the key and deploy again. Both servers involved restart, which takes about a minute.

What changes with the audience:

  • Users. An external app sees the users and groups of the second login, and access-groups names those groups. One login can hold several of your customers, each as a group, so that every customer sees only their apps. A public app has no users: every visitor gets a random id that lasts for the visit, in the group ANONYMOUS, and access-groups has no effect.
  • Shared containers. A public app serves ten visitors from one container and at most fifty at the same time, unless seats-per-container and max-users say otherwise. Without such a limit, anyone could start containers until the workspace runs out of resources. Write the app so that one process can serve several visitors: keep per-visitor state inside the session, not in global variables.
  • Variables. An external or public app gets its own .Renviron and velonde env set variables only. The variables an admin sets for every app reach internal apps.
  • APIs and MCP servers. An external API takes a token of the second login's identity provider or the API key. It does not know the workspace's users, so a colleague calls it with the key as well. A public API takes no key at all: anyone can call it, and the API sees no caller. Identity never crosses from one audience to another. An external app that calls an internal API needs that API's key, and an internal MCP server is the only kind that the workspace registers in your assistants.

Anyone who may deploy may publish to every audience the workspace has. The deploy that moves an app to external or public asks you to confirm it, and so does a first deploy with either. Check what an app shows before you make it public: a pipeline store under uses: and every query in the code reach whoever opens it.

New projects

velonde new sales --template shiny in a terminal of an IDE session creates the directory sales from one of the workspace's templates. In R, velonde::new_app("sales", template = "shiny") does the same from the console, and in RStudio so does File > New Project > New Directory > Velonde project. velonde new without a name lists the templates your workspace offers.

An R template needs R, so you create its project in RStudio or VS Code. You get an renv project with the template's packages. A Python template needs uv, which every IDE has. You get a pyproject.toml and a uv.lock, with the packages installed into the project's .venv. Both kinds of project come with a velonde.yaml and a git repository with a first commit. On a workspace with AI assistants, the project also has a CLAUDE.md that tells the coding agent how the project is laid out. --repo (repo = TRUE in R) also creates the project's repository on your git server, as velonde git create does. The platform provides these templates:

Template Language Makes Entry
shiny R Shiny app with bslib and box modules app.R
plumber R HTTP API with plumber plumber.R
plumber2 R HTTP API with plumber2, Posit's successor to plumber plumber.R
mcp R MCP server: R functions as tools for Claude Code and Posit Assistant tools.R
quarto R Quarto HTML report with parameters and _brand.yml index.qmd
quarto-dashboard R Quarto dashboard, static or with server: shiny index.qmd
rmarkdown R R Markdown HTML report index.Rmd
targets R targets pipeline with a persistent store _targets.R
script R R script that runs as a pipeline pipeline.R
package R R package for the workspace's package repository, with tests DESCRIPTION
shiny-python Python Shiny for Python app app.py
streamlit Python Streamlit app app.py
dash Python Dash app app.py
fastapi Python HTTP API with FastAPI app.py
mcp-python Python MCP server: Python functions as tools for Claude Code and Posit Assistant, with FastMCP server.py
quarto-python Python Quarto HTML report with Python chunks index.qmd
notebook Python Jupyter notebook, with a kernel of the project's environment registered under the project's name analysis.ipynb
script-python Python Python script that runs as a pipeline pipeline.py
package-python Python Python package for the workspace's package repository, with tests pyproject.toml

Your workspace may replace these templates or add its own, which appear in the same list. A template of your workspace's own with a pyproject.toml is a Python template, any other an R template.