Skip to main content
A self-hosted install has three footprints: 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.
The calculator applies the same model we use to size xpander cloud:
  1. 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.
  2. Execution replicas (agent-worker) = concurrent tasks ÷ 4 (each replica processes 4 tasks by default, configurable with MAX_CONCURRENT_EXECUTIONS). Each replica requests 2 vCPU / 2.5 GiB.
  3. Agent Controllers: 1 replica up to ~8 concurrent tasks, 2 up to ~20, 3 beyond. Each requests 1 vCPU / 2 GiB.
  4. 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.
  5. 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’s brain-ingest (1 vCPU / 4 GiB; drop it with brain.enabled=false). Add the AI Gateway’s two pods (0.5 vCPU / 1 GiB requested each).
  6. 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.
  7. 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-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):
The AI Gateway (llm-gw) has a Horizontal Pod Autoscaler on by default. Agent Controller, ai-gateway, the execution tier (agent-worker) and MCP get one when you turn on their autoscaling values. An HPA needs metrics-server in the cluster. GKE and AKS install it. Amazon EKS does not: add the Metrics Server community add-on, and check with kubectl get deployment metrics-server -n kube-system. The chart’s metricsServer.enabled is for local clusters only.

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.
All are RWO, on one StorageClass. The chart’s preflight verifies it exists. You can bring managed stores instead of the in-cluster data tier.
External data tier. You can bring managed stores instead (Data Tier). A reference customer install uses:
  • RDS PostgreSQL 16 on db.t4g.small with 50 GiB gp3
  • MemoryDB on db.t4g.small with one shard and one replica
  • S3 as the Supabase Storage backend for blobs
With external stores, xpander’s PostgreSQL, Redis and storage PVCs above fall away.Most services run one replica. deployment-manager, actions and the Supabase edge runtime ship at ×2 with soft anti-affinity. For production, also run 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.
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 autoscaling and ec2 VPC endpoints).
Karpenter does not fit sealed networks: it fetches instance pricing from the internet.

Capacity planning

Plan in memory-backed executors: 10 slots on a 16 vCPU / 128 GiB node (for example r6i.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.
  • Slots, not agents. One executor serves many idle agents but runs at most turnsMax turns 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 GiB within 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 turnsMax to 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:
  • Node types: x86_64 only. General-purpose instances with a 1:4 vCPU:GiB ratio (m5, m6i) fit the workload profile. t3 burstable 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.

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.