velonde.env reference
This page lists every typed setting in a workspace's velonde.env, for the person who configures the
workspace. Each line holds one key and a plain-text value, without quotes. A key left empty takes the
default given here.
Features
| Key |
Default |
Meaning |
features |
|
What the workspace is for, as a comma-separated list of r, python, deploy and packages (the package repository, which needs deploy). It selects the rules, skills, plugins and instructions the coding agents get. The installer writes r,python,deploy, or the list you give with --features. When it is empty, the agents get none of the content tied to a feature. The IDE tiles and the deploy component are chosen in kustomization.yaml. A change needs an image build. |
ai |
true |
Set to false for a workspace without any AI: the IDE images come without Claude Code and Posit Assistant, and the workspace ships no agent content and no AI packages. A change needs an image build. |
claude_login_method |
|
Which kind of Anthropic account Claude Code accepts at sign-in: claudeai for a Claude subscription (Team or Enterprise), console for an API account of the Claude Console. When it is empty, any account works, a private one included. It takes effect in new sessions after the next apply. |
claude_login_org |
|
The UUID of your organisation at Anthropic. With it set, only members of that organisation can sign in to Claude Code. Set it together with claude_login_method when company code must not be handled under a private account's terms. |
Branding
The name, logo and favicon of every page of the workspace: the IDE tiles, the apps page and the
external and public servers. Branding describes how to give each server
pages of its own.
| Key |
Default |
Meaning |
brand_name |
Velonde on the IDE server, Apps on the app servers |
The name in each page's title and navigation bar. It may not contain ${ or #{. |
brand_logo |
|
A logo shown in the navigation bar, as the path of an image file in the overlay directory, such as branding/logo.svg. |
brand_favicon |
|
The icon browsers show in the tab, as the path of a file in the overlay directory, such as branding/favicon.ico. |
A change needs only an apply. The servers whose pages change restart without interrupting
open sessions, and the apps server needs about a minute to come back for new visitors.
Registry
The workspace keeps its images in a registry: the IDE and base images with your layer, and every app
it builds. This is either the platform's own registry behind the Ingress, or one you provide.
| Key |
Default |
Meaning |
registry |
|
Host name of the registry. For the platform's own registry, this is the host name its Ingress serves. Otherwise it is the host name of the registry you provide. With a registry you provide, the value may also be a host followed by a path, such as harbor.acme.com/velonde-test. The workspace's images are then named <path>/velonde/<name> and <path>/apps/<name>. Give every workspace that shares a registry host, or an ECR account and region, a path of its own: without one, two workspaces overwrite and delete each other's images. |
registry_insecure |
false |
Set to true for a registry reached over plain HTTP. Use it only for a throwaway cluster, because every node must be configured with the registry's address. |
user_networks |
|
The private networks that user code and the deploy service may reach, separated by spaces: each a network such as 10.20.0.0/16, or a network with ports such as 10.0.5.10/32:5432,443. Sessions, apps, APIs, builds and pipeline runs reach the internet and their own namespace, and no private address (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10), because the cluster's nodes, other namespaces and storage have such addresses. List your databases, package mirrors, IdP and git server here when they do too. On a cluster whose workspace host names resolve to private addresses, those belong here on ports 80 and 443; the installer writes them. A connection to a private address that is not listed times out. A change takes effect at the next apply. |
egress |
open |
How user code reaches the internet. With open, sessions, apps, APIs, builds and pipeline runs reach any address that is not private. With proxy, they reach the internet only through a proxy in the workspace's namespace, and only the hosts on its allow-list, on ports 80 and 443. The platform's list covers the package repositories (CRAN, Posit Package Manager, R-universe, Bioconductor, PyPI), GitHub, GitLab and Bitbucket, the coding agents and their model providers, Hugging Face, Open VSX, npm, and Ubuntu's and Docker Hub's for builds. You add hosts in egress-allow.txt in the overlay. Only HTTPS goes through the proxy, so a plain-HTTP download from the internet fails. A host that is not on the list answers with status 403 from the proxy, and the proxy's log names it. The deploy service is not behind the proxy. After a change, apply, restart the ShinyProxy pods and the deploy service, and start sessions again. Switching back to open removes the proxy at the apply. |
registry_storage |
filesystem |
Where the platform's own registry keeps images: filesystem (a volume) or s3 (the object store below). With s3 the registry is stateless. |
registry_backend |
distribution |
For a registry you provide: distribution for any v2 registry such as Harbor, or ecr. With ecr, the overlay lists the registry/ecr component and no registry-pull entry under secretGenerator, and secrets.env needs no registry-password: the workspace reaches ECR with its IAM role. |
registry_user |
velonde |
The user name of the registry credential, if it is not velonde. The password is registry-password in secrets.env. |
Single host
Only the host setup reads these keys. An upgrade to the version you run applies a change to
them. On a cluster, the ingress handles TLS itself.
| Key |
Default |
Meaning |
acme_email |
|
The e-mail address Let's Encrypt sends notices about the host's certificates to. The installer requires it unless tls_cert and tls_key are set. |
tls_cert, tls_key |
|
Two files on the host with your own certificate for the host names, as absolute paths. When set, the workspace uses them instead of Let's Encrypt. The installer gives the group caddy read access to both files, since the web server reads them as the user caddy. To renew, copy the new files over the old ones and run sudo systemctl reload caddy. |
Mail and alerts
The mail account sends the alert mail of the monitoring stack, which is optional (see
Operating a workspace), the mail behind ShinyProxy's
"Report issue" button, and the mail that scheduled reports send after a render
(Mail after a render). Its password is smtp-password in secrets.env. The installer's
--monitoring option fills these keys in.
| Key |
Default |
Meaning |
smtp_host |
|
The SMTP server. Without it, the workspace sends no mail and shows no "Report issue" button. |
smtp_port |
587 |
The server's port. The workspace uses STARTTLS, or TLS from the start on port 465 for report mail. |
smtp_from |
|
The sender address. |
smtp_user |
the sender |
The login at the server, if it is not the sender address. |
alerts_to |
|
Who receives alert mail and issue reports. One address, or several separated by commas. The monitoring stack needs it. |
report_email_domains |
the domain of smtp_from |
The domains that the email: of a scheduled report may write to, separated by commas. Anyone who may deploy can set email:, so without this limit they could make the workspace's mail account write to anyone. The mails about a failed run or build go to owners and maintainers in these domains only. |
Release
| Key |
Default |
Meaning |
image_tag |
set by the installer |
The release the workspace runs, for example v1.0.0. The installer sets it on every install, upgrade and rollback. Changing it rolls the platform: new sessions start on the new images, and apps are rebuilt on their next deploy. |
Storage and object store
| Key |
Default |
Meaning |
home_size |
20Gi |
Size of a user's home volume. It applies when the volume is created at the user's first session. To grow an existing volume, patch its volume claim, as described in Operating a workspace. |
object_store_endpoint |
|
URL of an S3-compatible object store. Leave it empty for AWS S3 itself. The registry uses the object store with registry_storage=s3, and backups use it. The keys go in secrets.env. |
object_store_bucket |
|
The object store's bucket. |
object_store_region |
|
The object store's region. Empty means us-east-1, which S3-compatible stores accept. |
backups |
|
true backs the workspace's namespace up into the object store every day at 02:00, keeps each backup 30 days, and takes one before every upgrade. Operating a workspace has the restore steps. The installer's --bucket option sets this and the keys above. |
loki_s3_from |
|
The date from which logs are stored on the object store. On a workspace that already has logs, use tomorrow's date. On a new workspace, any past date works. It takes effect only on a workspace with the monitoring stack whose monitoring/kustomization.yaml lists the loki-s3 component. Without that component, logs stay on a volume. |
Redis
These keys apply only with the redis/external component. The workspace's own Redis needs none of
them.
| Key |
Default |
Meaning |
redis_host |
|
Host name of your Redis. |
redis_port |
6379 |
Port of your Redis. |
Package repository database
These keys apply only with the packages-db/external component. The repository's own
PostgreSQL needs none of them.
| Key |
Default |
Meaning |
packages_db_url |
|
Your PostgreSQL database as a JDBC URL, for example jdbc:postgresql://db.example.com:5432/rdepot. |
packages_db_user |
|
The database user. It must own the database, because the repository creates and migrates its tables. The password is packages-db-password in secrets.env. |
R packages
| Key |
Default |
Meaning |
r_snapshot |
latest |
The snapshot date of the package repository that the stack and every app build install from, for example 2026-09-01, or latest. Pin a date for reproducible builds. The date may not be older than the snapshot that the release's own images were built from, because the IDEs would then hold newer packages than a deploy can restore. The image build refuses such a date and names the earliest one. A change needs an image build. |
cran |
|
The full URL of your own repository, used instead of the public one, for example https://ppm.acme.internal/cran/__linux__/noble/2026-09-01. With a Posit Package Manager URL, builds still get Linux binaries. A plain mirror means packages build from source. A change needs an image build. |
sysreqs_api |
|
Where app builds look up system dependencies. Leave it empty for the public service, give a Posit Package Manager's .../__api__/repos/<repo>/sysreqs, or set none. With none, builds install only the system-packages listed in velonde.yaml. |
deploy_mode |
renv |
With renv, an app restores its own lock file on top of the stack. With stack, an app may use only the stack's packages and may not list system-packages in velonde.yaml, and builds take seconds. |
deploy_allow_dockerfile |
false |
Whether an app directory with its own Dockerfile is built from it, as it is, without a restore, system packages, the load check or the tests, and on a base image of its own choosing. Leave it off unless your teams need it: the workspace's consistency rests on its own base images. |
deploy_dockerfile_groups |
everyone |
With own Dockerfiles allowed, the groups whose members may deploy one, separated by commas. Velonde admins always may. |
deploy_dockerfile_images |
the workspace's base images |
With own Dockerfiles allowed, the base images they may start from: prefixes such as registry.acme.com/data-images/ for your own approved images, or python:3.12 for an official image on Docker Hub, separated by commas. Empty means the workspace's own velonde/shiny-base and velonde/python-base, and * any image. The workspace's IDE images and other apps are refused in any case. After a change of these three keys, apply and run kubectl rollout restart deploy/velonde-deploy -n <namespace>. |
Python
| Key |
Default |
Meaning |
py_snapshot |
|
The date that pins package resolution in the IDEs and in app builds. When empty, the newest versions are used. A change needs an image build. |
pypi_index |
|
Your own package index, used instead of PyPI. A change needs an image build. |
Sessions
| Key |
Default |
Meaning |
ide_idle_timeout |
never |
How many milliseconds an IDE session keeps running without an open browser tab before the workspace stops it. Files on the home volume persist. The R process and unsaved editor state are lost. -1 or an empty value means sessions are never stopped. |
ide_max_instances |
3 |
How many sessions of one IDE a user may run at the same time, each with its own size. Set it to 1 for one session per IDE. |
ide_sizes |
all |
The sizes users can choose when they start an IDE session: all (Small, Standard and Large) or small (Small only). With small, users do not see the other two sizes, and Small is preselected. Use it on a workspace for people you do not know, such as a trial for visitors. After a change, apply and restart the workspace's ShinyProxy pods (kubectl delete pod -l app=shinyproxy -n <namespace>). Running sessions continue. |
ide_packages |
true |
Whether admins can add system packages to the IDE images with velonde ide-packages. The workspace's deploy service then builds the images with those packages on top, in your registry. Set it to false if your policy allows only images from your own build pipeline. The IDEs then start the images as built, and the command refuses. A workspace without the deploy service has no such images either. |
Deploys
| Key |
Default |
Meaning |
max_builds |
2 |
How many builds run at the same time. Further deploys wait in line. |
app_max_memory, app_max_cpu |
8Gi, 4 |
The most memory and CPU that one app's velonde.yaml may ask for under resources. A deploy that asks for more is refused. |
app_max_prestart |
3 |
The most warm containers that one app may keep (prestart in velonde.yaml). |
app_max_store_size, app_max_timeout |
50Gi, 1440 |
The largest store and the longest run, in minutes, that one pipeline may ask for (store-size and timeout in velonde.yaml). |
default_access |
workspace |
Who can open an app, call an API or use an MCP server whose velonde.yaml sets neither access-groups nor access-users. With workspace, everyone who logs in can. With owner, only its owner and maintainers can, velonde apps lists only their own apps, and messages about another user's app do not name its owner. Use owner on a workspace whose users do not know each other. After a change, apply and run kubectl rollout restart deploy/velonde-deploy deploy/velonde-auth -n <namespace>. |
app_max_per_user |
no limit |
How many apps, documents, APIs, pipelines and packages one user may own. A deploy under a new name beyond that is refused. Velonde admins are not limited. |
ingress_class |
traefik |
The ingress class for the Ingress of each deployed API. Any class works, because the API's authentication runs as a sidecar in its pod. |
ingress_namespace |
kube-system |
The namespace your ingress controller runs in. The workspace's network policies let it reach the IDE server, the APIs, the registry and the package repository and nothing else from outside the workspace's namespace, and let app builds and the deploy service reach it. On a cluster whose controller runs in a namespace of its own, as it usually does when installed with Helm, every host name times out and builds cannot reach the registry until you set this. |
api_tls_secret |
|
On a cluster whose ingress controller terminates TLS itself: the name of the TLS Secret for the apps host name, which the Ingress of each API then names in its tls block. Leave it empty on a single host or behind a proxy that terminates TLS. |
external_tls_secret, public_tls_secret |
|
The same for the host names of the external and public servers, for the Ingresses of external and public APIs. |
timezone |
UTC |
The time zone in which pipeline schedules (schedule: in velonde.yaml) are read. The installer sets it to the time zone of the machine it runs on. |
Checks before a deploy
Each key takes block, warn or off. With block a finding stops the deploy, with warn
the deploy goes on and the output lists the finding, and with off the check does not run.
Checks before a deploy describes what each check
looks for. A change takes effect when the deploy service restarts: apply, then run
kubectl rollout restart deploy/velonde-deploy -n <namespace>.
| Key |
Default |
Meaning |
check_secrets |
block |
Passwords, keys and tokens written into the sources. |
check_vulnerabilities |
block |
Known vulnerabilities in the packages of renv.lock, uv.lock and the pinned lines of requirements.txt. With block, only a vulnerability rated high or critical, or not rated, for which a fixed version exists stops the deploy. The others are listed. In stack mode this check does not run, because apps use the packages of the workspace's images. |
check_code |
warn |
Code patterns that are a common security risk, such as a shell command, SQL built from pasted text, or TLS certificate checks turned off. |
check_tests |
block |
Every R and Python file parses, and the tests in tests/ pass. These run in the build. |
vulnerability_db_url |
OSV |
Where the deploy service downloads the vulnerability database each day: OSV's public copy at https://osv-vulnerabilities.storage.googleapis.com, or a mirror with the same layout (<url>/PyPI/all.zip, <url>/CRAN/all.zip) for a workspace without internet access. none turns the download off, and the vulnerability check then reports that it has no database. |
Git server
These keys name your company's git server, on which users create repositories for their
projects with velonde git create or the "Create a repository" option of a new project, as
Working on an app's code together describes. Each user does this with their
own token, and the workspace stores no credential for the server. Leave git_forge empty to turn
this off. Cloning and pushing work with any git server either way. After you change a key,
apply the overlay and restart the deploy service with
kubectl rollout restart deploy/velonde-deploy -n <namespace>.
| Key |
Default |
Meaning |
git_forge |
|
github or gitlab. GitHub Enterprise Server and self-managed GitLab count as these. |
git_forge_url |
https://github.com or https://gitlab.com |
The https address of the server, for example https://gitlab.example.com. |
git_forge_group |
|
The organisation (GitHub) or group path (GitLab, for example analytics/apps) in which new repositories are created. Empty means the user's own account. |
Cluster
These keys are for a cluster. On a single host, the installer sets single_node=true for you,
and the other keys stay empty.
| Key |
Default |
Meaning |
single_node |
false |
Set to true when the workspace runs on one machine. Pipeline stores that apps mount can then be shared without a ReadWriteMany class. |
storage_class_rwx |
|
A ReadWriteMany StorageClass (EFS, CephFS) for pipeline stores that apps on other nodes mount. If neither this key nor single_node is set, the workspace refuses uses: in velonde.yaml. |
session_pool |
false |
Set to true on a cluster whose nodes for user code carry the label and taint hub.linnerprogramming.com/pool=sessions. Sessions, apps, builds and pipeline runs then run only on those nodes, and the platform's pods stay on the others. An autoscaler can scale that pool. Leave it empty on a single host: its node carries no such label, so sessions and apps could not start. After a change, apply and restart the workspace's ShinyProxy pods and the deploy service (kubectl delete pod -l app=shinyproxy, kubectl rollout restart deploy/velonde-deploy); running sessions stay where they are. |
build_pool |
false |
Set to true on a cluster with nodes of their own for builds, labelled and tainted hub.linnerprogramming.com/pool=builds. The build pods then run only on those nodes. A build pod runs BuildKit as root with SYS_ADMIN, NET_ADMIN and SYS_PTRACE inside a user namespace of its own and without seccomp and AppArmor profiles, which is what a cluster's security policy may want kept away from other workloads. Without it builds run with the sessions (session_pool) or on any node. After a change, apply and restart the deploy service (kubectl rollout restart deploy/velonde-deploy). |
Tokens at APIs and MCP servers
Inside the workspace, a deployed API or MCP server is called with the caller's identity. From outside,
it is called with its API key. With the keys below set, a token from your identity provider also
works from outside: a script or another service sends Authorization: Bearer <token>, and the
API sees the user and groups behind the token.
| Key |
Default |
Meaning |
api_token_issuer |
|
The OpenID Connect issuer, for example https://cognito-idp.<region>.amazonaws.com/<pool id> or https://<keycloak>/realms/<realm>. When empty, the workspace accepts no tokens and the API key remains the only way in from outside. |
api_token_client_id |
|
The client the workspace logs people in with. Tokens of this client stand for people. A token of any other client stands for a machine, which access-clients in an API's velonde.yaml admits. |
api_token_user_claim |
email |
The claim that holds the user id. |
api_token_groups_claim |
cognito:groups |
The claim that holds the groups. With another identity provider, set it to that provider's claim, for example groups. With Cognito, send the ID token, because it carries the email. The installer's --auth oidc sets these four keys. |
The keys external_token_issuer, external_token_client_id, external_token_user_claim and
external_token_groups_claim do the same for APIs and MCP servers with audience: external,
with the identity provider of the external server's login. They have the same defaults. A
token of the workspace's own provider is not accepted there, and a token of the external provider is
not accepted at internal APIs.