Skip to content

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.