Hybrid Security Architecture

In the Hybrid edition, your data and agents run in your cluster and the control plane runs in xpander Cloud. Every task executes inside your VPC; the cluster initiates outbound TLS on port 443 to the control plane, and xpander Cloud never opens a connection into your environment. No inbound firewall rules are required for xpander. The design principles behind this page — permission model, credential isolation, encryption, safety controls — are on the Security Architecture page. The Air-Gapped edition removes the Cloud connection entirely.

Network boundary

AWS architecture of the xpander Hybrid edition. Left: users reach the cluster over a corporate VPN into the private subnet, or optionally through an Internet gateway and NLB. AZ A private subnet runs EKS, the Agent Controller, workers, and the AI Gateway. AZ B holds RDS, ElastiCache, and KMS. A VPC endpoint connects over PrivateLink to xpander Cloud. The deployment manager receives the cluster identity and health status and serves agent configuration and the connector tool schema. LLM providers and target APIs are reached from the VPC via NAT. — Hybrid edition on AWS. Left: your data plane — corporate VPN into the private subnet, or optional Internet + NLB. Right: xpander Cloud. The PrivateLink sync carries cluster identity, health status, agent configuration, and the connector tool schema. Draw.io source: /images/security/hybrid-aws-architecture.drawio

How to read the diagram:

Users reach your cluster two ways. Corp VPN is the company network path into the private subnet (chat, API, Agent Controller) — no public NLB required. See VPN / corporate network access. Internet is the optional public path through the Internet gateway and NLB.
Your VPC spans two Availability Zones. Public subnets hold the NLB and NAT gateways. Private subnets hold EKS (AZ A) and data stores (AZ B).
xpander Cloud — Workbench, identity, agent registry, and connector catalog. Agent configuration is authored here and synced into your cluster. AI Engineers sign in to Workbench; that path is browser-to-Cloud, not cluster egress.
PrivateLink — the Agent Controller reaches Cloud through the Endpoint svc and Deploy mgr. The connection carries the cluster’s identity (organization and environment IDs with the API key), health status, agent configuration, and the connector tool schema. Each is detailed in Data that leaves the on-prem installation.
Your models and tools sit outside the VPC and are reached from it via NAT.

Two outbound paths to the control plane:

Option	Target	Notes
Public TLS	`15.197.85.80`, `166.117.85.46`	Encrypted over public internet. Endpoint: `https://deployment-manager.xpander.ai`
AWS PrivateLink	`com.amazonaws.vpce.us-west-2.vpce-svc-0101884b32f655197`	AWS private backbone. Private DNS: `deployment-manager-privatelink.xpander.ai`. Endpoint security group allows TCP 443 from your VPC CIDR. See PrivateLink setup.

Supported PrivateLink regions: us-west-2, us-west-1, eu-west-2, eu-central-1, ap-south-1. The service itself is in us-west-2 (pass --service-region us-west-2 when creating the VPC endpoint from another region).

Authentication flow

Sign-in is the one flow that talks to xpander Cloud directly — and it carries identity, not work.

The AI Engineer signs in at chat.xpander.ai (SAML 2.0 SSO on enterprise plans).
The console tells the browser which self-hosted cluster to use.
Chat, tasks, and results move between the browser and your cluster. Chat content and task data are not part of the sign-in exchange.

Agent runtime flow

The prompt path — what happens when a user sends a task to an agent — runs inside your cluster.

The user’s prompt enters through your ingress to the cluster’s Chat/API services, then the Agent Controller and Workers.
Workers call your configured LLM providers; the AI Gateway calls target APIs. Both leave your VPC via NAT.
Threads, task state, and results are written to your cluster’s PostgreSQL.
Prompts, completions, and tool data are not sent to xpander Cloud.

Data that leaves the on-prem installation

Below is the Hybrid data-plane → xpander Cloud surface. It covers only fields documented in the Hybrid, Self-Hosted overview, Air-Gapped, and access control pages, plus the public shapes those pages point at (agent list, connector tool schema, MCP attach payload).

What does not leave

These stay in your cluster. They are not sent to xpander Cloud:

Data	Where it stays
Agent invocations and task payloads	Client → your Agent Controller / API
Chat threads and the activity / Monitor view	PostgreSQL in your cluster
Knowledge-base file uploads and queries	Your vector store
Tool results and connector responses	AI Gateway and workers in your cluster
Credentials, OAuth tokens, LLM API keys, IAM session credentials	Kubernetes secrets (and optional AWS Secrets Manager in your account)
Customer content (messages, documents, embeddings)	PostgreSQL / Redis / PVCs on encrypted EBS
Audit logs of tool calls, data access, and configuration changes	PostgreSQL in your cluster. See Access Control.

