# Air-gapped mode

> Run DataxLand on a network with no Internet access - the allow-list of hosts, the required NetworkPolicy, an in-house AI model, internal SMTP, features that turn off, data sources that still work and how to copy images into an internal registry.

Air-gapped mode is for installations that must not reach the Internet. When it is on, DataxLand only calls the hosts you list,
turns off the features that need an external host on its own, and tells you why.

DataxLand sends no telemetry back to DataxLand, air-gapped or not. The license is checked offline.

## 1. Turn on the mode and declare the allowed hosts

```yaml
airgapped:
  enabled: true
  egressAllow:
    - llm.corp.example        # exact name
    - smtp.corp.example
    - "*.db.corp.example"     # every subdomain of db.corp.example
    - 10.20.0.0/16            # address range (CIDR)
```

Each entry takes one of three forms:

| Form | Example | Matches |
| --- | --- | --- |
| Exact name | `llm.corp.example` | That name only |
| `*.suffix` | `*.db.corp.example` | `pg.db.corp.example`, `a.b.db.corp.example`; not `db.corp.example` itself |
| CIDR or IP | `10.20.0.0/16`, `10.20.1.5` | Hosts that resolve to an address in the range |

- Cloud metadata addresses and link-local (`169.254.0.0/16`) are **always blocked**, even when they are on the list.
- The AI model and SMTP are checked by **name** from the configuration at startup. List their host names (or IPs if they are
  configured by IP), not just a CIDR range.
- Even without air-gapped mode this list is useful: by default DataxLand refuses connections to internal addresses (SSRF
  protection), so a source database on your network must be in `egressAllow` before you can connect to it.

## 2. Block at the network level (required)

The in-app check is the second layer. Connector subprocesses don't carry the application's policy, so the primary layer has to
be the chart's NetworkPolicy and your firewall:

```yaml
networkPolicy:
  enabled: true
  egress:
    restrict: true
    dnsNamespace: kube-system
    allowCIDRs: [10.0.0.0/16, 10.20.0.0/16]   # Postgres, object storage, AI model, SMTP, source databases
    allowPorts: [5432, 443, 587, 1433, 3306, 8000]
```

Helm warns you when `airgapped.enabled` is on but `networkPolicy.egress.restrict` is off. Requires a CNI that supports
NetworkPolicy.

## 3. In-house AI model

The default model catalog in the image calls an external provider's API. In air-gapped mode every route must point to a model
whose host is in `egressAllow`; otherwise the application reports a configuration error at startup, naming the route and the
offending host.

Set your own catalog with `llm.modelsYaml`, using `openai_compat` models (vLLM, Ollama, LM Studio, TGI):

```yaml
llm:
  modelsYaml: |
    models:
      internal-qwen:
        provider: openai_compat
        base_url: http://llm.corp.example:8000/v1     # vLLM
        model: Qwen/Qwen3-32B
        api_key_env: INTERNAL_LLM_API_KEY             # key in the dataxland-env Secret; null if not needed
        capabilities: [structured_output, tool_use]
        region: local
      internal-ollama:
        provider: openai_compat
        base_url: http://ollama.corp.example:11434/v1 # Ollama
        model: qwen3:32b
        api_key_env: null
        capabilities: [structured_output, tool_use]
        region: local
    routes: {copilot: internal-qwen, agent: internal-qwen}
```

- The `copilot` route (Si analysing your data context) needs a model with `structured_output`; the `agent` route (Si answering
  questions) needs `tool_use`.
- Only declare capabilities the model really handles well. The quality of Si's answers depends on the model you choose; test it
  on your own data before rolling it out.
- `llm.copilotModel` and `llm.agentModel` pick a model by its catalog name without editing `routes`.

## 4. Email through internal SMTP

```yaml
deployment:
  extraEnv:
    DX_SMTP_HOST: smtp.corp.example
    DX_SMTP_PORT: "587"
    DX_SMTP_USER: dataxland
    DX_SMTP_FROM: dataxland@corp.example
```

