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
.envandvelophex.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.
- Open the tenant's Settings page (or Platform admin, Settings, for platform values).
- Choose the group.
- 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:
HTTPCopyGET /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:
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:
HTTPCopyPUT /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:
docker compose -f docker-compose.core.yml up -d api
Next steps#
- Retention
- Users and roles
- Network and firewall before you enable the WebSocket channel
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