Model calls you configure (OpenAI, Anthropic, Bedrock, and so on) and connector calls to your systems leave your VPC toward those systems. They do not transit xpander Cloud.

How the cluster talks to Cloud

The Agent Controller is the only Hybrid component that reaches xpander Cloud. It authenticates with organization_id + environment_id + the deployment-manager API key, reports heartbeats, and pulls agent, connector, and MCP configuration. Other pods (workers, gateway, API, MCP, chat) do not call Cloud. Workbench login is not cluster egress. Users sign in at chat.xpander.ai (SSO on enterprise plans). The cloud UI then tells the browser which self-hosted cluster to use; chat, tasks, and debugging traffic go client-to-cluster. Cloud Controls in the locations console (Chat, Streaming, Scheduler) are feature toggles for the location. Their on-the-wire schema is not published; they do not carry runtime payloads.

1. Cluster identification

Sent on every control-plane request so the deployment manager can identify which cluster is calling.

Field	Where it is set	Leaves the cluster?
`organization_id`	Installer `--org` / Helm `global.organizationId`	Yes — UUID
`environment_id`	Installer `--env` / Helm `global.environmentId`	Yes — UUID
Deployment manager API key	Installer `--dm-api-key`, stored as `DEPLOYMENT_MANAGER_API_KEY`	Yes — presented as `x-api-key`. Rotate if exposed.

{
  "organization_id": "3f2a9c18-6b41-4e0d-9a55-0c8e1b7d2f30",
  "environment_id": "9d4e21aa-8c77-4b12-a601-5f3c0e9b18d4"
}

GET https://deployment-manager.xpander.ai/...
x-api-key: <DEPLOYMENT_MANAGER_API_KEY>

The API key value is never logged by the installer (typed secrets are placeholdered; Helm writes them to a mode-600 values file that is removed on exit).

2. Health status (heartbeats)

The Agent Controller reports heartbeats so the locations console can show Connection established and per-service status on the Components tab. The heartbeat JSON schema is not published. Public docs establish that heartbeats exist, are authenticated with the same organization / environment / API key, and that the console displays status per service. They do not document field names, intervals, or response bodies. Do not treat the following as a wire-format dump. It only restates what the console is documented to show:

{
  "organization_id": "3f2a9c18-6b41-4e0d-9a55-0c8e1b7d2f30",
  "environment_id": "9d4e21aa-8c77-4b12-a601-5f3c0e9b18d4",
  "comment": "Per-service heartbeat status is visible in the console Components tab. Request and response fields are not published."
}

Heartbeats do not include chat text, tool results, knowledge-base content, or credentials.

3. Agent metadata (stored in Cloud, pulled by the cluster)

Agent definitions are authored in the Workbench on xpander Cloud and pulled so your cluster knows which agent to load. This is catalog metadata — not invocations. The public List Agents response is the documented shape of that catalog. Example (redacted; no customer content):