Put the password in the `DX_SMTP_PASSWORD` key of the Secret. In air-gapped mode, email is turned off if the SMTP host is not
in `egressAllow`.

## 5. Features that turn off

In air-gapped mode the following features turn off automatically when the hosts they need are not in `egressAllow`:

| Feature | Hosts needed |
| --- | --- |
| Google sign-in | `accounts.google.com`, `oauth2.googleapis.com` |
| Turnstile CAPTCHA | `challenges.cloudflare.com` |
| Shopee, TikTok Shop, Lazada marketplace connections | The marketplace's API and login hosts |
| Telegram channel | `api.telegram.org` |
| Slack channel | `slack.com`, `hooks.slack.com` |
| Microsoft Teams channel | `login.microsoftonline.com`, `login.botframework.com`, `smba.trafficmanager.net` |
| Google Sheets | `sheets.googleapis.com`, `oauth2.googleapis.com` |
| Email | Your SMTP server |
| Trace export (OTLP) | The trace collector |

Every OAuth connection (marketplaces and the connector library) is **off by default** in air-gapped mode. To turn them on,
list them in `DX_OAUTH_PROVIDERS` under `deployment.extraEnv`; a marketplace still stays off if its hosts are not in
`egressAllow`.

See the actual list for your installation in **Admin → Operations**, section **Deployment and licence**: the outbound hosts allowed and each disabled feature with its reason. Or run:

```bash
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status
```

## 6. Data sources

By default, air-gapped mode keeps the sources that ship in the image and connect to hosts you enter: **Excel**,
**PostgreSQL**, **MySQL** and **SQL Server**. The database host must be in `egressAllow` and allowed by the NetworkPolicy.

BigQuery, the connector library and the Singer, dlt and Airbyte runtimes are only enabled when you set `DX_SOURCE_CONNECTORS`
in `deployment.extraEnv`, and each connection is still blocked if its host is not allowed. Airbyte connectors that install
from PyPI at run time, or manifest connectors that are not yet cached, cannot run air-gapped.

## 7. Copy images into an internal registry

The following are **already inside the `api` image** and never downloaded at run time: the embedding model, the DuckDB
extensions, and the Singer, dlt and Airbyte connector runtimes. You only need to copy the images.

On a machine with Internet access and [skopeo](https://github.com/containers/skopeo), from the DataxLand source bundle shipped
with the release:

```bash
# List the images
python -m tools.mirror_images list --tag <version> --owner <registry owner>

# Option 1: an internal registry reachable from this machine
python -m tools.mirror_images mirror --tag <version> --owner <registry owner> --to registry.corp.example/dataxland

# Option 2: package them to carry into the closed network
python -m tools.mirror_images bundle --tag <version> --owner <registry owner> --out ./dx-bundle
```

- The list covers the `api` image (shared by `worker`, `mcp` and the Jobs), `web`, `site`, plus the auxiliary images in the
  chart (trial Postgres and MinIO, s3proxy). `--with-build` adds the base images if you want to build images inside the closed
  network.
- Images are copied for both amd64 and arm64. `--dry-run` only prints the `skopeo` commands.
- `bundle` writes one `oci-archive` file per image, with `images.txt` (file, source image, target name) and `SHA256SUMS`. Inside
  the closed network, verify `SHA256SUMS`, then load each file:

```bash
skopeo copy oci-archive:<file>.tar docker://registry.corp.example/dataxland/<name>:<tag>
```

Then point the chart at the internal registry:

```yaml
image:
  registry: registry.corp.example
  repositoryPrefix: dataxland
```

If you use s3proxy or the trial Postgres and MinIO, also set `s3proxy.image`, `postgres.bundled.image` and `minio.image` to the
target names in `images.txt`.

## Related

- [Install with Helm](/en/docs/self-host/helm)
- [Requirements and sizing](/en/docs/self-host/requirements)
- [Offline license](/en/docs/self-host/license)
