> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment options

> Three ways to run xpander: on xpander cloud with nothing to deploy, as a Hybrid deployment with the runtime in your cluster and the control plane on xpander cloud, or air-gapped with every component in your environment

xpander runs in one of three places. On **xpander cloud** there is nothing to deploy: agents run on xpander's executors and Xpander Chat is [chat.xpander.ai](https://chat.xpander.ai). The two self-hosted deployments put the runtime in your own cluster and are installed by the same one-line installer:

* **Hybrid** (default): your data and agents run in your cluster, control plane in xpander cloud. The **Agent Controller** is the only cluster egress to Cloud: it pulls agent definitions and the skills catalog, and reports heartbeats (the heartbeat JSON schema is not published). Execution, runtime data, credentials, and model keys stay inside your VPC. See [Hybrid Architecture](/resources/security-compliance/security-architecture-hybrid).
* **Air-Gapped**: every component runs in your environment with no connection to xpander cloud at run time. UI, database, and every xpander service live in your cluster; two sealed, signed Ed25519 license files enforce entitlement in-cluster, and images are pulled from your own registry mirror. Nothing is sent to xpander Cloud; every other connection is optional and yours (the [egress table](/resources/security-compliance/air-gapped-deployments#what-leaves-the-environment) lists them). It installs in a cloud VPC in private mode (no internet or NAT gateways) or in any disconnected compute environment. See [Air-Gapped Architecture](/resources/security-compliance/air-gapped-deployments).

The reference installations run on Amazon EKS, and the supporting guides below are written for AWS. Any Kubernetes 1.28 or later with a CNI, cluster DNS and a CSI driver that provides a default RWO StorageClass meets the chart's requirements; no other distribution has a step-by-step guide here yet.

In **both** self-hosted deployments, agents' skill calls, including skills served over MCP, run from your cluster, and agent workspaces (the agents' computers) run there too. MCP clients (Claude, ChatGPT or Cursor connecting to Omni, the built-in agent) are offered once the install sets its MCP origin, `global.mcp.publicUrl`; until then Settings > Channels lists MCP as not configured.

In both self-hosted deployments, agents run on Claude Code, Codex or OpenCode, and their turns land on the **executor fleet**, a warm pool the chart always renders. Its sizing and node prerequisites are on [Sizing and requirements](/self-hosted/sizing).

```bash theme={"dark"}
curl -fsSL https://charts.xpander.ai/install.sh | bash
```

The installer's first question is which edition you are installing, and it walks you through the rest: run it from a terminal with `kubectl` access to the target cluster. Xpander Chat generates a personalized one-liner with everything filled in.

<CardGroup cols={2}>
  <Card title="Hybrid deployment" icon="rocket" href="/self-hosted/hybrid">
    The complete Hybrid guide: architecture, requirements, the installer wizard, PrivateLink, LLM keys, upgrades, troubleshooting
  </Card>

  <Card title="Air-gapped deployment" icon="shield-halved" href="/self-hosted/airgap">
    The complete Air-gapped guide: license, mirroring, the install pipeline, data tier, sign-in, upgrades, troubleshooting
  </Card>
</CardGroup>

Network boundary, identity, and what leaves each environment are on the architecture pages, one page per deployment:

<CardGroup cols={3}>
  <Card title="Cloud Architecture" icon="cloud" href="/resources/security-compliance/security-architecture-cloud">
    Hosted control plane and data plane
  </Card>

  <Card title="Hybrid Architecture" icon="network-wired" href="/resources/security-compliance/security-architecture-hybrid">
    Data plane in your VPC; catalog and heartbeat sync to Cloud
  </Card>

  <Card title="Air-Gapped Architecture" icon="wifi-slash" href="/resources/security-compliance/air-gapped-deployments">
    Every component in your environment; nothing sent to xpander
  </Card>
</CardGroup>

***

## Choosing a deployment

| | **Hybrid** (default) | **Air-Gapped** |
| - | - | - |
| **What runs in your cluster** | Execution plane: `agent-controller`, `agent-worker`, AI gateway, chat UI, API, MCP, code runner, Redis, PostgreSQL | Every component: everything in Hybrid **plus** the control plane services, the web UI, the Supabase stack, MongoDB, and the full data tier |
| **What runs in xpander cloud** | Control plane: environment metadata, agent definitions, skills catalog, user identity | Nothing |
| **Internet / network needs** | Outbound HTTPS to `deployment-manager.xpander.ai` (or [PrivateLink](/self-hosted/hybrid#privatelink)) and to your LLM providers | **No connection to xpander cloud at run time.** An LLM endpoint reachable in-network; other egress is optional and yours ([egress table](/resources/security-compliance/air-gapped-deployments#what-leaves-the-environment)) |
| **Helm chart** | `xpander` from `https://charts.xpander.ai` | `xpander-airgap` as an OCI artifact: `oci://registry-1.docker.io/xpanderaihub/xpander-airgap` |
| **Images pulled from** | Public registry | Your own registry mirror: the installer can [fill it for you](/self-hosted/airgap#when-the-mirror-is-empty-the-wizard-offers-to-fill-it) |
| **Identity / entitlement** | Organization ID + environment ID + deployment manager API key from Xpander Chat, embedded in the install one-liner | Two sealed, signed Ed25519 license files (`install.json` + `activation.json`, [two-file licensing](/self-hosted/licensing)) plus the organization id passed as `--org`; no console IDs or API key. Older installs use one signed `license.json` that carries the org id itself |
| **Minimum footprint** | 3 nodes × 8 vCPU / 32 GiB, \~50 GiB PVC | 5 nodes × 16 vCPU / 64 GiB, 300–500 GiB PVC (RWO StorageClass) |
| **Kubernetes** | ≥ 1.28, amd64 | ≥ 1.28, amd64 (optional GPU node for voice / local inference) |
| **Sign-in** | xpander Cloud identity at `chat.xpander.ai` | In-cluster auth: bootstrap admin password, email OTP, or [SSO with your OIDC identity provider](/self-hosted/sso) |
| **Upgrades** | `install.sh upgrade` (chart repo) | Mirror the new image bundle first, then `install.sh upgrade` by hand or a [declarative re-install](/self-hosted/airgap#declarative-re-install-for-ci) from CI |
| **Guide** | [Hybrid deployment](/self-hosted/hybrid) | [Air-gapped deployment](/self-hosted/airgap) |

The full requirements are published as JSON at [charts.xpander.ai/requirements.json](https://charts.xpander.ai/requirements.json). The installer shows the same numbers before it changes anything.

**Choose Hybrid** when you need data residency (runtime data, credentials, and model keys inside your network) but are fine with xpander cloud managing agent definitions, identity, and the skills catalog. It is the smaller footprint and the default. See [Hybrid Architecture](/resources/security-compliance/security-architecture-hybrid).

**Choose Air-Gapped** when xpander must run with zero dependency on xpander cloud: sealed or classified networks, strict egress policies, or full operational ownership. "Air-gapped" means air-gapped from xpander's cloud: internet-backed skills can stay enabled or be sealed off, your choice. See [Air-Gapped Architecture](/resources/security-compliance/air-gapped-deployments).

***

## Supporting Guides

<CardGroup cols={2}>
  <Card title="EKS Cluster Setup" icon="server" href="/self-hosted/eks-setup">
    Provision a new EKS cluster with VPC, IAM, nodes, and add-ons
  </Card>

  <Card title="AWS Operator Setup" icon="aws" href="/self-hosted/aws-operator">
    IAM roles and Pod Identity for AWS skills
  </Card>

  <Card title="IAM Best Practices" icon="shield-halved" href="/self-hosted/iam-best-practices">
    Three-tier IAM role architecture for least privilege
  </Card>

  <Card title="Sizing and requirements" icon="microchip" href="/self-hosted/sizing">
    Base footprint per deployment, the workspace pod, the executor fleet, capacity planning
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.