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:

PowerShellCopy
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 internal or your own certificate (VELOPHEX_TLS=tls /certs/tls.crt /certs/tls.key),
  • forwards WebSocket upgrades on /api/v1/robot/gateway and /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:

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

You then own these settings:

  1. Forward Connection: Upgrade and Upgrade: websocket on /api/v1/robot/gateway and /hubs/*.
  2. Set the idle timeout far above 15 seconds (an hour is sensible).
  3. Turn response buffering off on those routes.
  4. Pass the original Host header and set X-Forwarded-For and X-Forwarded-Proto.
  5. Set VELOPHEX_TRUSTED_PROXY_NETWORK to your proxy's network (a single machine is its address as /32).
  6. Allow request bodies of at least 512 MB.
  7. Prefer client affinity for the gateway, so a reconnecting Robot returns to the same instance.
  8. Pass the Authorization header through untouched on the WebSocket upgrade.

Firewall rules to create#

  1. Allow inbound TCP 443 to the Orchestrator host from users, Studio machines and Robot machines.
  2. Allow inbound TCP 80 only if you use a public name with Let's Encrypt.
  3. Allow outbound TCP 443 from every Robot machine to the Orchestrator host (and to your blob storage endpoint if you use one).
  4. Allow outbound SMTP from the Orchestrator host to your mail relay.
  5. 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#

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