> ## 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.

# Configure an air-gapped install

> Choose the data tier, set up the executor fleet, AI skill generation, custom actions and skill credentials on an air-gapped install.

The settings an air-gapped install needs beyond the [install](https://docs.xpander.ai/self-hosted/airgap-install.md) defaults. Models and the LLM endpoint are on [Models and local inference](https://docs.xpander.ai/self-hosted/airgap-models.md). Every value here goes in your values file; a complete one is the [Reference values file](https://docs.xpander.ai/self-hosted/airgap-upgrade.md#reference-values-file).

## Data tier: in-cluster or external

Choose carefully: moving from chart-managed StatefulSets to a managed service later is a migration. The wizard asks per store. Both default to in-cluster.

> [tab] In-cluster (default)
>
> Chart-managed StatefulSets on your StorageClass:
>
> * **PostgreSQL 16**: history, memory and per-agent databases
> * **Redis Stack** (`redis-stack-server`): queues, cache and knowledge-base vectors. Not plain Redis: knowledge bases use RediSearch (`FT.*`)
> * **MongoDB**: catalog and monitoring
> * Supabase ships its **own** pinned PostgreSQL 15 (it needs extensions managed services lack)
>
> No flags needed. `--storage-class <name>` picks a non-default class.

> [tab] External (RDS / MemoryDB)
>
> Bring your own PostgreSQL and/or a Valkey / MemoryDB cache with the search module. Interactively:
>
> ```bash theme={"dark"}
> bash install.sh --edition airgap ... \
>   --pg-mode external --pg-dsn 'postgresql://xpander:password@db.internal:5432/xpander' \
>   --redis-mode external --redis-endpoint <clustercfg endpoint, no port> \
>   --redis-tls --redis-cluster --redis-username <acl-user> --redis-password <pass>
> ```
>
> In a pipeline, put it in values and pass passwords with `--set`, never in Git:
>
> ```yaml theme={"dark"}
> postgres:
>   mode: external
>   external:
>     host: postgres.internal.acme.example
>     port: 5432
> redis:
>   mode: external
> global:
>   redis:
>     endpoint: <clustercfg endpoint, no port>
>     clusterMode: true
>     auth:
>       username: <acl-user>
> ```
>
> ```bash theme={"dark"}
> bash install.sh --edition airgap ... --values values.yaml \
>   --set keygen.overrides.POSTGRES_PASSWORD=<postgres password> \
>   --set global.redis.auth.password=<redis password>
> ```
>
> **Live connectivity probes.** Before installing, a probe pod runs `pg_isready` and `redis-cli ping` from your namespace. On failure, retry, continue (the pre-install hook re-checks) or abort with nothing changed. `--on-probe-failure retry|continue|abort` preselects. Non-interactive runs default to `abort` and exit with code 5.
>
> > [accordion] External store requirements: PostgreSQL, Valkey / MemoryDB, MongoDB, blob storage
> >
> > * **PostgreSQL**: create the role and database first. The role needs **`CREATEDB`** for per-agent databases:
> >
> >   ```sql theme={"dark"}
> >   CREATE ROLE xpander LOGIN PASSWORD '<password>' CREATEDB;
> >   CREATE DATABASE xpander OWNER xpander;
> >   ```
> >
> >   `keygen.overrides.POSTGRES_PASSWORD` overrides every generated value.
> > * **On RDS**, name the master user and initial database `xpander`: the master role already has `CREATEDB`, so no SQL is needed.
> > * **Valkey / MemoryDB** must serve **RediSearch (`FT.*`) commands**, or knowledge bases accept writes and return nothing.
> >   * On MemoryDB: **Valkey 7.3 on parameter group `default.memorydb-valkey7.search`**, chosen at creation (it cannot be added later).
> >   * An ACL user with `on ~* &* +@all`.
> >   * TLS (`--redis-tls`) and cluster mode (`--redis-cluster`). Encrypted MemoryDB and ElastiCache answer TLS only.
> >   * **One cluster per environment**: ACLs cannot split `FT.*` namespaces. Recreating it means re-ingesting knowledge-base vectors.
> >   * `--redis-username` / `--redis-password` for ACL auth, `--redis-port` if not 6379.
> >   * The chart adds a `redis` ExternalName Service, so service DNS stays the same.
> >   * Probe errors echo the endpoint's replies (`NOAUTH`, `WRONGPASS`).
> > * **MongoDB has no external mode** and Supabase's Postgres is **never external** (its migrations need extensions RDS lacks).
> > * **Blob storage**: Supabase Storage keeps uploads, attachments and live-surface assets on its own volume. No S3 backend. See [File storage](https://docs.xpander.ai/run/integrations/file-storage.md#object-storage).

## The executor fleet on Air-Gapped

Agent turns on Claude Code, Codex and OpenCode run on the executor fleet. Sizing: [Sizing and requirements](https://docs.xpander.ai/self-hosted/sizing.md). Its storage class: [Prerequisites](https://docs.xpander.ai/self-hosted/airgap.md#prerequisites). On Air-Gapped, check each concern below.

> [accordion] What to set for the fleet on Air-Gapped
>
> | Concern | What to set |
> | - | - |
> | **An LLM route** | CLIs never call a provider directly: calls go through the Agent Controller and the LLM Gateway. Preflight needs one route: an org default provider (`global.llm.defaults` or `global.llm.bedrock`), a gateway provider (`global.llm.gateway`), an in-cluster endpoint (`LLM_PROXY_<PROVIDER>_BASE_URL`, for example `LLM_PROXY_ANTHROPIC_BASE_URL`), or `global.fleet.llmProxyUrl`. With `global.network.internetEgress: false`, a leg with no override is refused |
> | **Which CLI, provider and model a new agent gets** | Explicit choices win. Otherwise the **organization's default LLM** (Anthropic: Claude Code, Bedrock with an Anthropic model: Claude Code on Bedrock, OpenAI: Codex, others: OpenCode), then `global.harness.defaultModels.{claudeCode,codex,opencode,xpander}` and `global.harness.defaultProviders.claudeCode` (chart 0.12.10+), then baked defaults. With neither, a Claude Code agent runs **Fable 5.1 over Anthropic direct** and needs an Anthropic key, or Bedrock declared instead |
> | **Bedrock auth** | `global.llm.bedrock.region`, then `bearerTokenSecret`, `assumeRoleArn` (+ `assumeRoleExternalId`), or nothing for Pod Identity / IRSA. `baseUrl` for the VPC endpoint. Fable- and Mythos-class models need the per-region data-retention opt-in on the signing account, including an organization's own Bedrock key account |
> | **The license** | The activation file must carry the fleet entitlement (`harness / containers`), or agent creation is refused |
> | **CLI versions with no registry** | Seal the CLIs on a connected machine (`python -m xpander_harness.cli_updates --root /tmp/cli bundle --out cli-bundle.tar.gz`), put the tarball on a PVC and set `global.fleet.cliBundle.enabled: true` with `global.fleet.cliBundle.pvc`. A post-install Job imports it |
> | **Capacity** | Fixed `global.fleet.replicas` for peak (sealed networks), or KEDA with `global.fleet.keda.enabled` after `image_sync.sh --with-keda` |
> | **Claude Code on Bedrock** | `global.harness.defaultProviders.claudeCode: amazon_bedrock` and `global.harness.defaultModels.claudeCode: <Bedrock model id>`, or the first turn fails with `503 no anthropic credential configured for harness agents` |
> | **Fleet volumes on on-demand storage** | `global.fleet.storage.createClass: true` with `global.fleet.storage.provisioner` set to your CSI driver (`ebs.csi.eks.amazonaws.com` on EKS Auto Mode) |

## AI skill generation

Upload an OpenAPI spec (`Connectors` → `Create connector`) and the `openapi-spec-generator` service turns it into a full skill in the background: grouping, naming, descriptions, summaries and validation. You can delete generated skills or upload a new spec version over one. The air-gap license carries the entitlement (`Custom connectors`), and the image is in the standard mirrored set.

The generator uses **exactly one LLM provider**, chosen at install: Bedrock if configured, else OpenAI if a key was given. It refuses runs without that provider's credentials. **With neither, it is not installed** and skill creation is **spec-only**, with no enrichment (`VITE_CONNECTOR_AI_ENRICHMENT` is set for you).

It writes specs to an object store bucket, set on **both** `catalog` and `openapi-spec-generator`, with **versioning enabled** (it lists object versions). Without the bucket, upload fails.

```yaml theme={"dark"}
catalog:
  env:
    OAS_GEN_BUCKET_NAME: <bucket>
    AWS_DEFAULT_REGION: <region>
openapi-spec-generator:
  env:
    OAS_GEN_BUCKET_NAME: <bucket>
    AWS_DEFAULT_REGION: <region>
```

> [!WARNING]
>
> On Bedrock, the generator follows `global.llm.bedrock.region`, falling back to **us-west-2**. Its default models are US cross-region profiles, so that region must be in the US, and IAM and PrivateLink must cover Bedrock there.

## Custom actions and code execution

Custom actions and code run in short-lived jobs from the `actions` service. To let them reach internal systems, give them the cluster's resolver:

```yaml theme={"dark"}
actions:
  env:
    XPANDER_SANDBOX_DNS: <ClusterIP of the CoreDNS Service>   # 172.20.0.10 on EKS; kubectl -n kube-system get svc kube-dns
```

The job image is xpander's sandbox image from your mirror. `api.env.SANDBOX_IMAGE` overrides it for a development stream. Agent code execution itself is switched at install with `--code-execution` / `--no-code-execution` ([Install](https://docs.xpander.ai/self-hosted/airgap-install.md#install-in-three-steps)).

## Skill credentials on Air-Gapped

Built-in skills that call a third-party service need a credential, or they fail with a 401:

* **RapidAPI skills** (for example Google News, Company Insights and Social Media): set `global.network.toolKeys.RAPID_API_KEY`, or calls return `401 Invalid API key`.
* **Skills with their own sign-in** (for example BigQuery and Figma): create the connection with valid credentials.
* **AWS skills** (Redshift, S3, Athena, EKS): the IAM role and its permissions on [AWS Operator Setup](https://docs.xpander.ai/self-hosted/aws-operator.md#air-gapped-installs).
* **Public skills** need internet egress, and do not work with `global.network.internetEgress: false`.


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