Hybrid Security Architecture

Your data and agents run in your cluster. The control plane runs in xpander Cloud. The cluster opens outbound TLS on port 443 from the Agent Controller, and xpander Cloud never connects in, so no inbound firewall rules are needed. Prompts, completions, skill data, threads, task results and skill credentials never cross. The runtime controls are on Security Architecture. Air-Gapped 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, with 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.

Part	What it is
Users	Reach the private subnet over Corp VPN with no public NLB (VPN access), or optionally over the Internet 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.
PrivateLink	The Agent Controller reaches Cloud through the Endpoint svc and Deploy mgr, carrying only what leaves the installation.
Your models and target APIs	Outside the VPC, reached via NAT

The 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 only flow from the browser to xpander Cloud. It carries identity, not work.

The user signs in at chat.xpander.ai (SSO over OIDC on enterprise plans). xpander Chat then points the browser at your cluster, and chat, tasks and results move between the browser and your cluster only.

Agent runtime flow

The prompt path runs inside your cluster.

The prompt enters through your ingress to Chat/API, then the Agent Controller and the execution tier (agent-worker). Agents run on Claude Code, Codex or OpenCode on the executor fleet.
Model calls go through the in-cluster LLM Gateway, always on, with the organization’s or the install’s key. A call with neither key is refused with a message that names it. New runs wait for a healthy gateway.
The skill relay calls target APIs. Model and skill calls leave your VPC via NAT, never through xpander Cloud.
Threads, task state and results go to your cluster’s PostgreSQL.

Data that leaves the on-prem installation

Everything the Hybrid data plane sends to xpander Cloud, using only documented fields and public shapes. See also Hybrid deployment, Deployment options, Air-gapped deployment and access control.

What does not leave

Data	Where it stays
Agent invocations and task payloads	Client → your Agent Controller / API
Chat threads and task activity	PostgreSQL in your cluster
LLM Gateway request records for your agents’ model calls	Your cluster. Coding tools that people point at `https://llm-gw.xpander.ai` are recorded in xpander cloud (LLM Gateway)
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, connector OAuth tokens, LLM API keys, IAM session credentials	Kubernetes secrets (and optional AWS Secrets Manager in your account). Per-person MCP sign-in tokens are the exception: see below
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.

How the cluster talks to Cloud

Only the Agent Controller 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) never call Cloud. Each location also has feature toggles (Verify the Connection), which carry no runtime payloads.

1. Cluster identification

Sent on every control-plane request.

Field	Where it is set	Leaves the cluster?
`organization_id`	Installer `--org` / Helm `global.organizationId`	Yes, a UUID
`environment_id`	Installer `--env` / Helm `global.environmentId`	Yes, a 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 installer never logs the API key. Helm writes typed secrets to a mode-600 values file that is removed on exit.

2. Health status (heartbeats)

Heartbeats drive Connection established and per-service status in Platform > Agents > Runtime > Locations. They use the same credentials. The schema is not published, so the example only restates what xpander Chat shows, not the wire format:

{
  "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 Cloud and pulled as catalog metadata, not invocations. The shape is the public List Agents response, redacted:

{
  "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": "external-harness",
      "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 (`external-harness`) and agent type (`manager`, `regular`, …)

The request carries only the cluster identification headers.

4. Skill schema (pulled)

Each skill operation is pulled as a function-call definition: name, description and parameter schema, never the tokens. Connector tokens stay in Kubernetes secrets (per-person MCP tokens: below). Redacted Jira example:

{
  "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

Preset skill parameters are stripped before storage, so the definition is the call shape only.

5. MCP configuration (pulled)

MCP endpoints are pulled with the agent definition. 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 calls and results run from your cluster’s MCP service straight to your server, including servers with per-person sign-in. Only the person’s token comes from xpander Cloud. On Hybrid, per-person sign-in for MCP connectors runs in xpander Cloud. The chart has no sign-in service.

Step	Where it runs	What crosses to xpander Cloud
The person signs in	The person’s browser, your identity provider and xpander Cloud’s sign-in service (`client-auth.xpander.ai`)	The authorization code and the tokens your identity provider issues
Token storage and refresh	xpander Cloud’s vault, keyed by organization, server and person	Cloud calls your identity provider’s token endpoint to refresh
A run needs the token	The Agent Controller asks xpander Cloud for the person’s current access token	The access token, Cloud to cluster
The MCP call	Your cluster, straight to your MCP server	Nothing. Tool arguments and results stay in your cluster

xpander Cloud therefore holds each person’s access and refresh tokens for your identity provider. If your IdP or MCP connector must not be internet-reachable, or tokens must stay in your network, use Air-Gapped. Sign-in is browser to Cloud, not cluster egress (see Authentication flow). Cloud holds this for each user, the same created_by_details shape as agent metadata:

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

Next steps

Review the runtime controls

Permissions, credentials, safety

Install a Hybrid deployment

Installer and PrivateLink

Compare with Air-Gapped

Zero egress

Set up access control

RBAC, SSO, audit

Govern

LLM Gateway

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)

Next steps

Review the runtime controls

Install a Hybrid deployment

Compare with Air-Gapped

Set up 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)

​Per-person MCP sign-in tokens

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

​Next steps

Review the runtime controls

Install a Hybrid deployment

Compare with Air-Gapped

Set up 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)

Per-person MCP sign-in tokens

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

Next steps