Settings

The Orchestrator's settings groups, how platform and tenant values combine, and how to change them in the web app or the API.

The Orchestrator has two layers of configuration:

  • Deployment configuration is read at start from .env and velophex.prod.env: host names, secrets, database, storage provider, process role. Changing it means recreating the container. See Install on-premises.
  • Settings groups are stored in the database and changed at run time from the web app or the API. This page is about them.

Platform values and tenant overrides#

Each settings group is stored once at platform scope and optionally once per tenant. A tenant value overrides the platform value field by field: fields the tenant leaves empty fall back to the platform. Platform administrators edit platform values; tenant administrators edit their tenant's overrides.

Group What it controls Scope
general Time zone, the web app base URL used in links, alert emails on or off, personal workspaces, and a default workspace for new members Platform and tenant
security Failed sign-ins before lockout, lockout minutes, password minimum length and required character classes (upper, lower, digit, symbol), password expiry days, session timeout minutes, requireMfa, and whether Studio may start design-time runs Platform and tenant
email Whether email is on, SMTP host, port, user, password, TLS/SSL, from address Platform and tenant
retention Retention windows for execution logs, jobs, queue items, audit events and notifications Platform and tenant
robots commandChannel (https or websocket), attendedAuth (how Assistant starts are authenticated), tokenEndpointAuthMethod (private_key_jwt or self_signed_tls_client_auth), and default Robot settings: log level, RDP fallback, screen resolution, colour depth, heartbeat interval Platform and tenant; tokenEndpointAuthMethod tenant only
uiAutomation The tenant's UI automation policy: failure screenshots, scripts, hardware input, incomplete searches, fuzzy-match floor Platform and tenant
expressions The expression policy packages are checked against Platform and tenant
packages requireSignedPackages: refuse unsigned or untrusted publishes. Can only tighten the deployment's own setting Platform and tenant
storage The blob store provider and its connection Platform only

Secret fields (the SMTP password, storage secrets) are write-only: they are stored encrypted and are never returned after you save them.

Change a setting in the web app#

Prerequisites: settings.edit in the tenant, or platform administrator rights for platform values.

  1. Open the tenant's Settings page (or Platform admin, Settings, for platform values).
  2. Choose the group.
  3. Change the fields and save.

Verify: reload the page. You should see the saved values, and fields you left empty showing the inherited platform value.

Change a setting with the API#

List the groups, read one, and write it:

HTTPCopy
GET /api/v1/tenants/{tenantId}/settings/groups
GET /api/v1/tenants/{tenantId}/settings/security
PUT /api/v1/tenants/{tenantId}/settings/security
Content-Type: application/json

{ "maxFailedLogins": 5, "lockoutMinutes": 15, "passwordMinLength": 12 }

Platform values use the same shape under /api/v1/platform/settings/{group} (platform administrators). Reading a tenant's groups needs settings.view and writing needs settings.edit. GET …/settings/{group}/layers shows the default, platform and tenant layers separately. An unknown group name or an out-of-range value is refused with 400.

To check outbound mail after you change the email group:

HTTPCopy
POST /api/v1/tenants/{tenantId}/settings/email/test

You should receive a test message at your own address.

Common tasks#

Move a tenant to the WebSocket command channel#

By default, Robots poll for commands over HTTPS. The WebSocket gateway pushes commands the moment they are written, and is enabled per tenant:

HTTPCopy
PUT /api/v1/tenants/{tenantId}/settings/robots
Content-Type: application/json

{ "commandChannel": "websocket" }

Before you switch, confirm that your front door forwards WebSocket upgrades with an idle timeout well above 15 seconds and buffering off. Set "https" to go back; any other value is refused.

One tenant at a time

Switch one tenant, watch it for a working day, then move the next. Unacknowledged commands are never lost when you switch in either direction, because both channels deliver from the same command table.

Tighten sign-in rules#

Set passwordMinLength, the passwordRequire* flags and maxFailedLogins in the security group. New rules apply to the next password change and the next sign-in attempt.

Require a second factor#

Set requireMfa to true in the security group. See Two-step sign-in and passkeys.

Change retention#

See Retention for the windows and their allowed ranges.

Storage#

The blob store is chosen once, by a platform administrator, in the first-run /setup page or through deployment configuration (Storage__Provider with Storage__S3__* or Storage__Azure__* keys). Platform admin, Storage shows it and lets you test the connection and change credentials. The provider and location cannot change once the store holds blobs.

Deployment configuration keys#

Any application setting can also be supplied as an environment variable in velophex.prod.env, using double underscores for nesting, for example Retention__IntervalMinutes=60 or Kestrel__Limits__MaxConcurrentConnections=16000. Recreate the API container to apply them:

BashCopy
docker compose -f docker-compose.core.yml up -d api

Next steps#

Platform values and tenant overrides

Change a setting in the web app

Change a setting with the API

Common tasks

Move a tenant to the WebSocket command channel

Tighten sign-in rules

Require a second factor

Change retention

Storage

Deployment configuration keys

Next steps