Sizing guidance

Choose host resources, database connections and storage for an Orchestrator cell, based on the measured and documented figures.

This page gives the figures VeloPhex publishes for sizing a self-hosted cell and explains what each one depends on. Treat every number as a starting point, then measure your own workload. Your automations, not the Orchestrator, usually decide how many Robots you need.

Minimum host for Docker Compose#

The single-node Docker Compose stack (Caddy, the Orchestrator in role all, PostgreSQL 18 and Redis) needs at least:

Resource Minimum
OS Linux x86-64 with Docker Engine 27 or later and Compose v2
CPU 4 vCPU
Memory 8 GB
Disk 40 GB, plus the space your packages need

The compose file sets container memory ceilings that fit this host. You can change them in .env:

.env (defaults)INICopy
VELOPHEX_API_MEMORY_LIMIT=2g
VELOPHEX_POSTGRES_MEMORY_LIMIT=2g
VELOPHEX_REDIS_MEMORY_LIMIT=512m
VELOPHEX_CADDY_MEMORY_LIMIT=2g

Raise the PostgreSQL limit when you tune PostgreSQL's own memory settings upward.

What the measurements say#

Figure Context
1,000 connected Robots, 1,000 job starts per minute, 0 failures Certified for the 0.8.0 release candidate on the development topology. p50 start-to-claim 145 ms, every HTTP call under 200 ms.

Larger fleets are not certified. If you plan a fleet beyond 1,000 Robots, start from a single well-provisioned cell, measure, and give the database and the proxy their own hosts early: in uncertified larger test runs, the fleet, the database and the proxy competed for the same CPUs.

Database connections#

The database is sized with the cell:

Setting Default Where
API connection pool 100 VELOPHEX_DB_POOL_SIZE in .env
PostgreSQL max_connections 200 VELOPHEX_POSTGRES_MAX_CONNECTIONS in .env

A pool that is too small does not fail loudly: statements wait for a free connection, time out after 10 seconds, and clients retry, which adds load. If you run several Orchestrator processes against one database, they share max_connections, so divide the pool between them.

If you use a managed PostgreSQL 18 instead of the bundled container, it must allow the pg_trgm extension. Set Database__ConnectionString in velophex.prod.env and scale the postgres service to zero.

Connections at the front door#

Each process runs with production connection ceilings of 16,000 concurrent connections and 12,000 upgraded (WebSocket) connections. When the WebSocket ceiling is reached, the gateway answers 503 with Retry-After: 30; the Robots it turns away keep working over HTTPS and reconnect later. See Performance tuning to change these limits.

The bundled Caddy is given memory for the TLS sessions of a large fleet. If you put your own load balancer in front, size it for one long-lived WebSocket per connected Robot.

Storage#

  • Package storage. Every published package version is stored once. Budget for what you publish. The upload limit is 100 MB per package by default (Packages:MaxPackageSizeBytes) and can be raised to at most 512 MB.
  • Database growth. Jobs, execution logs, queue items, audit events and notifications grow until the retention sweep removes them. The defaults keep execution logs 30 days, jobs and queue items 90 days, and audit events 365 days. See Retention.
  • Traffic tables. Robot commands, domain events and webhook deliveries are kept in daily partitions and dropped a day at a time.

On one host, the local disk store is the simplest option. If you run more than one API process, use shared storage: an S3-compatible bucket, Azure Blob Storage, or a shared volume.

Robots#

Each machine runs one Robot. A machine's concurrency (maxConcurrentJobs) decides how many jobs it may run at once. For each Robot machine:

  • Keep at least 1 GiB of free disk plus twice the size of the largest package it prepares, or the Robot refuses jobs as DISK_FULL.
  • Plan for the package cache and per-attempt work folders under %ProgramData%\VeloPhex\Robot.

See System requirements for Robot and Studio machines.

A sizing checklist#

  1. Estimate peak job starts per minute and the number of Robots you will connect.
  2. Start with the minimum host for a pilot and one or two workspaces.
  3. Watch CPU, database connections and velophex.jobs.queue_depth while the pilot runs (see Observability).
  4. Move PostgreSQL to its own host or a managed service before the database becomes the bottleneck.
  5. If the fleet, not user traffic, drives the load, read Availability and recovery before you split roles.

Next steps#

Minimum host for Docker Compose

What the measurements say

Database connections

Connections at the front door

Storage

Robots

A sizing checklist

Next steps