Hybrid Security Architecture

In the Hybrid deployment, 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 deployment removes the Cloud connection entirely.

Network boundary

AWS architecture of the xpander Hybrid deployment. 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, the execution tier, 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 skill schema. LLM providers and target APIs are reached from the VPC via NAT. — Hybrid deployment 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 skill schema.

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 - Xpander Chat, identity, agent registry, and the skills catalog. Agent configuration is authored here and synced into your cluster. AI Engineers sign in to Xpander Chat; 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 skill schema. Each is detailed in Data that leaves the on-prem installation.
Your models and target APIs (the systems behind your skills) 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 (SSO over OIDC on enterprise plans).
Xpander Chat 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 the execution tier (the agent-worker service). New agents run on Claude Code, Codex or OpenCode on the executor fleet; their model calls go through the Agent Controller’s LLM proxy, the only component that reaches a model provider.
The execution tier calls your configured LLM providers; the Agent Controller’s skill relay calls target APIs. Both leave your VPC via NAT.
Threads, task state, and results are written to your cluster’s PostgreSQL.
Prompts, completions, and skill 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 deployment, Deployment options, Air-gapped deployment, and access control pages, plus the public shapes those pages point at (agent list, skill 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
Skill results and target-system responses	The skill relay and the execution tier 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 skill calls, data access, and configuration changes	PostgreSQL in your cluster. See Access Control.

Model calls you configure (OpenAI, Anthropic, Bedrock, and so on) and skill 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, skill, and MCP configuration. Other pods (agent-worker, gateway, API, MCP, chat) do not call Cloud. Sign-in to Xpander Chat 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. Settings > Locations in Xpander Chat also shows feature toggles for each connected cluster, called a location. Verify the Connection documents them. Their schema is not published, and they carry no 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 Settings > Locations in Xpander Chat 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 Xpander Chat 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 location's Components tab in the xpander app. Request and response fields are not published."
}

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

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

Agent definitions are authored in Xpander Chat 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`	Xpander Chat user id, display name, email
`instructions`	Role, goal, and general instructions configured in Xpander Chat
`model_provider`, `model_name`, `llm_api_base`	Which model the agent is configured to use - not the prompt or completion
`framework`, `type`	Harness (`agno`, …) and agent type (`manager`, `regular`, …)

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

4. Skill schema (pulled)

The skills catalog lives in Cloud. Your cluster pulls each skill operation 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 skill relay at invocation time. A stored function-call 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

Skill-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 endpoints registered for the agent are pulled with the rest of the agent definition. Documented attach payloads from the Add Agent Tool endpoint:

{
  "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 skill 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 SSO over OIDC on enterprise plans. That traffic is the user’s browser to Cloud, not the Agent Controller. What Cloud holds for an Xpander Chat 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 deployment Guide

Installer, PrivateLink, sizing, and data residency table

Air-Gapped Architecture

Every component in your environment, zero egress to xpander

Access Control

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

Govern

Deploy

Integrations

Licensing and identity

Security and compliance

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. Skill schema (pulled)

5. MCP configuration (pulled)

Security Architecture

Hybrid deployment 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. Skill schema (pulled)

​5. MCP configuration (pulled)

​6. Xpander Chat sign-in identity (browser → Cloud)

​Related

Security Architecture

Hybrid deployment 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. Skill schema (pulled)

5. MCP configuration (pulled)

6. Xpander Chat sign-in identity (browser → Cloud)

Related