The turns of every Claude Code, Codex and OpenCode agent land on the fleet, however the agent was created. Two kinds of agent do not. An agent whose harness is xpander runs on the execution tier (
agent-worker), and on a workspace pod when it uses one. An SDK agent runs its loop in your own process.
Executor and workspace internals, node prerequisites, Landlock, autoscaling, rollouts, images and egress are on Runtime and node reference.
Base footprint
Hybrid
The installer shows the same minimums, published at charts.xpander.ai/requirements.json.
Size for tasks running concurrently at peak, whatever triggers them. In xpander cloud production only ~5% of executions are interactive chat. The rest come from schedules, webhooks, the API and other agents.
Capacity includes ~50% headroom over pod requests for bursts, system pods and node upgrades. Capacity and storage cover the base services and workspaces. Add the executor fleet on top: each executor requests 2 vCPU / 8 GiB and has a 500 GiB volume (see Capacity Planning).
Sizing calculator
Enter peak concurrent tasks, agents, and how many use a workspace.How the estimate works
How the estimate works
The calculator applies the same model we use to size xpander cloud:
- Concurrent tasks is the primary driver. A task is any agent execution, from any source: chat, API calls, schedules, webhooks, MCP clients, Slack, or another agent. If you don’t know your peak concurrency yet, assume one concurrent task per agent - that covers most production organizations we measured. In practice most teams peak at just a few concurrent tasks (typically under 5), and even the busiest organization peaks around 30.
- Execution replicas (
agent-worker) = concurrent tasks ÷ 4 (each replica processes 4 tasks by default, configurable withMAX_CONCURRENT_EXECUTIONS). Each replica requests 2 vCPU / 2.5 GiB. - Agent Controllers: 1 replica up to ~8 concurrent tasks, 2 up to ~20, 3 beyond. Each requests 1 vCPU / 2 GiB.
- Active workspaces = concurrent tasks × workspace share, capped at the agent count. Budget ~0.5 vCPU / 1 GiB per active workspace. That is the measured typical load, and each can burst to its 2 vCPU / 3 GiB limit.
- Fixed base (~3.75 vCPU / 11 GiB):
ai-gateway(registration only), MCP, Code Runner, AWS Operator, API, Redis, PostgreSQL, container registry and metrics-server at one replica each, plus the Company Brain’sbrain-ingest(1 vCPU / 4 GiB; drop it withbrain.enabled=false). Add the AI Gateway’s two pods (0.5 vCPU / 1 GiB requested each). - Cluster capacity = requests × 1.5 for burst, DaemonSets, and safe node drains. Storage = 68 GiB of chart volumes (48 GiB without the Company Brain) + 5 GiB per agent (an upper bound for workspace volumes; only an agent whose harness is xpander and that uses a workspace keeps one) + image cache per node.
- Executor fleet, where Claude Code, Codex and OpenCode turns run, is not in the estimate. Each executor requests 2 vCPU / 8 GiB and has a 500 GiB volume. Add it from Capacity Planning.
Per-service requirements
Per-service requirements
Per-replica values. Defaults are what the Helm chart applies out of the box. The recommended values raise the ones we found low against measured production usage.
Override any of these in your Helm values (keys are camelCase):
Air-Gapped
The full prerequisite list (network, license files, registry, tooling) is on Air-Gapped: Prerequisites.
Sizing tiers
Air-Gapped runs everything in-cluster: the execution tier (agent-worker) plus the control plane, the web UI, the Supabase stack (its own PostgreSQL 15, auth, storage, edge functions) and MongoDB.
Storage breakdown at the production tier
Storage breakdown at the production tier
External data tier and replica counts
External data tier and replica counts
External data tier. You can bring managed stores instead (Data Tier). A reference customer install uses:
- RDS PostgreSQL 16 on
db.t4g.smallwith 50 GiB gp3 - MemoryDB on
db.t4g.smallwith one shard and one replica - S3 as the Supabase Storage backend for blobs
agent-controller, agent-worker, api, agents and functions at ×2.Scaling with usage
The chart ships fixed replica counts and no autoscalers. Scaling policy is yours, and node capacity is the real ceiling.What grows, how to scale it, and node capacity
What grows, how to scale it, and node capacity
Node capacity is the real ceiling, because workspaces and code-execution Jobs create pods on demand. Two postures:
- Static capacity: size the node group for peak and leave it fixed. Simplest, fully offline, recommended for sealed networks.
- Cluster Autoscaler: adds nodes when pods can’t schedule. It works in a no-internet VPC if your cloud’s scaling API is reachable (on AWS, the
autoscalingandec2VPC endpoints).
Capacity planning
Plan in memory-backed executors: 10 slots on a 16 vCPU / 128 GiB node (for exampler6i.4xlarge), with executor memory raised so each turn’s 8 GiB is backed. The rest covers the kubelet, DaemonSets, the 4 GiB /dev/shm and the 20 GiB package cache.
Planning notes: slots, volumes, memory, smaller executors
Planning notes: slots, volumes, memory, smaller executors
- Slots, not agents. One executor serves many idle agents but runs at most
turnsMaxturns at once. Extra turns queue. - Agents per volume is a ceiling. Most directories stay far below the quota, and clones share one object store per repository, so a 500 GiB volume holds far more than 25 agents in practice.
- Memory headroom. Keep the executor’s limit at or below ~80 % of the node, and
turnsMax x 8 GiBwithin what the node can back. - Smaller executors are fine. On the defaults (8 vCPU / 28 GiB, 12 slots) one fits on a 16 vCPU / 32 GiB node, with the risk in the memory warning. Lower
turnsMaxto 3 or 4 for heavy builds. - Workspace pods are separate: 0.25 vCPU / 256 Mi request, up to 2 vCPU / 3 GiB while active. See Agent workspaces.
Data services and storage
The chart deploys single-replica Redis and PostgreSQL StatefulSets and a container registry alongside xpander:
Baseline storage: 68 GiB of persistent volumes (48 GiB with
brain.enabled=false) plus the 500 GiB agent volume per executor, plus the workspace volume of each workspace-using agent (Agent workspaces). All volumes use your cluster’s default StorageClass unless overridden.
Production checklist
Production checklist
Production checklist:
- Node types: x86_64 only. General-purpose instances with a 1:4 vCPU:GiB ratio (
m5,m6i) fit the workload profile.t3burstable instances are fine for evaluation, not for production. - Raise the low defaults: API memory (Per-service requirements) before real load.
- Enable autoscaling for the execution tier (
agent-worker) once concurrency grows beyond a couple of replicas. - Keep headroom: pod requests should stay under ~65% of cluster capacity so node upgrades and bursts don’t evict workloads.
- Storage class: SSD-backed volumes for Redis and PostgreSQL.
Air-Gapped vs Hybrid
How the executor fleet differs between the two charts.Fleet settings: Hybrid and Air-Gapped side by side
Fleet settings: Hybrid and Air-Gapped side by side
Next steps
Install Hybrid
The Hybrid installer.
Install Air-Gapped
The Air-Gapped installer.
Set up an EKS cluster
Nodes and StorageClasses.
Read the runtime and node reference
Executors, Landlock, rollouts and egress.
Understand two-file licensing
Seat and agent caps.

