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

# Locations and environments

> Where your agents run, and how to add, connect and switch locations.

A **location** is where xpander runs your agents. In xpander Chat, the location you are working against is your **environment**.

| Organization | Its locations |
| - | - |
| Cloud | Only the **xpander.ai cloud**, which xpander manages |
| **Hybrid** | The cloud, plus **self-hosted** clusters you connect with the Helm chart |
| **air-gapped** installation | Only its own clusters. No cloud location. |

A location says where the agent's computer runs. A [runtime environment](https://docs.xpander.ai/use/agents/runtime-environments.md) says what is installed on it.

## Manage locations

Admins manage locations in **Platform > Agents > Runtime**, on the **Locations** tab. Each row shows its type (**Managed** or **Self-hosted**), its status (**Connected**, **Checking**, **Unreachable** or **Setup incomplete**), and which one is the **Default** (change it with **Set as default**).

![Runtime page on the Locations tab with the main installation marked This installation and Default, status Connected](https://mintcdn.com/xpanderai-099931d1/wqIIXSsh0kqA2hZ_/images/verify/platform-runtime-locations.png?fit=max\&auto=format\&n=wqIIXSsh0kqA2hZ_\&q=85\&s=15b0d61c35736b3e5a62d53db526322f)

Platform > Agents > Runtime > Locations. Shown with sample data.

### Add a location

**Add location** depends on the organization:

* **Cloud organization:** you choose Hybrid (data and agents in your cluster, control plane in the xpander.ai cloud) or Air-gapped (everything in your environment, then no cloud location). Self-hosted locations depend on your plan, and the tab says if a plan change is needed.
* **Licensed installation** (already air-gapped): the dialog is **New remote location**. It asks only for a **Name**, an optional **Domain**, and **Use dash subdomains** (`chat-xpander.acme.com` instead of `chat.xpander.acme.com`). The new cluster joins your installation.

![Runtime page on the Locations tab with the New remote location panel open: Name, Domain (optional), Use dash subdomains, Cancel and Create location](https://mintcdn.com/xpanderai-099931d1/wqIIXSsh0kqA2hZ_/images/verify/locations-add-1.png?fit=max\&auto=format\&n=wqIIXSsh0kqA2hZ_\&q=85\&s=fbf27b6d3045f5f3d6f3111e352a766c)

Add location on a licensed installation: New remote location, with a name and an optional domain. Shown with sample data.

**1. Create the location**

**Create location** adds the row as **Setup incomplete**.

**2. Connect the cluster**

The row opens **Connect** with the system requirements, a one-line installer and a manual Helm install. See [Self-hosted](https://docs.xpander.ai/self-hosted/index.md), [Hybrid](https://docs.xpander.ai/self-hosted/hybrid.md) and [Air-gapped](https://docs.xpander.ai/self-hosted/airgap.md).

**3. Wait for it to report in**

The row turns **Connected**.

### Cloud controls and deleting a location

**Cloud controls** on a self-hosted row decide what that cluster exposes through the xpander.ai cloud:

| Control | Exposes |
| - | - |
| **Chat** | Talking to its agents through the cloud, including a relay when the cluster can't be reached directly |
| **Streaming** | Execution status and skill calls |
| **Scheduler** | Task scheduling from the cloud |

**Delete location** removes it. Agents assigned to it stop running there.

## Which location an agent runs in

An agent's location is set when it is created, with the **Environment** picker on the **New agent** form (the default is starred).

## Switching environments

With a connected self-hosted location, the profile menu gains an **Environments** section: **xpander.ai cloud** (**Managed**), or **Main** / **This installation** on a licensed installation, then each self-hosted location. Your choice sticks across visits. Until you pick, you start in the default location.

Agents work only in their own environment. Opening one from elsewhere shows a notice with a **Switch to** button.

### When a self-hosted environment is not connected

The row reads **Not connected**, with a hint to check your VPN. Then it depends on the location's **Chat** control:

| If **Chat** is | xpander Chat |
| - | - |
| Allowed | Keeps working through the xpander.ai cloud relay. The file browser is unavailable until you reconnect. |
| Not allowed | Blocks until you retry, switch environments, or an admin opens the location's settings |

## The cloud location in a Hybrid organization

Once a self-hosted location exists, the **Locations** tab shows an **Agents runtime** row with the switch "Allow agents to run on the xpander.ai cloud runtime." Turned off:

* Members work only with agents in your self-hosted locations.
* The cloud leaves the environment switcher and the **New agent** picker.
* New tasks on cloud agents are blocked, and a link to one asks an admin to re-enable it.

An air-gapped installation never shows this row.

## Next steps

> **[Install a self-hosted location](https://docs.xpander.ai/self-hosted/index.md)**
>
> Hybrid or Air-Gapped.

> **[Set up an agent's computer](https://docs.xpander.ai/use/agents/runtime-environments.md)**
>
> Runtime environments.


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