Security model overview
How VeloPhex protects people, machines, secrets and packages across Studio, the Robot and the Orchestrator.
VeloPhex is built so that each component proves who it is, holds only the secrets it needs, and refuses anything it cannot verify. This page gives you the whole picture in one place. Each area links to a page with the details and the settings you control.
The trust boundaries#
A VeloPhex deployment has four kinds of actors, and each one authenticates differently:
| Actor | How it authenticates | Where the credential lives |
|---|---|---|
| A person in the web app | Local account (password, optionally with two-step sign-in or a passkey), or single sign-on through OpenID Connect (SAML 2.0 is in preview) | Server-side session in a browser cookie (HttpOnly, Secure, SameSite=Strict) |
| Studio and the Assistant | Browser sign-in (OAuth 2.0 authorization code with PKCE) that issues short-lived access tokens and a rotating refresh token | Windows Credential Manager |
| The Python SDK, scripts, CI | Personal access token (vpx_pat_…) |
Your CI secret store |
| A third-party application | OAuth client credentials for one tenant | Your application's secret store |
| A Robot machine | Its own key pair, OAuth client credentials with private_key_jwt (or, per tenant, mutual TLS) |
DPAPI-protected store on the machine; the private key never leaves it |
| A running automation | Execution token (vpx_rt_…) scoped to one job attempt |
Process memory of the executor, for the life of the attempt |
Every API endpoint requires an authenticated caller by default. A tenant or workspace you cannot see answers 404 Not Found, so the API never confirms that it exists. Inside a tenant you can see, a missing permission answers 403 Forbidden.
Identity and access#
- People sign in with local accounts or through an identity provider (OpenID Connect, including a Microsoft Entra ID preset, or SAML 2.0 in preview). Passwords are hashed with PBKDF2-HMAC-SHA512, and account lockout and password rules are enforced from the
securitysettings group. Local accounts can add two-step sign-in (TOTP) and passkeys, and a tenant can require a second factor. See Users and roles. - Authorization is permission-based. Built-in and custom roles are assigned to users or groups at tenant or workspace scope. See RBAC and permissions.
- Machines enroll once with a single-use enrollment key and then authenticate with short-lived tokens signed by their own key. See Robot identity and tokens.
Secrets#
Assets of type Secret and Credential are envelope-encrypted with AES-256-GCM under a per-tenant data key, which is itself wrapped by a key-encryption key (KEK) that you supply. A job claim never carries a password: the Robot redeems a credential lease, bound to that job attempt, just before the automation starts. See Secrets and encryption.
Tenancy#
A tenant is the organization boundary. All tenants in one Orchestrator share one database schema, with a tenant identifier on every tenant-owned row. Isolation is enforced by route authorization and by data access that is always scoped to the caller's tenant. Blob storage is partitioned by tenant path and every tenant has its own package feed.
Choosing a deployment model
If you need hard separation between organizations, run one Orchestrator per organization. The on-premises and dedicated cloud models both give you a cell of your own. See Deployment options.
Network#
Robots connect outbound only, over HTTPS (plus one outbound WebSocket when the tenant uses the WebSocket command channel). No inbound port is opened on a Robot machine. The Orchestrator terminates TLS in its bundled Caddy front door, sends HSTS and a Content Security Policy, and answers only on its configured host name. See Network and firewall.
Packages and supply chain#
Every package format in the platform uses one signing implementation: a detached velophex/signature.json verified against pinned signers. VeloPhex's own packages must carry the VeloPhex signature everywhere. Your own packages can be signed and, when you choose, required to be signed. Every release ships a CycloneDX SBOM, third-party notices and SHA256SUMS. See Package signing and supply chain.
Execution on the Robot#
Each job attempt runs in its own executor process inside a Windows Job Object, which ends the process tree when its parent closes and applies memory and process-count limits. The executor starts with an environment built from empty, and its control frames are HMAC-authenticated. Local inter-process communication uses named pipes that check the caller's Windows identity.
Activities are trusted code
Activity packages declare capabilities such as FileSystem, Network or Credentials. Studio shows them when you install a package, as a consent signal. They are not a sandbox: an activity runs with the rights of the job's run-as account. Install only packages you trust, and use signing to control what your Robots accept.
Auditing#
Security-relevant changes (sign-ins, roles, assets, packages, jobs, queues, triggers, machines, tokens and applications) are written to an append-only audit trail you can search in the web app and through the API. See Audit log.
Your responsibilities#
VeloPhex encrypts secrets at the application level, but the database volume, the blob store and your backups are yours to protect. Use encrypted disks or your cloud provider's storage encryption, keep the KEK in escrow, and restrict who can reach the Docker host. The Hardening checklist lists every step in order.
Next steps#
- Work through the Hardening checklist before you go live.
- Report a vulnerability through Responsible disclosure.
The trust boundaries
Identity and access
Secrets
Tenancy
Network
Packages and supply chain
Execution on the Robot
Auditing
Your responsibilities
Next steps