Network and firewall
Which ports and connections VeloPhex needs, why Robots are outbound-only, and how to configure the front door and your firewall.
VeloPhex keeps the network footprint small. The Orchestrator accepts HTTPS on one host name. Robots and Studio only ever connect out to it. No component needs an inbound port on a Windows machine.
Connection map#
| From | To | Port and protocol | Purpose |
|---|---|---|---|
| Users' browsers | Orchestrator host name | TCP 443, HTTPS (HTTP/2) | Web app and SignalR live updates (/hubs/*) |
| Studio, Python SDK, CI | Orchestrator host name | TCP 443, HTTPS | Sign-in, package feed, publishing |
| Robots | Orchestrator host name | TCP 443, HTTPS | Token, claims, leases, results, package downloads |
| Robots | Orchestrator host name | TCP 443, WebSocket (/api/v1/robot/gateway) |
Pushed commands, when the tenant uses the WebSocket channel |
| Robots | Your storage endpoint | TCP 443, HTTPS | Package downloads by short-lived grant, when blobs are in S3-compatible or Azure Blob storage |
| Internet (ACME) | Orchestrator host | TCP 80, HTTP | Let's Encrypt validation and redirect to 443 (public names only) |
| Orchestrator host | Your SMTP server | Your SMTP port (587 by default) | Invitation and notification email |
| Orchestrator host | Your identity provider | TCP 443, HTTPS | Single sign-on metadata and token validation, when you use SSO |
| Orchestrator host | Your OTLP collector | Your collector port | Optional traces and metrics |
Inside the Docker host, the API listens on 127.0.0.1:8080 (VELOPHEX_HTTP_BIND) for local health checks and for a proxy of your own. PostgreSQL and Redis are reachable only on the stack's private network.
Robots connect outbound only#
A Robot makes HTTPS calls for everything it does: getting tokens, claiming jobs, renewing leases, posting results and downloading packages. When a tenant uses the WebSocket command channel, the Robot also holds one outbound WebSocket to /api/v1/robot/gateway, carrying binary Protobuf frames. Nothing connects to the Robot.
The HTTPS command cursor is the default channel. The WebSocket gateway is opt-in per tenant through the commandChannel value in the robots settings group. See Settings.
Robots behind an HTTP proxy
The Robot sends all its outbound traffic (HTTPS calls, the WebSocket, package downloads, and the proxy settings it passes to the workflow executor and to uv) through one proxy setting. By default it uses the machine's WinHTTP proxy (netsh winhttp show proxy). The service runs as LocalSystem, so a proxy configured only in a user's browser has no effect on it. To set an explicit proxy, from an elevated prompt:
VeloPhex.Robot.Service.exe configure --proxy http://proxy.corp.example:8080 --proxy-bypass "*.corp.example;<local>"
Restart-Service VeloPhexRobot
--proxy-default-credentials true authenticates as the machine account (Negotiate/NTLM), and --proxy-user with --proxy-password-stdin stores a named proxy user's password encrypted. --proxy system or --proxy none switches back. status prints the proxy in use.
The front door#
The Compose stack ships Caddy as its TLS front door. It:
- obtains and renews a certificate automatically for a public name, or uses
VELOPHEX_TLS=tls internalor your own certificate (VELOPHEX_TLS=tls /certs/tls.crt /certs/tls.key), - forwards WebSocket upgrades on
/api/v1/robot/gatewayand/hubs/*with buffering off, - sets an idle timeout of 5 minutes, far above the 15-second heartbeat,
- limits request bodies to 512 MB on API routes, which is the package upload limit.
The API adds security headers to every response: Strict-Transport-Security (HSTS, on HTTPS requests), Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options, Referrer-Policy and Permissions-Policy. Outside development, it answers only its own host name and refuses any other Host header with 400.
Trusted proxy network#
The API reads the client address and scheme from X-Forwarded-* headers, and trusts them only from VELOPHEX_TRUSTED_PROXY_NETWORK (CIDR). The Compose file creates the stack's network with exactly the default subnet, so with the shipped Caddy you do not need to change it. The API refuses to start without a value, because a wrong value makes the sign-in rate limit one bucket for everyone, stops HSTS, and records the proxy's address in every audit event.
Rate limiting#
A global per-IP limit runs before authentication, followed by named policies for sign-in, registration, uploads and feed reads. Authenticated Robot calls are limited per machine (600 a minute) and per tenant, never per address, so a fleet behind one NAT address is not throttled as one caller; failed Robot authentication is limited per address. Limits are held in memory in each API process and are not shared between replicas. A client that exceeds a limit receives 429 Too Many Requests with Retry-After.
Using your own load balancer#
You can start the stack without Caddy and point your own proxy at VELOPHEX_HTTP_BIND:
docker compose -f docker-compose.core.yml up -d postgres redis api
You then own these settings:
- Forward
Connection: UpgradeandUpgrade: websocketon/api/v1/robot/gatewayand/hubs/*. - Set the idle timeout far above 15 seconds (an hour is sensible).
- Turn response buffering off on those routes.
- Pass the original
Hostheader and setX-Forwarded-ForandX-Forwarded-Proto. - Set
VELOPHEX_TRUSTED_PROXY_NETWORKto your proxy's network (a single machine is its address as/32). - Allow request bodies of at least 512 MB.
- Prefer client affinity for the gateway, so a reconnecting Robot returns to the same instance.
- Pass the
Authorizationheader through untouched on the WebSocket upgrade.
Firewall rules to create#
- Allow inbound TCP 443 to the Orchestrator host from users, Studio machines and Robot machines.
- Allow inbound TCP 80 only if you use a public name with Let's Encrypt.
- Allow outbound TCP 443 from every Robot machine to the Orchestrator host (and to your blob storage endpoint if you use one).
- Allow outbound SMTP from the Orchestrator host to your mail relay.
- Block everything else inbound to the Docker host, including 8080, 5432 and 6379.
Verify: on a Robot machine, run "%ProgramFiles%\VeloPhex\Robot\VeloPhex.Robot.Service.exe" status. You should see connectivity: Connected.
Next steps#
- Install the stack: Install on-premises.
- Diagnose a Robot that will not connect: Logs and troubleshooting.
Connection map
Robots connect outbound only
The front door
Trusted proxy network
Rate limiting
Using your own load balancer
Firewall rules to create
Next steps