{
  "items": [
    {
      "id": "7c4e1a90-2b33-4f18-9d6a-11e0c8a4b275",
      "name": "PR triage",
      "description": "Lists and labels pull requests in the platform repository",
      "icon": "🔎",
      "status": "ACTIVE",
      "organization_id": "3f2a9c18-6b41-4e0d-9a55-0c8e1b7d2f30",
      "deployment_type": "serverless",
      "created_at": "2026-03-12T14:02:11.104Z",
      "created_by": "b8e0d41f-0c22-4a91-9e17-6d2f0a11c883",
      "created_by_details": {
        "id": "b8e0d41f-0c22-4a91-9e17-6d2f0a11c883",
        "name": "Alex Rivera",
        "email": "alex.rivera@example.com"
      },
      "instructions": {
        "role": ["You are a pull-request triage assistant"],
        "goal": ["Label incoming PRs and summarize risk"],
        "general": "Only use the Jira and GitHub operations attached to this agent."
      },
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-4-5",
      "framework": "agno",
      "type": "regular",
      "llm_api_base": null,
      "has_pending_changes": false
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Field	Meaning
`id`, `name`, `description`, `icon`, `status`	Agent identity and deployment status (`ACTIVE` / `INACTIVE`)
`organization_id`	Owning org
`deployment_type`	`serverless` or `null`
`created_by` / `created_by_details`	Workbench user id, display name, email
`instructions`	Role, goal, and general instructions configured in Workbench
`model_provider`, `model_name`, `llm_api_base`	Which model the agent is configured to use — not the prompt or completion
`framework`, `type`	Runtime (`agno`, …) and agent type (`manager`, `regular`, …)

The cluster’s request that fetches this list carries the cluster identification headers only. Thread text, tool outputs, and knowledge-base hits are not part of this catalog.

4. Connector tool schema (pulled)

The connector catalog lives in Cloud. Your cluster pulls each tool as an LLM function-call definition — the operation’s name, description, and parameter schema — not the tokens used to call those APIs. Tokens stay in Kubernetes secrets and are injected by the AI Gateway at invocation time. A stored tool definition (redacted; Jira list-issues):

{
  "type": "function",
  "function": {
    "name": "list_issues",
    "description": "List issues in a Jira project",
    "parameters": {
      "type": "object",
      "properties": {
        "query_params": {
          "type": "object",
          "description": "Query parameters to include in the request to the tool",
          "additionalProperties": false,
          "properties": {
            "jql": { "type": "string", "description": "JQL query" },
            "maxResults": { "type": "integer" }
          },
          "required": ["jql"]
        },
        "path_params": {
          "type": "object",
          "description": "Path parameters to include in the request to the tool",
          "additionalProperties": false,
          "properties": {},
          "required": []
        },
        "body_params": {
          "type": "object",
          "description": "Body parameters to include in the request payload to the tool",
          "additionalProperties": false,
          "properties": {},
          "required": []
        }
      },
      "required": ["query_params", "path_params", "body_params"]
    }
  }
}

Field	Meaning
`function.name`	The operation on the agent’s surface (for example `list_issues`, not org-admin APIs)
`function.description`	What the operation does — shown to the model
`parameters.query_params` / `path_params` / `body_params`	JSON Schema for the arguments the model may fill in

Connector-level general parameters that carry preset values are stripped from this schema before it is stored, so the definition describes the call shape only. Credentials, connection tokens, and invocation results are never part of it.

5. MCP configuration (pulled)

MCP servers registered for the agent are pulled with the rest of the agent definition. Documented attach payloads from Add Agent Tool:

{
  "type": "mcp",
  "mcp_id": "6e2c0b14-9a88-4d21-b705-0f3a91c8e442"
}

{
  "type": "mcp",
  "name": "internal-docs",
  "url": "https://mcp.internal.example.com",
  "transport": "streamable-http"
}

Field	Meaning
`mcp_id`	Organization MCP registry entry
`name`	Display name for an inline server
`url`	Server URL (your endpoint, not xpander Cloud)
`transport`	`streamable-http`, `sse`, or `stdio`

MCP invocations and tool results run from your cluster’s MCP service. They do not go to xpander Cloud. Hybrid sign-in is xpander Cloud identity (chat.xpander.ai), including SAML 2.0 SSO on enterprise plans. That traffic is the user’s browser to Cloud, not the Agent Controller. What Cloud holds for a Workbench user (same created_by_details shape as agent metadata):

{
  "id": "b8e0d41f-0c22-4a91-9e17-6d2f0a11c883",
  "name": "Alex Rivera",
  "email": "alex.rivera@example.com"
}

After authentication, the UI directs the client to your cluster. Chat threads, Monitor data, and task results are fetched from your PostgreSQL — they do not pass through Cloud.

Self-hosted SDK calls use the Agent Controller API key issued at install time, not your xpander Cloud API key. See Using the SDK with Self-Hosted.

Security Architecture

Permission model, credential isolation, encryption, and safety controls

Hybrid Edition Guide

Installer, PrivateLink, sizing, and data residency table

Air-Gapped Architecture

The full platform in your environment, zero egress to xpander

Access Control

RBAC, SSO, API keys, and in-cluster audit logs

Overview

Platform

Getting Started

Building Agents

Workflows

Agentic Automation

Observability

Deployment Channels

Self-Hosted

Security & Compliance

Building In-Product Agents

Hybrid Security Architecture

Network boundary

Authentication flow

Agent runtime flow

Data that leaves the on-prem installation

What does not leave

How the cluster talks to Cloud

1. Cluster identification

2. Health status (heartbeats)

3. Agent metadata (stored in Cloud, pulled by the cluster)

4. Connector tool schema (pulled)

5. MCP configuration (pulled)

Security Architecture

Hybrid Edition Guide

Air-Gapped Architecture

Access Control

​Network boundary

​Authentication flow

​Agent runtime flow

​Data that leaves the on-prem installation

​What does not leave

​How the cluster talks to Cloud

​1. Cluster identification

​2. Health status (heartbeats)

​3. Agent metadata (stored in Cloud, pulled by the cluster)

​4. Connector tool schema (pulled)

​5. MCP configuration (pulled)

​6. Workbench login identity (browser → Cloud)

​Related

Security Architecture

Hybrid Edition Guide

Air-Gapped Architecture

Access Control

Network boundary

Authentication flow

Agent runtime flow

Data that leaves the on-prem installation

What does not leave

How the cluster talks to Cloud

1. Cluster identification

2. Health status (heartbeats)

3. Agent metadata (stored in Cloud, pulled by the cluster)

4. Connector tool schema (pulled)

5. MCP configuration (pulled)

6. Workbench login identity (browser → Cloud)

Related